aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/elementary/elm_general.h
blob: 35701cfe47744bcfe85e96bee22b039c6e8d1890 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
/**
 * @defgroup Elm_General General
 * @ingroup Elementary
 *
 * @brief General Elementary API. Functions that don't relate to
 * Elementary objects specifically.
 *
 * Here are documented functions which init/shutdown the library,
 * that apply to generic Elementary objects, that deal with
 * configuration, et cetera.
 *
 * @ref general_functions_example_page "This" example contemplates
 * some of these functions.
 */

/**
 * @addtogroup Elm_General
 * @{
 */

#include "elm_general.eot.h"

#define ELM_FOCUS_PREVIOUS EFL_UI_FOCUS_DIRECTION_PREVIOUS
#define ELM_FOCUS_NEXT EFL_UI_FOCUS_DIRECTION_NEXT
#define ELM_FOCUS_UP EFL_UI_FOCUS_DIRECTION_UP
#define ELM_FOCUS_DOWN EFL_UI_FOCUS_DIRECTION_DOWN
#define ELM_FOCUS_RIGHT EFL_UI_FOCUS_DIRECTION_RIGHT
#define ELM_FOCUS_LEFT EFL_UI_FOCUS_DIRECTION_LEFT
typedef Efl_Ui_Focus_Direction Elm_Focus_Direction;

/**
 * Defines couple of standard Evas_Object layers to be used
 * with evas_object_layer_set().
 *
 * @note whenever extending with new values, try to keep some padding
 *       to siblings so there is room for further extensions.
 */
typedef enum
{
   ELM_OBJECT_LAYER_BACKGROUND = EVAS_LAYER_MIN + 64, /**< where to place backgrounds */
   ELM_OBJECT_LAYER_DEFAULT = 0, /**< Evas_Object default layer (and thus for Elementary) */
   ELM_OBJECT_LAYER_FOCUS = EVAS_LAYER_MAX - 128, /**< where focus object visualization is */
   ELM_OBJECT_LAYER_TOOLTIP = EVAS_LAYER_MAX - 64, /**< where to show tooltips */
   ELM_OBJECT_LAYER_CURSOR = EVAS_LAYER_MAX - 32, /**< where to show cursors */
   ELM_OBJECT_LAYER_LAST /**< last layer known by Elementary */
} Elm_Object_Layer;

/**************************************************************************/
EAPI extern int ELM_ECORE_EVENT_ETHUMB_CONNECT;

/**
 * Emitted when the application has reconfigured elementary settings due
 * to an external configuration tool asking it to.
 */
EAPI extern int ELM_EVENT_CONFIG_ALL_CHANGED;

/**
 * Emitted when any Elementary's policy value is changed.
 */
EAPI extern int ELM_EVENT_POLICY_CHANGED;

/**
 * Emitted when nothing is visible and the process as a whole should go into
 * a background state.
 * @since 1.12
 */
EAPI extern int ELM_EVENT_PROCESS_BACKGROUND;

/**
 * Emitted when going from nothing being visible to at least one window
 * being visible.
 * @since 1.12
 */
EAPI extern int ELM_EVENT_PROCESS_FOREGROUND;

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. */

extern EAPI double _elm_startup_time;

#ifndef ELM_LIB_QUICKLAUNCH
#define ELM_MAIN() int main(int argc, char **argv) { int ret__; _elm_startup_time = ecore_time_unix_get(); elm_init(argc, argv); ret__ = elm_main(argc, argv); elm_shutdown(); return ret__; } /**< macro to be used after the elm_main() function */
#else
/** @deprecated macro to be used after the elm_main() function.
 * Do not define ELM_LIB_QUICKLAUNCH
 * Compile your programs with -fpie and -pie -rdynamic instead, to generate a single binary (linkable executable).
 */
#define ELM_MAIN() int main(int argc, char **argv) { int ret__; _elm_startup_time = ecore_time_unix_get(); ret__ = elm_quicklaunch_fallback(argc, argv); elm_shutdown(); return ret__; }
#endif


#ifdef EFL_BETA_API_SUPPORT

#ifdef EFL_VERSION_MICRO
# define _EFL_VERSION_MICRO EFL_VERSION_MICRO
#else
# define _EFL_VERSION_MICRO 0
#endif

