2 * @defgroup General General
5 * @brief General Elementary API. Functions that don't relate to
6 * Elementary objects specifically.
8 * Here are documented functions which init/shutdown the library,
9 * that apply to generic Elementary objects, that deal with
10 * configuration, et cetera.
12 * @ref general_functions_example_page "This" example contemplates
13 * some of these functions.
22 * Defines couple of standard Evas_Object layers to be used
23 * with evas_object_layer_set().
25 * @note whenever extending with new values, try to keep some padding
26 * to siblings so there is room for further extensions.
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 */
38 /**************************************************************************/
39 EAPI extern int ELM_ECORE_EVENT_ETHUMB_CONNECT;
42 * Emitted when the application has reconfigured elementary settings due
43 * to an external configuration tool asking it to.
45 EAPI extern int ELM_EVENT_CONFIG_ALL_CHANGED;
48 * Emitted when any Elementary's policy value is changed.
50 EAPI extern int ELM_EVENT_POLICY_CHANGED;
53 * @typedef Elm_Event_Policy_Changed
55 * Data on the event when an Elementary policy has changed
57 typedef struct _Elm_Event_Policy_Changed Elm_Event_Policy_Changed;
60 * @struct _Elm_Event_Policy_Changed
62 * Data on the event when an Elementary policy has changed
64 struct _Elm_Event_Policy_Changed
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 */
76 ELM_POLICY_QUIT, /**< under which circumstances the application
77 * should quit automatically. @see
80 ELM_POLICY_EXIT, /**< defines elm_exit() behaviour. @see Elm_Policy_Exit.
84 } Elm_Policy; /**< Elementary policy identifiers/groups enumeration. @see elm_policy_set() */
87 * Possible values for the #ELM_POLICY_QUIT policy
91 ELM_POLICY_QUIT_NONE = 0, /**< never quit the application
93 ELM_POLICY_QUIT_LAST_WINDOW_CLOSED /**< quit when the
99 * Possible values for the #ELM_POLICY_EXIT policy.
104 ELM_POLICY_EXIT_NONE = 0, /**< just quit the main loop on elm_exit() */
105 ELM_POLICY_EXIT_WINDOWS_DEL /**< delete all the windows after quitting
113 } Elm_Focus_Direction;
117 ELM_OBJECT_SELECT_MODE_DEFAULT = 0, /**< default select mode */
118 ELM_OBJECT_SELECT_MODE_ALWAYS, /**< always select mode */
119 ELM_OBJECT_SELECT_MODE_NONE, /**< no select mode */
120 ELM_OBJECT_SELECT_MODE_DISPLAY_ONLY, /**< no select mode with no finger size rule*/
121 ELM_OBJECT_SELECT_MODE_MAX
122 } Elm_Object_Select_Mode;
125 * @typedef Elm_Object_Item
126 * An Elementary Object item handle.
129 typedef struct _Elm_Object_Item Elm_Object_Item;
131 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. */
133 #ifndef ELM_LIB_QUICKLAUNCH
134 #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 */
136 #define ELM_MAIN() int main(int argc, char **argv) {return elm_quicklaunch_fallback(argc, argv); } /**< macro to be used after the elm_main() function */
139 /**************************************************************************/
143 * Initialize Elementary
145 * @param[in] argc System's argument count value
146 * @param[in] argv System's pointer to array of argument strings
147 * @return The init counter value.
149 * This function initializes Elementary and increments a counter of
150 * the number of calls to it. It returns the new counter's value.
152 * @warning This call is exported only for use by the @c ELM_MAIN()
153 * macro. There is no need to use this if you use this macro (which
154 * is highly advisable). An elm_main() should contain the entry
155 * point code for your application, having the same prototype as
156 * elm_init(), and @b not being static (putting the @c EAPI_MAIN symbol
157 * in front of its type declaration is advisable). The @c
158 * ELM_MAIN() call should be placed just after it.
161 * @dontinclude bg_example_01.c
165 * See the full @ref bg_example_01_c "example".
167 * @see elm_shutdown().
170 EAPI int elm_init(int argc, char **argv);
173 * Shut down Elementary
175 * @return The init counter value.
177 * This should be called at the end of your application, just
178 * before it ceases to do any more processing. This will clean up
179 * any permanent resources your application may have allocated via
180 * Elementary that would otherwise persist.
182 * @see elm_init() for an example
184 * @note elm_shutdown() will iterate main loop until all ecore_evas are freed.
185 * There is a possibility to call your ecore callbacks(timer, animator, event,
186 * job, and etc.) in elm_shutdown()
190 EAPI int elm_shutdown(void);
193 * Run Elementary's main loop
195 * This call should be issued just after all initialization is
196 * completed. This function will not return until elm_exit() is
197 * called. It will keep looping, running the main
198 * (event/processing) loop for Elementary.
200 * @see elm_init() for an example
204 EAPI void elm_run(void);
207 * Ask to exit Elementary's main loop
209 * If this call is issued, it will flag the main loop to cease
210 * processing and return back to its parent function (usually your
211 * elm_main() function). This does not mean the main loop instantly quits.
212 * So your ecore callbacks(timer, animator, event, job, and etc.) have chances
213 * to be called even after elm_exit().
215 * @see elm_init() for an example. There, just after a request to
216 * close the window comes, the main loop will be left.
218 * @note By using the appropriate #ELM_POLICY_QUIT on your Elementary
219 * applications, you'll be able to get this function called automatically for you.
223 EAPI void elm_exit(void);
226 * Exposed symbol used only by macros and should not be used by apps
228 EAPI void elm_quicklaunch_mode_set(Eina_Bool ql_on);
231 * Exposed symbol used only by macros and should not be used by apps
233 EAPI Eina_Bool elm_quicklaunch_mode_get(void);
236 * Exposed symbol used only by macros and should not be used by apps
238 EAPI int elm_quicklaunch_init(int argc, char **argv);
241 * Exposed symbol used only by macros and should not be used by apps
243 EAPI int elm_quicklaunch_sub_init(int argc, char **argv);
246 * Exposed symbol used only by macros and should not be used by apps
248 EAPI int elm_quicklaunch_sub_shutdown(void);
251 * Exposed symbol used only by macros and should not be used by apps
253 EAPI int elm_quicklaunch_shutdown(void);
256 * Exposed symbol used only by macros and should not be used by apps
258 EAPI void elm_quicklaunch_seed(void);
261 * Exposed symbol used only by macros and should not be used by apps
263 EAPI Eina_Bool elm_quicklaunch_prepare(int argc, char **argv);
266 * Exposed symbol used only by macros and should not be used by apps
268 EAPI Eina_Bool elm_quicklaunch_fork(int argc, char **argv, char *cwd, void (postfork_func) (void *data), void *postfork_data);
271 * Exposed symbol used only by macros and should not be used by apps
273 EAPI void elm_quicklaunch_cleanup(void);
276 * Exposed symbol used only by macros and should not be used by apps
278 EAPI int elm_quicklaunch_fallback(int argc, char **argv);
281 * Exposed symbol used only by macros and should not be used by apps
283 EAPI char *elm_quicklaunch_exe_path_get(const char *exe);
286 * Set a new policy's value (for a given policy group/identifier).
288 * @param policy policy identifier, as in @ref Elm_Policy.
289 * @param value policy value, which depends on the identifier
291 * @return @c EINA_TRUE on success or @c EINA_FALSE, on error.
293 * Elementary policies define applications' behavior,
294 * somehow. These behaviors are divided in policy groups
295 * (see #Elm_Policy enumeration). This call will emit the Ecore
296 * event #ELM_EVENT_POLICY_CHANGED, which can be hooked at with
297 * handlers. An #Elm_Event_Policy_Changed struct will be passed,
300 * @note Currently, we have only one policy identifier/group
301 * (#ELM_POLICY_QUIT), which has two possible values.
305 EAPI Eina_Bool elm_policy_set(unsigned int policy, int value);
308 * Gets the policy value for given policy identifier.
310 * @param policy policy identifier, as in #Elm_Policy.
311 * @return The currently set policy value, for that
312 * identifier. Will be @c 0 if @p policy passed is invalid.
316 EAPI int elm_policy_get(unsigned int policy);
319 * Change the language of the current application
321 * The @p lang passed must be the full name of the locale to use, for
322 * example "en_US.utf8" or "es_ES@euro".
324 * Changing language with this function will make Elementary run through
325 * all its widgets, translating strings set with
326 * elm_object_domain_translatable_text_part_set(). This way, an entire
327 * UI can have its language changed without having to restart the program.
329 * For more complex cases, like having formatted strings that need
330 * translation, widgets will also emit a "language,changed" signal that
331 * the user can listen to to manually translate the text.
333 * @param lang Language to set, must be the full name of the locale
337 EAPI void elm_language_set(const char *lang);
340 * Set the text for an objects' part, marking it as translatable.
342 * The string to set as @p text must be the original one. Do not pass the
343 * return of @c gettext() here. Elementary will translate the string
344 * internally and set it on the object using elm_object_part_text_set(),
345 * also storing the original string so that it can be automatically
346 * translated when the language is changed with elm_language_set().
348 * The @p domain will be stored along to find the translation in the
349 * correct catalog. It can be NULL, in which case it will use whatever
350 * domain was set by the application with @c textdomain(). This is useful
351 * in case you are building a library on top of Elementary that will have
352 * its own translatable strings, that should not be mixed with those of
353 * programs using the library.
355 * @param obj The object containing the text part
356 * @param part The name of the part to set
357 * @param domain The translation domain to use
358 * @param text The original, non-translated text to set
362 EAPI void elm_object_domain_translatable_text_part_set(Evas_Object *obj, const char *part, const char *domain, const char *text);
364 #define elm_object_domain_translatable_text_set(obj, domain, text) elm_object_domain_translatable_text_part_set((obj), NULL, (domain), (text))
366 #define elm_object_translatable_text_set(obj, text) elm_object_domain_translatable_text_part_set((obj), NULL, NULL, (text))
369 * Gets the original string set as translatable for an object
371 * When setting translated strings, the function elm_object_part_text_get()
372 * will return the translation returned by @c gettext(). To get the
373 * original string use this function.
375 * @param obj The object
376 * @param part The name of the part that was set
378 * @return The original, untranslated string
382 EAPI const char *elm_object_translatable_text_part_get(const Evas_Object *obj, const char *part);
384 #define elm_object_translatable_text_get(obj) elm_object_translatable_text_part_get((obj), NULL)