src/lib/elm_general.h

   1    /**
   2     * @defgroup General General
   3     *
   4     * @brief General Elementary API. Functions that don't relate to
   5     * Elementary objects specifically.
   6     *
   7     * Here are documented functions which init/shutdown the library,
   8     * that apply to generic Elementary objects, that deal with
   9     * configuration, et cetera.
  10     *
  11     * @ref general_functions_example_page "This" example contemplates
  12     * some of these functions.
  13     */
  14
  15    /**
  16     * @addtogroup General
  17     * @{
  18     */
  19
  20    /**
  21     * Defines couple of standard Evas_Object layers to be used
  22     * with evas_object_layer_set().
  23     *
  24     * @note whenever extending with new values, try to keep some padding
  25     *       to siblings so there is room for further extensions.
  26     */
  27    typedef enum _Elm_Object_Layer
  28      {
  29         ELM_OBJECT_LAYER_BACKGROUND = EVAS_LAYER_MIN + 64, /**< where to place backgrounds */
  30         ELM_OBJECT_LAYER_DEFAULT = 0, /**< Evas_Object default layer (and thus for Elementary) */
  31         ELM_OBJECT_LAYER_FOCUS = EVAS_LAYER_MAX - 128, /**< where focus object visualization is */
  32         ELM_OBJECT_LAYER_TOOLTIP = EVAS_LAYER_MAX - 64, /**< where to show tooltips */
  33         ELM_OBJECT_LAYER_CURSOR = EVAS_LAYER_MAX - 32, /**< where to show cursors */
  34         ELM_OBJECT_LAYER_LAST /**< last layer known by Elementary */
  35      } Elm_Object_Layer;
  36
  37    /**************************************************************************/
  38    EAPI extern int ELM_ECORE_EVENT_ETHUMB_CONNECT;
  39
  40    /**
  41     * Emitted when the application has reconfigured elementary settings due
  42     * to an external configuration tool asking it to.
  43     */
  44    EAPI extern int ELM_EVENT_CONFIG_ALL_CHANGED;
  45
  46    /**
  47     * Emitted when any Elementary's policy value is changed.
  48     */
  49    EAPI extern int ELM_EVENT_POLICY_CHANGED;
  50
  51    /**
  52     * @typedef Elm_Event_Policy_Changed
  53     *
  54     * Data on the event when an Elementary policy has changed
  55     */
  56    typedef struct _Elm_Event_Policy_Changed Elm_Event_Policy_Changed;
  57
  58    /**
  59     * @struct _Elm_Event_Policy_Changed
  60     *
  61     * Data on the event when an Elementary policy has changed
  62     */
  63    struct _Elm_Event_Policy_Changed
  64      {
  65         unsigned int policy; /**< the policy identifier */
  66         int          new_value; /**< value the policy had before the change */
  67         int          old_value; /**< new value the policy got */
  68      };
  69
  70    /**
  71     * Policy identifiers.
  72     */
  73    typedef enum _Elm_Policy
  74      {
  75         ELM_POLICY_QUIT, /**< under which circumstances the application
  76                           * should quit automatically. @see
  77                           * Elm_Policy_Quit.
  78                           */
  79         ELM_POLICY_LAST
  80      } Elm_Policy; /**< Elementary policy identifiers/groups enumeration.  @see elm_policy_set() */
  81
  82    typedef enum _Elm_Policy_Quit
  83      {
  84         ELM_POLICY_QUIT_NONE = 0, /**< never quit the application
  85                                    * automatically */
  86         ELM_POLICY_QUIT_LAST_WINDOW_CLOSED /**< quit when the
  87                                             * application's last
  88                                             * window is closed */
  89      } Elm_Policy_Quit; /**< Possible values for the #ELM_POLICY_QUIT policy */
  90
  91    typedef enum _Elm_Focus_Direction
  92      {
  93         ELM_FOCUS_PREVIOUS,
  94         ELM_FOCUS_NEXT
  95      } Elm_Focus_Direction;
  96
  97    /**
  98     * @typedef Elm_Object_Item
  99     * An Elementary Object item handle.
 100     * @ingroup General
 101     */
 102    typedef struct _Elm_Object_Item Elm_Object_Item;
 103
 104    typedef Eina_Bool (*Elm_Event_Cb) (void *data, Evas_Object *obj, Evas_Object *src, Evas_Callback_Type type, void *event_info); /**< Function prototype definition for callbacks on input events happening on Elementary widgets. @a data will receive the user data pointer passed to elm_object_event_callback_add(). @a src will be a pointer to the widget on which the input event took place. @a type will get the type of this event and @a event_info, the struct with details on this event. */
 105
 106 #ifndef ELM_LIB_QUICKLAUNCH
 107 #define ELM_MAIN() int main(int argc, char **argv) {elm_init(argc, argv); return elm_main(argc, argv);} /**< macro to be used after the elm_main() function */
 108 #else
 109 #define ELM_MAIN() int main(int argc, char **argv) {return elm_quicklaunch_fallback(argc, argv);} /**< macro to be used after the elm_main() function */
 110 #endif
 111
 112 /**************************************************************************/
 113    /* General calls */
 114
 115    /**
 116     * Initialize Elementary
 117     *
 118     * @param[in] argc System's argument count value
 119     * @param[in] argv System's pointer to array of argument strings
 120     * @return The init counter value.
 121     *
 122     * This function initializes Elementary and increments a counter of
 123     * the number of calls to it. It returns the new counter's value.
 124     *
 125     * @warning This call is exported only for use by the @c ELM_MAIN()
 126     * macro. There is no need to use this if you use this macro (which
 127     * is highly advisable). An elm_main() should contain the entry
 128     * point code for your application, having the same prototype as
 129     * elm_init(), and @b not being static (putting the @c EAPI symbol
 130     * in front of its type declaration is advisable). The @c
 131     * ELM_MAIN() call should be placed just after it.
 132     *
 133     * Example:
 134     * @dontinclude bg_example_01.c
 135     * @skip static void
 136     * @until ELM_MAIN
 137     *
 138     * See the full @ref bg_example_01_c "example".
 139     *
 140     * @see elm_shutdown().
 141     * @ingroup General
 142     */
 143    EAPI int          elm_init(int argc, char **argv);
 144
 145    /**
 146     * Shut down Elementary
 147     *
 148     * @return The init counter value.
 149     *
 150     * This should be called at the end of your application, just
 151     * before it ceases to do any more processing. This will clean up
 152     * any permanent resources your application may have allocated via
 153     * Elementary that would otherwise persist.
 154     *
 155     * @see elm_init() for an example
 156     *
 157     * @ingroup General
 158     */
 159    EAPI int          elm_shutdown(void);
 160
 161    /**
 162     * Run Elementary's main loop
 163     *
 164     * This call should be issued just after all initialization is
 165     * completed. This function will not return until elm_exit() is
 166     * called. It will keep looping, running the main
 167     * (event/processing) loop for Elementary.
 168     *
 169     * @see elm_init() for an example
 170     *
 171     * @ingroup General
 172     */
 173    EAPI void         elm_run(void);
 174
 175    /**
 176     * Exit Elementary's main loop
 177     *
 178     * If this call is issued, it will flag the main loop to cease
 179     * processing and return back to its parent function (usually your
 180     * elm_main() function).
 181     *
 182     * @see elm_init() for an example. There, just after a request to
 183     * close the window comes, the main loop will be left.
 184     *
 185     * @note By using the appropriate #ELM_POLICY_QUIT on your Elementary
 186     * applications, you'll be able to get this function called automatically for you.
 187     *
 188     * @ingroup General
 189     */
 190    EAPI void         elm_exit(void);
 191
 192    /**
 193     * Exposed symbol used only by macros and should not be used by apps
 194     */
 195    EAPI void         elm_quicklaunch_mode_set(Eina_Bool ql_on);
 196
 197    /**
 198     * Exposed symbol used only by macros and should not be used by apps
 199     */
 200    EAPI Eina_Bool    elm_quicklaunch_mode_get(void);
 201
 202    /**
 203     * Exposed symbol used only by macros and should not be used by apps
 204     */
 205    EAPI int          elm_quicklaunch_init(int argc, char **argv);
 206
 207    /**
 208     * Exposed symbol used only by macros and should not be used by apps
 209     */
 210    EAPI int          elm_quicklaunch_sub_init(int argc, char **argv);
 211
 212    /**
 213     * Exposed symbol used only by macros and should not be used by apps
 214     */
 215    EAPI int          elm_quicklaunch_sub_shutdown(void);
 216
 217    /**
 218     * Exposed symbol used only by macros and should not be used by apps
 219     */
 220    EAPI int          elm_quicklaunch_shutdown(void);
 221
 222    /**
 223     * Exposed symbol used only by macros and should not be used by apps
 224     */
 225    EAPI void         elm_quicklaunch_seed(void);
 226
 227    /**
 228     * Exposed symbol used only by macros and should not be used by apps
 229     */
 230    EAPI Eina_Bool    elm_quicklaunch_prepare(int argc, char **argv);
 231
 232    /**
 233     * Exposed symbol used only by macros and should not be used by apps
 234     */
 235    EAPI Eina_Bool    elm_quicklaunch_fork(int argc, char **argv, char *cwd, void (postfork_func) (void *data), void *postfork_data);
 236
 237    /**
 238     * Exposed symbol used only by macros and should not be used by apps
 239     */
 240    EAPI void         elm_quicklaunch_cleanup(void);
 241
 242    /**
 243     * Exposed symbol used only by macros and should not be used by apps
 244     */
 245    EAPI int          elm_quicklaunch_fallback(int argc, char **argv);
 246
 247    /**
 248     * Exposed symbol used only by macros and should not be used by apps
 249     */
 250    EAPI char        *elm_quicklaunch_exe_path_get(const char *exe);
 251
 252    /**
 253     * Set a new policy's value (for a given policy group/identifier).
 254     *
 255     * @param policy policy identifier, as in @ref Elm_Policy.
 256     * @param value policy value, which depends on the identifier
 257     *
 258     * @return @c EINA_TRUE on success or @c EINA_FALSE, on error.
 259     *
 260     * Elementary policies define applications' behavior,
 261     * somehow. These behaviors are divided in policy groups (see
 262     * #Elm_Policy enumeration). This call will emit the Ecore event
 263     * #ELM_EVENT_POLICY_CHANGED, which can be hooked at with
 264     * handlers. An #Elm_Event_Policy_Changed struct will be passed,
 265     * then.
 266     *
 267     * @note Currently, we have only one policy identifier/group
 268     * (#ELM_POLICY_QUIT), which has two possible values.
 269     *
 270     * @ingroup General
 271     */
 272    EAPI Eina_Bool    elm_policy_set(unsigned int policy, int value);
 273
 274    /**
 275     * Gets the policy value for given policy identifier.
 276     *
 277     * @param policy policy identifier, as in #Elm_Policy.
 278     * @return The currently set policy value, for that
 279     * identifier. Will be @c 0 if @p policy passed is invalid.
 280     *
 281     * @ingroup General
 282     */
 283    EAPI int          elm_policy_get(unsigned int policy);
 284
 285    /**
 286     * Change the language of the current application
 287     *
 288     * The @p lang passed must be the full name of the locale to use, for
 289     * example "en_US.utf8" or "es_ES@euro".
 290     *
 291     * Changing language with this function will make Elementary run through
 292     * all its widgets, translating strings set with
 293     * elm_object_domain_translatable_text_part_set(). This way, an entire
 294     * UI can have its language changed without having to restart the program.
 295     *
 296     * For more complex cases, like having formatted strings that need
 297     * translation, widgets will also emit a "language,changed" signal that
 298     * the user can listen to to manually translate the text.
 299     *
 300     * @param lang Language to set, must be the full name of the locale
 301     *
 302     * @ingroup General
 303     */
 304    EAPI void         elm_language_set(const char *lang);
 305
 306    /**
 307     * Set the text for an objects' part, marking it as translatable.
 308     *
 309     * The string to set as @p text must be the original one. Do not pass the
 310     * return of @c gettext() here. Elementary will translate the string
 311     * internally and set it on the object using elm_object_part_text_set(),
 312     * also storing the original string so that it can be automatically
 313     * translated when the language is changed with elm_language_set().
 314     *
 315     * The @p domain will be stored along to find the translation in the
 316     * correct catalog. It can be NULL, in which case it will use whatever
 317     * domain was set by the application with @c textdomain(). This is useful
 318     * in case you are building a library on top of Elementary that will have
 319     * its own translatable strings, that should not be mixed with those of
 320     * programs using the library.
 321     *
 322     * @param obj The object containing the text part
 323     * @param part The name of the part to set
 324     * @param domain The translation domain to use
 325     * @param text The original, non-translated text to set
 326     *
 327     * @ingroup General
 328     */
 329    EAPI void         elm_object_domain_translatable_text_part_set(Evas_Object *obj, const char *part, const char *domain, const char *text);
 330
 331 #define elm_object_domain_translatable_text_set(obj, domain, text) elm_object_domain_translatable_text_part_set((obj), NULL, (domain), (text))
 332
 333 #define elm_object_translatable_text_set(obj, text) elm_object_domain_translatable_text_part_set((obj), NULL, NULL, (text))
 334
 335    /**
 336     * Gets the original string set as translatable for an object
 337     *
 338     * When setting translated strings, the function elm_object_part_text_get()
 339     * will return the translation returned by @c gettext(). To get the
 340     * original string use this function.
 341     *
 342     * @param obj The object
 343     * @param part The name of the part that was set
 344     *
 345     * @return The original, untranslated string
 346     *
 347     * @ingroup General
 348     */
 349    EAPI const char  *elm_object_translatable_text_part_get(const Evas_Object *obj, const char *part);
 350
 351 #define elm_object_translatable_text_get(obj) elm_object_translatable_text_part_get((obj), NULL)
 352
 353    /**
 354     * @}
 355     */
 356