#ifdef EFL_VERSION_REVISION
# define _EFL_VERSION_REVISION EFL_VERSION_REVISION
#else
# define _EFL_VERSION_REVISION 0
#endif

#ifdef EFL_VERSION_FLAVOR
# define _EFL_VERSION_FLAVOR EFL_VERSION_FLAVOR
#else
# define _EFL_VERSION_FLAVOR NULL
#endif

#ifdef EFL_BUILD_ID
# define _EFL_BUILD_ID EFL_BUILD_ID
#else
# define _EFL_BUILD_ID NULL
#endif

#define _EFL_APP_VERSION_SET() do { if (efl_build_version_set) efl_build_version_set(EFL_VERSION_MAJOR, EFL_VERSION_MINOR, _EFL_VERSION_MICRO, _EFL_VERSION_REVISION, _EFL_VERSION_FLAVOR, _EFL_BUILD_ID); } while (0)

#ifndef ELM_LIB_QUICKLAUNCH
#define EFL_MAIN() int main(int argc, char **argv) { int ret__; _EFL_APP_VERSION_SET(); _elm_startup_time = ecore_time_unix_get(); elm_init(argc, argv); efl_event_callback_add(ecore_main_loop_get(), EFL_LOOP_EVENT_ARGUMENTS, efl_main, NULL); ret__ = efl_loop_begin(ecore_main_loop_get()); elm_shutdown(); return ret__; }

#define EFL_MAIN_EX()                                                   \
  EFL_CALLBACKS_ARRAY_DEFINE(_efl_main_ex,                              \
                             { EFL_LOOP_EVENT_ARGUMENTS, efl_main },    \
                             { EFL_LOOP_EVENT_PAUSE, efl_pause },       \
                             { EFL_LOOP_EVENT_RESUME, efl_resume },     \
                             { EFL_LOOP_EVENT_TERMINATE, efl_terminate });         \
  int main(int argc, char **argv)                                       \
  {                                                                     \
     int ret__;                                                         \
     _EFL_APP_VERSION_SET();                                            \
     _elm_startup_time = ecore_time_unix_get();                         \
     elm_init(argc, argv);                                              \
     efl_event_callback_array_add(ecore_main_loop_get(), _efl_main_ex(), NULL); \
     ret__ = efl_loop_begin(ecore_main_loop_get());                     \
     elm_shutdown();                                                    \
     return ret__;                                                      \
  }

#else
/** @deprecated macro to be used after the elm_main() function.
 * Do not define ELM_LIB_QUICKLAUNCH
 * Compile your programs with -fpie and -pie -rdynamic instead, to generate a single binary (linkable executable).
 */
#define EFL_MAIN() int main(int argc, char **argv) { int ret__; _EFL_APP_VERSION_SET(); _elm_startup_time = ecore_time_unix_get(); ret__ = efl_quicklaunch_fallback(argc, argv); elm_shutdown(); return ret__; (void) efl_main(NULL, NULL); return 0; }
#define EFL_MAIN_EX() int main(int argc, char **argv) { int ret__; _EFL_APP_VERSION_SET(); _elm_startup_time = ecore_time_unix_get(); ret__ = efl_quicklaunch_fallback(argc, argv); elm_shutdown(); return ret__; (void) efl_main(NULL, NULL);  (void) efl_pause(NULL, NULL);  (void) efl_resume(NULL, NULL); (void) efl_terminate(NULL, NULL); return 0; }
#endif

#endif /* EFL_BETA_API_SUPPORT */


/**************************************************************************/
/* General calls */

/**
 * Initialize Elementary
 *
 * @param[in] argc System's argument count value
 * @param[in] argv System's pointer to array of argument strings
 * @return The init counter value.
 *
 * This function initializes Elementary and increments a counter of
 * the number of calls to it. It returns the new counter's value.
 *
 * @warning This call is exported only for use by the @c ELM_MAIN()
 * macro. There is no need to use this if you use this macro (which
 * is highly advisable). An elm_main() should contain the entry
 * point code for your application, having the same prototype as
 * elm_init(), and @b not being static (putting the @c EAPI_MAIN symbol
 * in front of its type declaration is advisable). The @c
 * ELM_MAIN() call should be placed just after it.
 *
 * Example:
 * @dontinclude bg_example_01.c
 * @skip static void
 * @until ELM_MAIN
 *
 * See the full @ref bg_example_01_c "example".
 *
 * @see elm_shutdown().
 * @ingroup Elm_General
 */
