src/lib/elm_general.h

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