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
  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
  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
  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
  92 {
  93    ELM_FOCUS_PREVIOUS,
  94    ELM_FOCUS_NEXT
  95 } Elm_Focus_Direction;
  96
  97 typedef enum
  98 {
  99    ELM_OBJECT_SELECT_MODE_DEFAULT = 0, /**< default select mode */
 100    ELM_OBJECT_SELECT_MODE_ALWAYS, /**< always select mode */
 101    ELM_OBJECT_SELECT_MODE_NONE, /**< no select mode */
 102    ELM_OBJECT_SELECT_MODE_DISPLAY_ONLY, /**< no select mode with no finger size rule*/
 103    ELM_OBJECT_SELECT_MODE_MAX
 104 } Elm_Object_Select_Mode;
 105
 106 /**
 107  * @typedef Elm_Object_Item
 108  * An Elementary Object item handle.
 109  * @ingroup General
 110  */
 111 typedef struct _Elm_Object_Item Elm_Object_Item;
 112
 113 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. */
 114
 115 #ifndef ELM_LIB_QUICKLAUNCH
 116 #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 */
 117 #else
 118 #define ELM_MAIN() int main(int argc, char **argv) {return elm_quicklaunch_fallback(argc, argv); } /**< macro to be used after the elm_main() function */
 119 #endif
 120
 121 /**************************************************************************/
 122 /* General calls */
 123
 124 /**
 125  * Initialize Elementary
 126  *
 127  * @param[in] argc System's argument count value
 128  * @param[in] argv System's pointer to array of argument strings
 129  * @return The init counter value.
 130  *
 131  * This function initializes Elementary and increments a counter of
 132  * the number of calls to it. It returns the new counter's value.
 133  *
 134  * @warning This call is exported only for use by the @c ELM_MAIN()
 135  * macro. There is no need to use this if you use this macro (which
 136  * is highly advisable). An elm_main() should contain the entry
 137  * point code for your application, having the same prototype as
 138  * elm_init(), and @b not being static (putting the @c EAPI_MAIN symbol
 139  * in front of its type declaration is advisable). The @c
 140  * ELM_MAIN() call should be placed just after it.
 141  *
 142  * Example:
 143  * @dontinclude bg_example_01.c
 144  * @skip static void
 145  * @until ELM_MAIN
 146  *
 147  * See the full @ref bg_example_01_c "example".
 148  *
 149  * @see elm_shutdown().
 150  * @ingroup General
 151  */
 152 EAPI int       elm_init(int argc, char **argv);
 153
 154 /**
 155  * Shut down Elementary
 156  *
 157  * @return The init counter value.
 158  *
 159  * This should be called at the end of your application, just
 160  * before it ceases to do any more processing. This will clean up
 161  * any permanent resources your application may have allocated via
 162  * Elementary that would otherwise persist.
 163  *
 164  * @see elm_init() for an example
 165  *
 166  * @ingroup General
 167  */
 168 EAPI int       elm_shutdown(void);
 169
 170 /**
 171  * Run Elementary's main loop
 172  *
 173  * This call should be issued just after all initialization is
 174  * completed. This function will not return until elm_exit() is
 175  * called. It will keep looping, running the main
 176  * (event/processing) loop for Elementary.
 177  *
 178  * @see elm_init() for an example
 179  *
 180  * @ingroup General
 181  */
 182 EAPI void      elm_run(void);
 183
 184 /**
 185  * Exit Elementary's main loop
 186  *
 187  * If this call is issued, it will flag the main loop to cease
 188  * processing and return back to its parent function (usually your
 189  * elm_main() function).
 190  *
 191  * @see elm_init() for an example. There, just after a request to
 192  * close the window comes, the main loop will be left.
 193  *
 194  * @note By using the appropriate #ELM_POLICY_QUIT on your Elementary
 195  * applications, you'll be able to get this function called automatically for you.
 196  *
 197  * @ingroup General
 198  */
 199 EAPI void      elm_exit(void);
 200
 201 /**
 202  * Exposed symbol used only by macros and should not be used by apps
 203  */
 204 EAPI void      elm_quicklaunch_mode_set(Eina_Bool ql_on);
 205
 206 /**
 207  * Exposed symbol used only by macros and should not be used by apps
 208  */
 209 EAPI Eina_Bool elm_quicklaunch_mode_get(void);
 210
 211 /**
 212  * Exposed symbol used only by macros and should not be used by apps
 213  */
 214 EAPI int       elm_quicklaunch_init(int argc, char **argv);
 215
 216 /**
 217  * Exposed symbol used only by macros and should not be used by apps
 218  */
 219 EAPI int       elm_quicklaunch_sub_init(int argc, char **argv);
 220
 221 /**
 222  * Exposed symbol used only by macros and should not be used by apps
 223  */
 224 EAPI int       elm_quicklaunch_sub_shutdown(void);
 225
 226 /**
 227  * Exposed symbol used only by macros and should not be used by apps
 228  */
 229 EAPI int       elm_quicklaunch_shutdown(void);
 230
 231 /**
 232  * Exposed symbol used only by macros and should not be used by apps
 233  */
 234 EAPI void      elm_quicklaunch_seed(void);
 235
 236 /**
 237  * Exposed symbol used only by macros and should not be used by apps
 238  */
 239 EAPI Eina_Bool elm_quicklaunch_prepare(int argc, char **argv);
 240
 241 /**
 242  * Exposed symbol used only by macros and should not be used by apps
 243  */
 244 EAPI Eina_Bool elm_quicklaunch_fork(int argc, char **argv, char *cwd, void (postfork_func) (void *data), void *postfork_data);
 245
 246 /**
 247  * Exposed symbol used only by macros and should not be used by apps
 248  */
 249 EAPI void      elm_quicklaunch_cleanup(void);
 250
 251 /**
 252  * Exposed symbol used only by macros and should not be used by apps
 253  */
 254 EAPI int       elm_quicklaunch_fallback(int argc, char **argv);
 255
 256 /**
 257  * Exposed symbol used only by macros and should not be used by apps
 258  */
 259 EAPI char     *elm_quicklaunch_exe_path_get(const char *exe);
 260
 261 /**
 262  * Set a new policy's value (for a given policy group/identifier).
 263  *
 264  * @param policy policy identifier, as in @ref Elm_Policy.
 265  * @param value policy value, which depends on the identifier
 266  *
 267  * @return @c EINA_TRUE on success or @c EINA_FALSE, on error.
 268  *
 269  * Elementary policies define applications' behavior,
 270  * somehow. These behaviors are divided in policy groups (see
 271  * #Elm_Policy enumeration). This call will emit the Ecore event
 272  * #ELM_EVENT_POLICY_CHANGED, which can be hooked at with
 273  * handlers. An #Elm_Event_Policy_Changed struct will be passed,
 274  * then.
 275  *
 276  * @note Currently, we have only one policy identifier/group
 277  * (#ELM_POLICY_QUIT), which has two possible values.
 278  *
 279  * @ingroup General
 280  */
 281 EAPI Eina_Bool elm_policy_set(unsigned int policy, int value);
 282
 283 /**
 284  * Gets the policy value for given policy identifier.
 285  *
 286  * @param policy policy identifier, as in #Elm_Policy.
 287  * @return The currently set policy value, for that
 288  * identifier. Will be @c 0 if @p policy passed is invalid.
 289  *
 290  * @ingroup General
 291  */
 292 EAPI int       elm_policy_get(unsigned int policy);
 293
 294 /**
 295  * Change the language of the current application
 296  *
 297  * The @p lang passed must be the full name of the locale to use, for
 298  * example "en_US.utf8" or "es_ES@euro".
 299  *
 300  * Changing language with this function will make Elementary run through
 301  * all its widgets, translating strings set with
 302  * elm_object_domain_translatable_text_part_set(). This way, an entire
 303  * UI can have its language changed without having to restart the program.
 304  *
 305  * For more complex cases, like having formatted strings that need
 306  * translation, widgets will also emit a "language,changed" signal that
 307  * the user can listen to to manually translate the text.
 308  *
 309  * @param lang Language to set, must be the full name of the locale
 310  *
 311  * @ingroup General
 312  */
 313 EAPI void      elm_language_set(const char *lang);
 314
 315 /**
 316  * Set the text for an objects' part, marking it as translatable.
 317  *
 318  * The string to set as @p text must be the original one. Do not pass the
 319  * return of @c gettext() here. Elementary will translate the string
 320  * internally and set it on the object using elm_object_part_text_set(),
 321  * also storing the original string so that it can be automatically
 322  * translated when the language is changed with elm_language_set().
 323  *
 324  * The @p domain will be stored along to find the translation in the
 325  * correct catalog. It can be NULL, in which case it will use whatever
 326  * domain was set by the application with @c textdomain(). This is useful
 327  * in case you are building a library on top of Elementary that will have
 328  * its own translatable strings, that should not be mixed with those of
 329  * programs using the library.
 330  *
 331  * @param obj The object containing the text part
 332  * @param part The name of the part to set
 333  * @param domain The translation domain to use
 334  * @param text The original, non-translated text to set
 335  *
 336  * @ingroup General
 337  */
 338 EAPI void      elm_object_domain_translatable_text_part_set(Evas_Object *obj, const char *part, const char *domain, const char *text);
 339
 340 #define elm_object_domain_translatable_text_set(obj, domain, text) elm_object_domain_translatable_text_part_set((obj), NULL, (domain), (text))
 341
 342 #define elm_object_translatable_text_set(obj, text)                elm_object_domain_translatable_text_part_set((obj), NULL, NULL, (text))
 343
 344 /**
 345  * Gets the original string set as translatable for an object
 346  *
 347  * When setting translated strings, the function elm_object_part_text_get()
 348  * will return the translation returned by @c gettext(). To get the
 349  * original string use this function.
 350  *
 351  * @param obj The object
 352  * @param part The name of the part that was set
 353  *
 354  * @return The original, untranslated string
 355  *
 356  * @ingroup General
 357  */
 358 EAPI const char *elm_object_translatable_text_part_get(const Evas_Object *obj, const char *part);
 359
 360 #define elm_object_translatable_text_get(obj) elm_object_translatable_text_part_get((obj), NULL)
 361
 362 /**
 363  * @}
 364  */