EAPI int       elm_init(int argc, char **argv);

/**
 * Shut down Elementary
 *
 * @return The init counter value.
 *
 * This should be called at the end of your application, just
 * before it ceases to do any more processing. This will clean up
 * any permanent resources your application may have allocated via
 * Elementary that would otherwise persist.
 *
 * @see elm_init() for an example
 *
 * @note elm_shutdown() will iterate main loop until all ecore_evas are freed.
 * There is a possibility to call your ecore callbacks(timer, animator, event,
 * job, and etc.) in elm_shutdown()
 *
 * @ingroup Elm_General
 */
EAPI int       elm_shutdown(void);

/**
 * Run Elementary's main loop
 *
 * This call should be issued just after all initialization is
 * completed. This function will not return until elm_exit() is
 * called. It will keep looping, running the main
 * (event/processing) loop for Elementary.
 *
 * This function should be called once only from the same thread that
 * initted elementary, (elm_init(), eina_init(), ...) and should never
 * be nested. Never call it from within an instance of itself.
 *
 * @see elm_init() for an example
 *
 * @ingroup Elm_General
 */
EAPI void      elm_run(void);

/**
 * Ask to exit Elementary's main loop
 *
 * If this call is issued, it will flag the main loop to cease
 * processing and return back to its parent function (usually your
 * elm_main() function). This does not mean the main loop instantly quits.
 * So your ecore callbacks(timer, animator, event, job, and etc.) have chances
 * to be called even after elm_exit().
 *
 * @see elm_init() for an example. There, just after a request to
 * close the window comes, the main loop will be left.
 *
 * @note By using the appropriate #ELM_POLICY_QUIT on your Elementary
 * applications, you'll be able to get this function called automatically for you.
 *
 * @ingroup Elm_General
 */
EAPI void      elm_exit(void);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI void      elm_quicklaunch_mode_set(Eina_Bool ql_on);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI Eina_Bool elm_quicklaunch_mode_get(void);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI int       elm_quicklaunch_init(int argc, char **argv);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI int       elm_quicklaunch_sub_init(int argc, char **argv);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI int       elm_quicklaunch_sub_shutdown(void);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI int       elm_quicklaunch_shutdown(void);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI void      elm_quicklaunch_seed(void);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI Eina_Bool elm_quicklaunch_prepare(int argc, char **argv, const char *cwd);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI Eina_Bool efl_quicklaunch_prepare(int argc, char **argv, const char *cwd);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI Eina_Bool elm_quicklaunch_fork(int argc, char **argv, char *cwd, void (*postfork_func) (void *data), void *postfork_data);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI void      elm_quicklaunch_cleanup(void);

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI int       elm_quicklaunch_fallback(int argc, char **argv);

#ifdef EFL_BETA_API_SUPPORT
/**
 * Exposed symbol used only by macros and should not be used by apps
 * @since 1.18 (as beta)
 */
EAPI int       efl_quicklaunch_fallback(int argc, char **argv);
#endif

/**
 * Exposed symbol used only by macros and should not be used by apps
 */
EAPI char     *elm_quicklaunch_exe_path_get(const char *exe, const char *cwd);

/**
 * Set a new policy's value (for a given policy group/identifier).
 *
 * @param policy policy identifier, as in @ref Elm_Policy.
 * @param value policy value, which depends on the identifier
 *
 * @return @c EINA_TRUE on success or @c EINA_FALSE, on error.
 *
 * Elementary policies define applications' behavior,
 * somehow. These behaviors are divided in policy groups
 * (see #Elm_Policy enumeration). This call will emit the Ecore
 * event #ELM_EVENT_POLICY_CHANGED, which can be hooked at with
 * handlers. An #Elm_Event_Policy_Changed struct will be passed,
 * then.
 *
 * @note Currently, we have only one policy identifier/group
 * (#ELM_POLICY_QUIT), which has two possible values.
 *
 * @ingroup Elm_General
 */
EAPI Eina_Bool elm_policy_set(unsigned int policy, int value);

