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