/**
 * Get the policy value for given policy identifier.
 *
 * @param policy policy identifier, as in #Elm_Policy.
 * @return The currently set policy value, for that
 * identifier. Will be @c 0 if @p policy passed is invalid.
 *
 * @ingroup Elm_General
 */
EAPI int       elm_policy_get(unsigned int policy);

/**
 * Change the language of the current application
 *
 * The @p lang passed must be the full name of the locale to use, for
 * example "en_US.utf8" or "es_ES@euro".
 *
 * Changing language with this function will make Elementary run through
 * all its widgets, translating strings set with
 * elm_object_domain_translatable_part_text_set(). This way, an entire
 * UI can have its language changed without having to restart the program.
 *
 * For more complex cases, like having formatted strings that need
 * translation, widgets will also emit a "language,changed" signal that
 * the user can listen to and manually translate the text.
 *
 * @param lang Language to set, must be the full name of the locale
 *
 * @ingroup Elm_General
 */
EAPI void      elm_language_set(const char *lang);

typedef enum _Elm_Process_State
{
   ELM_PROCESS_STATE_FOREGROUND, /*< The process is in a foreground/active/running state - work as normal. @since 1.12 */
   ELM_PROCESS_STATE_BACKGROUND /*< The process is in the bacgkround, so you may want to stop animating, fetching data as often etc. @since 1.12 */
} Elm_Process_State; /** The state of the process as a whole. @since 1.12 */

/**
 * Get the process state as a while
 *
 * @return The current process state
 *
 * The process may logically be some runnable state. a "foreground" application
 * runs as normal and may be user-visible or "active" in some way. A
 * background application is not user-visible or otherwise important and
 * likely should release resources and not wake up often or process much.
 *
 * @ingroup Elm_General
 * @since 1.12
 */
EAPI Elm_Process_State  elm_process_state_get(void);


/* legacy to eo translation */

typedef Efl_Ui_Focus_Autoscroll_Mode       Elm_Focus_Autoscroll_Mode;
#define ELM_FOCUS_AUTOSCROLL_MODE_SHOW     EFL_UI_FOCUS_AUTOSCROLL_MODE_SHOW
#define ELM_FOCUS_AUTOSCROLL_MODE_NONE     EFL_UI_FOCUS_AUTOSCROLL_MODE_NONE
#define ELM_FOCUS_AUTOSCROLL_MODE_BRING_IN EFL_UI_FOCUS_AUTOSCROLL_MODE_BRING_IN

typedef Efl_Ui_Softcursor_Mode             Elm_Softcursor_Mode;
#define ELM_SOFTCURSOR_MODE_AUTO           EFL_UI_SOFTCURSOR_MODE_AUTO
#define ELM_SOFTCURSOR_MODE_ON             EFL_UI_SOFTCURSOR_MODE_ON
#define ELM_SOFTCURSOR_MODE_OFF            EFL_UI_SOFTCURSOR_MODE_OFF

typedef Efl_Ui_Slider_Indicator_Visible_Mode       Elm_Slider_Indicator_Visible_Mode;
#define ELM_SLIDER_INDICATOR_VISIBLE_MODE_DEFAULT  EFL_UI_SLIDER_INDICATOR_VISIBLE_MODE_DEFAULT
#define ELM_SLIDER_INDICATOR_VISIBLE_MODE_ALWAYS   EFL_UI_SLIDER_INDICATOR_VISIBLE_MODE_ALWAYS
#define ELM_SLIDER_INDICATOR_VISIBLE_MODE_ON_FOCUS EFL_UI_SLIDER_INDICATOR_VISIBLE_MODE_ON_FOCUS
#define ELM_SLIDER_INDICATOR_VISIBLE_MODE_NONE     EFL_UI_SLIDER_INDICATOR_VISIBLE_MODE_NONE

typedef Efl_Ui_Focus_Move_Policy           Elm_Focus_Move_Policy;
#define ELM_FOCUS_MOVE_POLICY_CLICK        EFL_UI_FOCUS_MOVE_POLICY_CLICK
#define ELM_FOCUS_MOVE_POLICY_IN           EFL_UI_FOCUS_MOVE_POLICY_IN
#define ELM_FOCUS_MOVE_POLICY_KEY_ONLY     EFL_UI_FOCUS_MOVE_POLICY_KEY_ONLY

/**
 * @}
 */