2 # include "elementary_config.h"
5 #include <dlfcn.h> /* dlopen,dlclose,etc */
7 #ifdef HAVE_CRT_EXTERNS_H
8 # include <crt_externs.h>
15 #include <Elementary.h>
18 #define SEMI_BROKEN_QUICKLAUNCH 1
20 static Elm_Version _version = { VMAJ, VMIN, VMIC, VREV };
21 EAPI Elm_Version *elm_version = &_version;
26 * This group includes functions of elm_main.c
31 _elm_dangerous_call_check(const char *call)
36 snprintf(buf, sizeof(buf), "%i.%i.%i.%i", VMAJ, VMIN, VMIC, VREV);
37 eval = getenv("ELM_NO_FINGER_WAGGLING");
38 if ((eval) && (!strcmp(eval, buf)))
40 printf("ELEMENTARY FINGER WAGGLE!!!!!!!!!!\n"
43 "PLEASE see the API documentation for this function. This call\n"
44 "should almost never be used. Only in very special cases.\n"
46 "To remove this warning please set the environment variable:\n"
47 " ELM_NO_FINGER_WAGGLING\n"
48 "To the value of the Elementary version + revision number. e.g.:\n"
57 * @defgroup Start Getting Started
60 * To write an Elementary app, you can get started with the following:
63 * #include <Elementary.h>
64 * #ifndef ELM_LIB_QUICKLAUNCH
66 * elm_main(int argc, char **argv)
68 * // create window(s) here and do any application init
69 * elm_run(); // run main loop
70 * elm_shutdown(); // after mainloop finishes running, shutdown
71 * return 0; // exit 0 for exit code
77 * To take full advantage of the quicklaunch architecture for launching
78 * processes as quickly as possible (saving time at startup time like
79 * connecting to X11, loading and linking shared libraries) you may want to
80 * use the following configure.in/configure.ac and Makefile.am and autogen.sh
81 * script to generate your files. It is assumed your application uses the
82 * main.c file for its code.
84 * configure.in/configure.ac:
87 AC_INIT(myapp, 0.0.0, myname@mydomain.com)
89 AC_CONFIG_SRCDIR(configure.in)
91 AM_INIT_AUTOMAKE(1.6 dist-bzip2)
92 AM_CONFIG_HEADER(config.h)
102 define([AC_LIBTOOL_LANG_CXX_CONFIG], [:])dnl
103 define([AC_LIBTOOL_LANG_F77_CONFIG], [:])dnl
106 PKG_CHECK_MODULES([ELEMENTARY], elementary)
114 AUTOMAKE_OPTIONS = 1.4 foreign
115 MAINTAINERCLEANFILES = Makefile.in
117 INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@
120 myapp_LTLIBRARIES = myapp.la
124 myapp_la_SOURCES = main.c
125 myapp_la_LIBADD = @ELEMENTARY_LIBS@
127 myapp_la_LDFLAGS = -module -avoid-version -no-undefined
129 myapp_SOURCES = main.c
130 myapp_LDADD = @ELEMENTARY_LIBS@
131 myapp_CFLAGS = -DELM_LIB_QUICKLAUNCH=1
138 rm -rf autom4te.cache
139 rm -f aclocal.m4 ltmain.sh
144 echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS -I m4 || exit 1
145 echo "Running autoheader..." ; autoheader || exit 1
146 echo "Running autoconf..." ; autoconf || exit 1
147 echo "Running libtoolize..." ; (libtoolize --copy --automake || glibtoolize --automake) || exit 1
148 echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1
150 if [ -z "$NOCONFIGURE" ]; then
155 * To gnerate all the things needed to bootstrap just run:
161 * This will generate Makefile.in's, the confgure script and everything else.
162 * After this it works like all normal autotools projects:
169 * Note sudo was assumed to get root permissions, as this would install in
170 * /usr/local which is system-owned. Ue any way you like to gain root, or
171 * specify a different prefix with configure:
174 ./confiugre --prefix=$HOME/mysoftware
177 * Also remember that autotools buys you some useful commands like:
182 * This uninstalls the software after it was installed with "make install".
183 * It is very useful to clear up what you built if you wish to clean the
190 * This firstly checks if your build tree is "clean" and ready for
191 * distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is
192 * ready to upload and distribute to the world, that contains the generated
193 * Makefile.in's and configure script. The users do not need to run
194 * autogen.sh - just configure and on. They don't need autotools installed.
195 * This tarball also builds cleanly, has all the sources it needs to build
196 * included (that is sources for your application, not libraries it depends
197 * on like Elementary). It builds cleanly in a buildroot and does not
198 * contain any files that are temporarily generated like binaries and other
199 * build-gnerated files, so the tarball is clean, and no need to worry
200 * about cleaning up your tree before packaging.
206 * This cleans up all build files (binaries, objects etc.) from the tree.
212 * This cleans out all files from the build and from configure's output too.
215 make maintainer-clean
218 * This deletes all the files autogen.sh will produce so the tree is clean
219 * to be put into a revision-control system (like CVS, SVN or GIT for example).
221 * The above will build a library - libmyapp.so and install in the target
222 * library directory (default is /usr/local/lib). You will also get a
223 * myapp.a and myapp.la - these are useless and can be deleted. Libtool likes
224 * to generate these all the time. You will also get a binary in the target
225 * binary directory (default is /usr/local/bin). This is a "debug binary".
226 * This will run and dlopen() the myapp.so and then jump to it's elm_main
227 * function. This allows for easy debugging with GDB and Valgrind. When you
228 * are ready to go to production do the following:
230 * 1. delete the myapp binary. i.e. rm /usr/local/bin/myapp
232 * 2. symlink the myapp binary to elementary_run (supplied by elementary).
233 * i.e. ln -s elmentary_run /usr/local/bin/myapp
235 * 3. run elementary_quicklaunch as part of your graphical login session and
238 * This will man elementary_quicklaunch does pre-initialization before the
239 * application needs to be run, saving the effort at the time the application
240 * is needed, thus speeding up the time it takes to appear.
242 * If you don't want to use the quicklaunch infrastructure (which is
243 * optional), you can execute the old fashioned way by just running the
244 * myapp binary loader than will load the myapp.so for you, or you can
245 * remove the split-file binary and put it into one binary as things always
246 * have been with the following configure.in/configure.ac and Makfile.am
249 * configure.in/configure.ac:
252 AC_INIT(myapp, 0.0.0, myname@mydomain.com)
254 AC_CONFIG_SRCDIR(configure.in)
256 AM_INIT_AUTOMAKE(1.6 dist-bzip2)
257 AM_CONFIG_HEADER(config.h)
266 PKG_CHECK_MODULES([ELEMENTARY], elementary)
274 AUTOMAKE_OPTIONS = 1.4 foreign
275 MAINTAINERCLEANFILES = Makefile.in
277 INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@
281 myapp_SOURCES = main.c
282 myapp_LDADD = @ELEMENTARY_LIBS@
286 * Notice that they are the same as before, just with libtool and library
287 * building sections removed. Both ways work for building elementary
288 * applications. It is up to you to decide what is best for you. If you just
289 * follow the template above, you can do it both ways and can decide at build
290 * time. The more advanced of you may suggest making it a configure option.
291 * That is perfectly valid, but has been left out here for simplicity, as our
292 * aim to have an Elementary (and EFL) tutorial, not an autoconf & automake
297 static Eina_Bool _elm_signal_exit(void *data,
301 char *_elm_appname = NULL;
302 const char *_elm_data_dir = NULL;
303 const char *_elm_lib_dir = NULL;
304 int _elm_log_dom = -1;
306 EAPI int ELM_EVENT_POLICY_CHANGED = 0;
308 static int _elm_init_count = 0;
309 static int _elm_sub_init_count = 0;
310 static int _elm_ql_init_count = 0;
311 static int _elm_policies[ELM_POLICY_LAST];
312 static Ecore_Event_Handler *_elm_exit_handler = NULL;
313 static Eina_Bool quicklaunch_on = 0;
316 _elm_signal_exit(void *data __UNUSED__,
317 int ev_type __UNUSED__,
321 return ECORE_CALLBACK_PASS_ON;
327 edje_scale_set(_elm_config->scale);
328 _elm_win_rescale(NULL, EINA_FALSE);
332 * @defgroup General General
337 * Inititalise Elementary
339 * @return The init counter value.
341 * This call is exported only for use by the ELM_MAIN() macro. There is no
342 * need to use this if you use this macro (which is highly advisable).
350 if (_elm_init_count > 1) return _elm_init_count;
351 elm_quicklaunch_init(argc, argv);
352 elm_quicklaunch_sub_init(argc, argv);
353 return _elm_init_count;
357 * Shut down Elementary
359 * @return The init counter value.
361 * This should be called at the end of your application just before it ceases
362 * to do any more processing. This will clean up any permanent resources your
363 * application may have allocated via Elementary that would otherwise persist
364 * on an exit without this call.
371 if (_elm_init_count > 0) return _elm_init_count;
372 // FIXME : it can cause abnormal program exit
373 // After app-core fixing the issue about app's callback fucntion pointer,
374 // activate _elm_win_shutdown();
376 while (_elm_win_deferred_free) ecore_main_loop_iterate();
377 elm_quicklaunch_sub_shutdown();
378 elm_quicklaunch_shutdown();
379 return _elm_init_count;
383 static int _elm_need_e_dbus = 0;
386 elm_need_e_dbus(void)
389 if (_elm_need_e_dbus++) return EINA_TRUE;
399 _elm_unneed_e_dbus(void)
402 if (--_elm_need_e_dbus) return;
404 _elm_need_e_dbus = 0;
411 static int _elm_need_efreet = 0;
414 elm_need_efreet(void)
417 if (_elm_need_efreet++) return EINA_TRUE;
425 list = efreet_icon_extra_list_get();
428 e_user_dir_concat_static(buf, "icons");
429 *list = eina_list_prepend(*list, (void *)eina_stringshare_add(buf));
430 e_prefix_data_concat_static(buf, "data/icons");
431 *list = eina_list_prepend(*list, (void *)eina_stringshare_add(buf));
442 _elm_unneed_efreet(void)
445 if (--_elm_need_efreet) return;
447 _elm_need_efreet = 0;
448 efreet_trash_shutdown();
449 efreet_mime_shutdown();
455 elm_quicklaunch_mode_set(Eina_Bool ql_on)
457 quicklaunch_on = ql_on;
461 elm_quicklaunch_mode_get(void)
463 return quicklaunch_on;
467 elm_quicklaunch_init(int argc,
470 char buf[PATH_MAX], *s;
472 _elm_ql_init_count++;
473 if (_elm_ql_init_count > 1) return _elm_ql_init_count;
475 _elm_log_dom = eina_log_domain_register("elementary", EINA_COLOR_LIGHTBLUE);
478 EINA_LOG_ERR("could not register elementary log domain.");
479 _elm_log_dom = EINA_LOG_DOMAIN_GLOBAL;
484 ecore_app_args_set(argc, (const char **)argv);
486 memset(_elm_policies, 0, sizeof(_elm_policies));
487 if (!ELM_EVENT_POLICY_CHANGED)
488 ELM_EVENT_POLICY_CHANGED = ecore_event_type_new();
492 _elm_exit_handler = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT, _elm_signal_exit, NULL);
494 if (argv) _elm_appname = strdup(ecore_file_file_get(argv[0]));
498 s = getenv("ELM_DATA_DIR");
499 _elm_data_dir = eina_stringshare_add(s);
503 s = getenv("ELM_PREFIX");
506 snprintf(buf, sizeof(buf), "%s/share/elementary", s);
507 _elm_data_dir = eina_stringshare_add(buf);
512 s = getenv("ELM_LIB_DIR");
513 _elm_lib_dir = eina_stringshare_add(s);
517 s = getenv("ELM_PREFIX");
520 snprintf(buf, sizeof(buf), "%s/lib", s);
521 _elm_lib_dir = eina_stringshare_add(buf);
525 if ((!_elm_data_dir) || (!_elm_lib_dir))
527 Dl_info elementary_dl;
528 // libelementary.so/../../share/elementary/
529 if (dladdr(elm_init, &elementary_dl))
533 dir = ecore_file_dir_get(elementary_dl.dli_fname);
538 if (ecore_file_is_dir(dir))
539 _elm_lib_dir = eina_stringshare_add(dir);
543 dir2 = ecore_file_dir_get(dir);
546 snprintf(buf, sizeof(buf), "%s/share/elementary", dir2);
547 if (ecore_file_is_dir(buf))
548 _elm_data_dir = eina_stringshare_add(buf);
558 _elm_data_dir = eina_stringshare_add(PACKAGE_DATA_DIR);
560 _elm_data_dir = eina_stringshare_add("/");
562 _elm_lib_dir = eina_stringshare_add(PACKAGE_LIB_DIR);
564 _elm_lib_dir = eina_stringshare_add("/");
567 return _elm_ql_init_count;
571 elm_quicklaunch_sub_init(int argc,
574 _elm_sub_init_count++;
575 if (_elm_sub_init_count > 1) return _elm_sub_init_count;
578 #ifdef SEMI_BROKEN_QUICKLAUNCH
579 return _elm_sub_init_count;
584 ecore_app_args_set(argc, (const char **)argv);
588 _elm_config_sub_init();
589 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
590 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
591 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
592 ENGINE_COMPARE(ELM_XRENDER_X11) ||
593 ENGINE_COMPARE(ELM_OPENGL_X11))
594 #undef ENGINE_COMPARE
596 #ifdef HAVE_ELEMENTARY_X
600 ecore_evas_init(); // FIXME: check errors
603 return _elm_sub_init_count;
607 elm_quicklaunch_sub_shutdown(void)
609 _elm_sub_init_count--;
610 if (_elm_sub_init_count > 0) return _elm_sub_init_count;
613 #ifdef SEMI_BROKEN_QUICKLAUNCH
614 return _elm_sub_init_count;
620 _elm_module_shutdown();
621 ecore_imf_shutdown();
622 ecore_evas_shutdown();
623 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
624 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
625 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
626 ENGINE_COMPARE(ELM_XRENDER_X11) ||
627 ENGINE_COMPARE(ELM_OPENGL_X11))
628 #undef ENGINE_COMPARE
630 #ifdef HAVE_ELEMENTARY_X
631 ecore_x_disconnect();
634 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
635 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
636 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
637 ENGINE_COMPARE(ELM_XRENDER_X11) ||
638 ENGINE_COMPARE(ELM_OPENGL_X11) ||
639 ENGINE_COMPARE(ELM_SOFTWARE_SDL) ||
640 ENGINE_COMPARE(ELM_SOFTWARE_16_SDL) ||
641 ENGINE_COMPARE(ELM_OPENGL_SDL) ||
642 ENGINE_COMPARE(ELM_SOFTWARE_WIN32) ||
643 ENGINE_COMPARE(ELM_SOFTWARE_16_WINCE))
644 #undef ENGINE_COMPARE
645 evas_cserve_disconnect();
649 return _elm_sub_init_count;
653 elm_quicklaunch_shutdown(void)
655 _elm_ql_init_count--;
656 if (_elm_ql_init_count > 0) return _elm_ql_init_count;
657 eina_stringshare_del(_elm_data_dir);
658 _elm_data_dir = NULL;
659 eina_stringshare_del(_elm_lib_dir);
665 _elm_config_shutdown();
667 ecore_event_handler_del(_elm_exit_handler);
668 _elm_exit_handler = NULL;
670 _elm_theme_shutdown();
671 _elm_unneed_efreet();
672 _elm_unneed_e_dbus();
673 _elm_unneed_ethumb();
674 ecore_file_shutdown();
678 if ((_elm_log_dom > -1) && (_elm_log_dom != EINA_LOG_DOMAIN_GLOBAL))
680 eina_log_domain_unregister(_elm_log_dom);
684 _elm_widget_type_clear();
687 return _elm_ql_init_count;
691 elm_quicklaunch_seed(void)
693 #ifndef SEMI_BROKEN_QUICKLAUNCH
696 Evas_Object *win, *bg, *bt;
698 win = elm_win_add(NULL, "seed", ELM_WIN_BASIC);
699 bg = elm_bg_add(win);
700 elm_win_resize_object_add(win, bg);
701 evas_object_show(bg);
702 bt = elm_button_add(win);
703 elm_button_label_set(bt, " abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789~-_=+\\|]}[{;:'\",<.>/?");
704 elm_win_resize_object_add(win, bt);
705 ecore_main_loop_iterate();
706 evas_object_del(win);
707 ecore_main_loop_iterate();
708 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
709 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
710 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
711 ENGINE_COMPARE(ELM_XRENDER_X11) ||
712 ENGINE_COMPARE(ELM_OPENGL_X11))
713 #undef ENGINE_COMPARE
715 # ifdef HAVE_ELEMENTARY_X
719 ecore_main_loop_iterate();
724 static void *qr_handle = NULL;
725 static int (*qr_main)(int argc,
729 elm_quicklaunch_prepare(int argc __UNUSED__,
733 char *exe = elm_quicklaunch_exe_path_get(argv[0]);
736 ERR("requested quicklaunch binary '%s' does not exist\n", argv[0]);
744 exe2 = malloc(strlen(exe) + 1 + 10);
746 p = strrchr(exe2, '/');
749 exename = alloca(strlen(p) + 1);
752 strcat(p, "../lib/");
755 if (!access(exe2, R_OK | X_OK))
763 qr_handle = dlopen(exe, RTLD_NOW | RTLD_GLOBAL);
766 fprintf(stderr, "dlerr: %s\n", dlerror());
767 WRN("dlopen('%s') failed: %s", exe, dlerror());
771 INF("dlopen('%s') = %p", exe, qr_handle);
772 qr_main = dlsym(qr_handle, "elm_main");
773 INF("dlsym(%p, 'elm_main') = %p", qr_handle, qr_main);
776 WRN("not quicklauncher capable: no elm_main in '%s'", exe);
795 extern char **environ;
800 for (i = 0, size = 0; environ[i]; i++)
801 size += strlen(environ[i]) + 1;
803 p = malloc((i + 1) * sizeof(char *));
808 for (i = 0; oldenv[i]; i++)
809 environ[i] = strdup(oldenv[i]);
816 elm_quicklaunch_fork(int argc,
819 void (postfork_func) (void *data),
829 // need to accept current environment from elementary_run
836 if (child > 0) return EINA_TRUE;
839 perror("could not fork");
844 perror("could not chdir");
845 args = alloca((argc + 1) * sizeof(char *));
846 for (i = 0; i < argc; i++) args[i] = argv[i];
848 WRN("%s not quicklaunch capable, fallback...", argv[0]);
849 execvp(argv[0], args);
850 ERR("failed to execute '%s': %s", argv[0], strerror(errno));
854 if (child > 0) return EINA_TRUE;
857 perror("could not fork");
860 if (postfork_func) postfork_func(postfork_data);
864 #ifdef SEMI_BROKEN_QUICKLAUNCH
865 ecore_app_args_set(argc, (const char **)argv);
868 _elm_config_sub_init();
869 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
870 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
871 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
872 ENGINE_COMPARE(ELM_XRENDER_X11) ||
873 ENGINE_COMPARE(ELM_OPENGL_X11))
874 #undef ENGINE_COMPARE
876 # ifdef HAVE_ELEMENTARY_X
880 ecore_evas_init(); // FIXME: check errors
888 perror("could not chdir");
889 // FIXME: this is very linux specific. it changes argv[0] of the process
890 // so ps etc. report what you'd expect. for other unixes and os's this
897 ecore_app_args_get(&real_argc, &real_argv);
898 lastarg = real_argv[real_argc - 1] + strlen(real_argv[real_argc - 1]);
899 for (p = real_argv[0]; p < lastarg; p++) *p = 0;
900 strcpy(real_argv[0], argv[0]);
902 ecore_app_args_set(argc, (const char **)argv);
903 ret = qr_main(argc, argv);
917 elm_quicklaunch_cleanup(void)
930 elm_quicklaunch_fallback(int argc,
934 elm_quicklaunch_init(argc, argv);
935 elm_quicklaunch_sub_init(argc, argv);
936 elm_quicklaunch_prepare(argc, argv);
937 ret = qr_main(argc, argv);
943 elm_quicklaunch_exe_path_get(const char *exe)
945 static char *path = NULL;
946 static Eina_List *pathlist = NULL;
950 if (exe[0] == '/') return strdup(exe);
951 if ((exe[0] == '.') && (exe[1] == '/')) return strdup(exe);
952 if ((exe[0] == '.') && (exe[1] == '.') && (exe[2] == '/')) return strdup(exe);
957 path = getenv("PATH");
958 buf2 = alloca(strlen(path) + 1);
963 if ((*p == ':') || (!*p))
968 strncpy(buf2, pp, len);
970 pathlist = eina_list_append(pathlist, eina_stringshare_add(buf2));
982 EINA_LIST_FOREACH(pathlist, l, pathitr)
984 snprintf(buf, sizeof(buf), "%s/%s", pathitr, exe);
985 if (!access(buf, R_OK | X_OK)) return strdup(buf);
993 * This call should be called just after all initialization is complete. This
994 * function will not return until elm_exit() is called. It will keep looping
995 * running the main event/processing loop for Elementary.
1001 ecore_main_loop_begin();
1005 * Exit the main loop
1007 * If this call is called, it will flag the main loop to cease processing and
1008 * return back to its parent function.
1014 ecore_main_loop_quit();
1018 * Set new policy value.
1020 * This will emit the ecore event ELM_EVENT_POLICY_CHANGED in the main
1021 * loop giving the event information Elm_Event_Policy_Changed with
1022 * policy identifier, new and old values.
1024 * @param policy policy identifier as in Elm_Policy.
1025 * @param value policy value, depends on identifiers, usually there is
1026 * an enumeration with the same prefix as the policy name, for
1027 * example: ELM_POLICY_QUIT and Elm_Policy_Quit
1028 * (ELM_POLICY_QUIT_NONE, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED).
1031 * @return @c EINA_TRUE on success or @c EINA_FALSE on error (right
1032 * now just invalid policy identifier, but in future policy
1033 * value might be enforced).
1036 elm_policy_set(unsigned int policy,
1039 Elm_Event_Policy_Changed *ev;
1041 if (policy >= ELM_POLICY_LAST)
1044 if (value == _elm_policies[policy])
1047 /* TODO: validade policy? */
1049 ev = malloc(sizeof(*ev));
1050 ev->policy = policy;
1051 ev->new_value = value;
1052 ev->old_value = _elm_policies[policy];
1054 _elm_policies[policy] = value;
1056 ecore_event_add(ELM_EVENT_POLICY_CHANGED, ev, NULL, NULL);
1062 * Gets the policy value set for given identifier.
1064 * @param policy policy identifier as in Elm_Policy.
1067 * @return policy value. Will be 0 if policy identifier is invalid.
1070 elm_policy_get(unsigned int policy)
1072 if (policy >= ELM_POLICY_LAST)
1074 return _elm_policies[policy];
1078 * @defgroup UI-Mirroring Selective Widget mirroring
1080 * These functions allow you to set ui-miroring on specific widgets or whe
1081 * whole interface. Widgets can be in one of two modes, automatic and manual.
1082 * Automatic means they'll be changed according to the system mirroring mode
1083 * and manual means only explicit changes will matter. You are not supposed to
1084 * change mirroring state of a widget set to automatic, will mostly work, but
1085 * the behavior is not really defined.
1089 * Returns the widget's mirrored mode.
1091 * @param obj The widget.
1092 * @return mirrored mode of the object.
1096 elm_object_mirrored_get(const Evas_Object *obj)
1098 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
1099 return elm_widget_mirrored_get(obj);
1103 * Sets the widget's mirrored mode.
1105 * @param obj The widget.
1106 * @param mirrored EINA_TRUE to set mirrored mode. EINA_FALSE to unset.
1109 elm_object_mirrored_set(Evas_Object *obj, Eina_Bool mirrored)
1111 EINA_SAFETY_ON_NULL_RETURN(obj);
1112 elm_widget_mirrored_set(obj, mirrored);
1116 * Returns the widget's mirrored mode setting.
1118 * @param obj The widget.
1119 * @return mirrored mode setting of the object.
1123 elm_object_mirrored_automatic_get(const Evas_Object *obj)
1125 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
1126 return elm_widget_mirrored_automatic_get(obj);
1130 * Sets the widget's mirrored mode setting.
1131 * When widget in automatic mode, it follows the system mirrored mode set by
1132 * elm_mirrored_set().
1133 * @param obj The widget.
1134 * @param automatic EINA_TRUE for auto mirrored mode. EINA_FALSE for manual.
1137 elm_object_mirrored_automatic_set(Evas_Object *obj, Eina_Bool automatic)
1139 EINA_SAFETY_ON_NULL_RETURN(obj);
1140 elm_widget_mirrored_automatic_set(obj, automatic);
1144 * @defgroup Scaling Selective Widget Scaling
1147 * Different widgets can be scaled independently. These functions allow you to
1148 * manipulate this scaling on a per-widget basis. The object and all its
1149 * children get their scaling factors multiplied by the scale factor set.
1150 * This is multiplicative, in that if a child also has a scale size set it is
1151 * in turn multiplied by its parent's scale size. 1.0 means “don't scale”,
1152 * 2.0 is double size, 0.5 is half etc.
1156 * Set the scaling factor
1158 * @param obj The object
1159 * @param scale Scale factor (from 0.0 up, with 1.0 == no scaling)
1163 elm_object_scale_set(Evas_Object *obj,
1166 EINA_SAFETY_ON_NULL_RETURN(obj);
1167 elm_widget_scale_set(obj, scale);
1171 * Get the scaling factor
1173 * @param obj The object
1174 * @return The scaling factor set by elm_object_scale_set()
1178 elm_object_scale_get(const Evas_Object *obj)
1180 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, 0.0);
1181 return elm_widget_scale_get(obj);
1185 * Get the global scaling factor
1187 * This gets the globally configured scaling factor that is applied to all
1190 * @return The scaling factor
1196 return _elm_config->scale;
1200 * Set the global scaling factor
1202 * This sets the globally configured scaling factor that is applied to all
1205 * @param scale The scaling factor to set
1209 elm_scale_set(double scale)
1211 if (_elm_config->scale == scale) return;
1212 _elm_config->scale = scale;
1217 * Set the global scaling factor for all applications on the display
1219 * This sets the globally configured scaling factor that is applied to all
1220 * objects for all applications.
1221 * @param scale The scaling factor to set
1225 elm_scale_all_set(double scale)
1227 #ifdef HAVE_ELEMENTARY_X
1228 static Ecore_X_Atom atom = 0;
1229 unsigned int scale_i = (unsigned int)(scale * 1000.0);
1231 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_SCALE");
1232 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1238 * @defgroup Styles Styles
1241 * Widgets can have different styles of look. These generic API's set
1242 * styles of widgets, if they support them (and if the theme(s) do).
1248 * This sets the name of the style
1249 * @param obj The object
1250 * @param style The style name to use
1254 elm_object_style_set(Evas_Object *obj,
1257 EINA_SAFETY_ON_NULL_RETURN(obj);
1258 elm_widget_style_set(obj, style);
1264 * This gets the style being used for that widget. Note that the string
1265 * pointer is only valid as longas the object is valid and the style doesn't
1268 * @param obj The object
1269 * @return The style name
1273 elm_object_style_get(const Evas_Object *obj)
1275 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
1276 return elm_widget_style_get(obj);
1280 * Set the disable state
1282 * This sets the disable state for the widget.
1284 * @param obj The object
1285 * @param disabled The state
1289 elm_object_disabled_set(Evas_Object *obj,
1292 EINA_SAFETY_ON_NULL_RETURN(obj);
1293 elm_widget_disabled_set(obj, disabled);
1297 * Get the disable state
1299 * This gets the disable state for the widget.
1301 * @param obj The object
1302 * @return True, if the widget is disabled
1306 elm_object_disabled_get(const Evas_Object *obj)
1308 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
1309 return elm_widget_disabled_get(obj);
1313 * @defgroup Config Elementary Config
1316 * Elementary configuration is formed by a set options bounded to a
1317 * given @ref Profile profile, like @ref Theme theme, @ref Fingers
1318 * "finger size", etc. These are functions with which one syncronizes
1319 * changes made to those values to the configuration storing files, de
1320 * facto. You most probably don't want to use the functions in this
1321 * group unlees you're writing an elementary configuration manager.
1325 * Save back Elementary's configuration, so that it will persist on
1328 * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
1331 * This function will take effect -- thus, do I/O -- immediately. Use
1332 * it when you want to apply all configuration changes at once. The
1333 * current configuration set will get saved onto the current profile
1334 * configuration file.
1338 elm_config_save(void)
1340 return _elm_config_save();
1344 * Reload Elementary's configuration, bounded to current selected
1347 * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
1350 * Useful when you want to force reloading of configuration values for
1351 * a profile. If one removes user custom configuration directories,
1352 * for example, it will force a reload with system values insted.
1356 elm_config_reload(void)
1358 _elm_config_reload();
1362 * @defgroup Profile Elementary Profile
1365 * Profiles are pre-set options that affect the whole look-and-feel of
1366 * Elementary-based applications. There are, for example, profiles
1367 * aimed at desktop computer applications and others aimed at mobile,
1368 * touchscreen-based ones. You most probably don't want to use the
1369 * functions in this group unlees you're writing an elementary
1370 * configuration manager.
1374 * Get Elementary's profile in use.
1376 * This gets the global profile that is applied to all Elementary
1379 * @return The profile's name
1383 elm_profile_current_get(void)
1385 return _elm_config_current_profile_get();
1389 * Get an Elementary's profile directory path in the filesystem. One
1390 * may want to fetch a system profile's dir or an user one (fetched
1393 * @param profile The profile's name
1394 * @param is_user Whether to lookup for an user profile (@c EINA_TRUE)
1395 * or a system one (@c EINA_FALSE)
1396 * @return The profile's directory path.
1399 * @note You must free it with elm_profile_dir_free().
1402 elm_profile_dir_get(const char *profile,
1405 return _elm_config_profile_dir_get(profile, is_user);
1409 * Free an Elementary's profile directory path, as returned by
1410 * elm_profile_dir_get().
1412 * @param p_dir The profile's path
1417 elm_profile_dir_free(const char *p_dir)
1419 free((void *)p_dir);
1423 * Get Elementary's list of available profiles.
1425 * @return The profiles list. List node data are the profile name
1429 * @note One must free this list, after usage, with the function
1430 * elm_profile_list_free().
1433 elm_profile_list_get(void)
1435 return _elm_config_profiles_list();
1439 * Free Elementary's list of available profiles.
1441 * @param The profiles list, as returned by elm_profile_list_get().
1446 elm_profile_list_free(Eina_List *l)
1450 EINA_LIST_FREE(l, dir)
1451 eina_stringshare_del(dir);
1455 * Set Elementary's profile.
1457 * This sets the global profile that is applied to Elementary
1458 * applications. Just the process the call comes from will be
1461 * @param profile The profile's name
1466 elm_profile_set(const char *profile)
1468 EINA_SAFETY_ON_NULL_RETURN(profile);
1469 _elm_config_profile_set(profile);
1473 * Set Elementary's profile.
1475 * This sets the global profile that is applied to all Elementary
1476 * applications. All running Elementary windows will be affected.
1478 * @param profile The profile's name
1483 elm_profile_all_set(const char *profile)
1485 #ifdef HAVE_ELEMENTARY_X
1486 static Ecore_X_Atom atom = 0;
1488 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_PROFILE");
1489 ecore_x_window_prop_string_set(ecore_x_window_root_first_get(),
1495 * @defgroup Engine Elementary Engine
1498 * These are functions setting and querying which rendering engine
1499 * Elementary will use for drawing its windows' pixels.
1503 * Get Elementary's rendering engine in use.
1505 * This gets the global rendering engine that is applied to all
1506 * Elementary applications.
1508 * @return The rendering engine's name
1511 * @note there's no need to free the returned string, here.
1514 elm_engine_current_get(void)
1516 return _elm_config->engine;
1520 * Set Elementary's rendering engine for use.
1522 * This gets sets global rendering engine that is applied to all
1523 * Elementary applications. Note that it will take effect only to
1524 * subsequent Elementary window creations.
1526 * @param The rendering engine's name
1529 * @note there's no need to free the returned string, here.
1532 elm_engine_set(const char *engine)
1534 EINA_SAFETY_ON_NULL_RETURN(engine);
1536 _elm_config_engine_set(engine);
1540 * @defgroup Fonts Elementary Fonts
1543 * These are functions dealing with font rendering, selection and the
1544 * like for Elementary applications. One might fetch which system
1545 * fonts are there to use and set custom fonts for individual classes
1546 * of UI items containing text (text classes).
1550 * Get Elementary's list of supported text classes.
1552 * @return The text classes list, with @c Elm_Text_Class blobs as data.
1555 * Release the list with elm_text_classes_list_free().
1557 EAPI const Eina_List *
1558 elm_text_classes_list_get(void)
1560 return _elm_config_text_classes_get();
1564 * Free Elementary's list of supported text classes.
1568 * @see elm_text_classes_list_get().
1571 elm_text_classes_list_free(const Eina_List *list)
1573 _elm_config_text_classes_free((Eina_List *)list);
1577 * Get Elementary's list of font overlays, set with
1578 * elm_font_overlay_set().
1580 * @return The font overlays list, with @c Elm_Font_Overlay blobs as
1585 * For each text class, one can set a <b>font overlay</b> for it,
1586 * overriding the default font properties for that class coming from
1587 * the theme in use. There is no need to free this list.
1589 * @see elm_font_overlay_set() and elm_font_overlay_unset().
1591 EAPI const Eina_List *
1592 elm_font_overlay_list_get(void)
1594 return _elm_config_font_overlays_list();
1598 * Set a font overlay for a given Elementary text class.
1600 * @param text_class Text class name
1601 * @param font Font name and style string
1602 * @param size Font size
1606 * @p font has to be in the format returned by
1607 * elm_font_fontconfig_name_get(). @see elm_font_overlay_list_get()
1608 * and @elm_font_overlay_unset().
1611 elm_font_overlay_set(const char *text_class,
1613 Evas_Font_Size size)
1615 _elm_config_font_overlay_set(text_class, font, size);
1619 * Unset a font overlay for a given Elementary text class.
1621 * @param text_class Text class name
1625 * This will bring back text elements belonging to text class @p
1626 * text_class back to their default font settings.
1629 elm_font_overlay_unset(const char *text_class)
1631 _elm_config_font_overlay_remove(text_class);
1635 * Apply the changes made with elm_font_overlay_set() and
1636 * elm_font_overlay_unset() on the current Elementary window.
1640 * This applies all font overlays set to all objects in the UI.
1643 elm_font_overlay_apply(void)
1645 _elm_config_font_overlay_apply();
1649 * Apply the changes made with elm_font_overlay_set() and
1650 * elm_font_overlay_unset() on all Elementary application windows.
1654 * This applies all font overlays set to all objects in the UI.
1657 elm_font_overlay_all_apply(void)
1659 #ifdef HAVE_ELEMENTARY_X
1660 static Ecore_X_Atom atom = 0;
1661 unsigned int dummy = (unsigned int)(1 * 1000.0);
1663 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FONT_OVERLAY");
1664 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(), atom, &dummy,
1670 * Translate a font (family) name string in fontconfig's font names
1671 * syntax into an @c Elm_Font_Properties struct.
1673 * @param font The font name and styles string
1674 * @return the font properties struct
1678 * @note The reverse translation can be achived with
1679 * elm_font_fontconfig_name_get(), for one style only (single font
1680 * instance, not family).
1682 EAPI Elm_Font_Properties *
1683 elm_font_properties_get(const char *font)
1685 EINA_SAFETY_ON_NULL_RETURN_VAL(font, NULL);
1686 return _elm_font_properties_get(NULL, font);
1690 * Free font properties return by elm_font_properties_get().
1692 * @param efp the font properties struct
1697 elm_font_properties_free(Elm_Font_Properties *efp)
1701 EINA_SAFETY_ON_NULL_RETURN(efp);
1702 EINA_LIST_FREE(efp->styles, str)
1703 if (str) eina_stringshare_del(str);
1704 if (efp->name) eina_stringshare_del(efp->name);
1709 * Translate a font name, bound to a style, into fontconfig's font names
1712 * @param name The font (family) name
1713 * @param style The given style (may be @c NULL)
1715 * @return the font name and style string
1719 * @note The reverse translation can be achived with
1720 * elm_font_properties_get(), for one style only (single font
1721 * instance, not family).
1724 elm_font_fontconfig_name_get(const char *name,
1729 EINA_SAFETY_ON_NULL_RETURN_VAL(name, NULL);
1730 if (!style || style[0] == 0) return eina_stringshare_add(name);
1731 snprintf(buf, 256, "%s" ELM_FONT_TOKEN_STYLE "%s", name, style);
1732 return eina_stringshare_add(buf);
1736 * Free the font string return by elm_font_fontconfig_name_get().
1738 * @param efp the font properties struct
1743 elm_font_fontconfig_name_free(const char *name)
1745 eina_stringshare_del(name);
1749 * Create a font hash table of available system fonts.
1751 * One must call it with @p list being the return value of
1752 * evas_font_available_list(). The hash will be indexed by font
1753 * (family) names, being its values @c Elm_Font_Properties blobs.
1755 * @param list The list of available system fonts, as returned by
1756 * evas_font_available_list().
1757 * @return the font hash.
1761 * @note The user is supposed to get it populated at least with 3
1762 * default font families (Sans, Serif, Monospace), which should be
1763 * present on most systems.
1766 elm_font_available_hash_add(Eina_List *list)
1768 Eina_Hash *font_hash;
1774 /* populate with default font families */
1775 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Regular");
1776 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Bold");
1777 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Oblique");
1778 font_hash = _elm_font_available_hash_add(font_hash,
1779 "Sans:style=Bold Oblique");
1781 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Regular");
1782 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Bold");
1783 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Oblique");
1784 font_hash = _elm_font_available_hash_add(font_hash,
1785 "Serif:style=Bold Oblique");
1787 font_hash = _elm_font_available_hash_add(font_hash,
1788 "Monospace:style=Regular");
1789 font_hash = _elm_font_available_hash_add(font_hash,
1790 "Monospace:style=Bold");
1791 font_hash = _elm_font_available_hash_add(font_hash,
1792 "Monospace:style=Oblique");
1793 font_hash = _elm_font_available_hash_add(font_hash,
1794 "Monospace:style=Bold Oblique");
1796 EINA_LIST_FOREACH(list, l, key)
1797 font_hash = _elm_font_available_hash_add(font_hash, key);
1803 * Free the hash return by elm_font_available_hash_add().
1805 * @param hash the hash to be freed.
1810 elm_font_available_hash_del(Eina_Hash *hash)
1812 _elm_font_available_hash_del(hash);
1816 * @defgroup Fingers Fingers
1819 * Elementary is designed to be finger-friendly for touchscreens, and so in
1820 * addition to scaling for display resolution, it can also scale based on
1821 * finger "resolution" (or size).
1825 * Get the configured finger size
1827 * This gets the globally configured finger size in pixels
1829 * @return The finger size
1833 elm_finger_size_get(void)
1835 return _elm_config->finger_size;
1839 * Set the configured finger size
1841 * This sets the globally configured finger size in pixels
1843 * @param size The finger size
1847 elm_finger_size_set(Evas_Coord size)
1849 if (_elm_config->finger_size == size) return;
1850 _elm_config->finger_size = size;
1855 * Set the configured finger size for all applications on the display
1857 * This sets the globally configured finger size in pixels for all applications
1860 * @param size The finger size
1864 elm_finger_size_all_set(Evas_Coord size)
1866 #ifdef HAVE_ELEMENTARY_X
1867 static Ecore_X_Atom atom = 0;
1868 unsigned int size_i = (unsigned int)size;
1870 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FINGER_SIZE");
1871 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1877 elm_autocapitalization_allow_all_set(Eina_Bool on)
1879 #ifdef HAVE_ELEMENTARY_X
1880 static Ecore_X_Atom atom = 0;
1881 unsigned int on_i = (unsigned int)on;
1883 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_AUTOCAPITAL_ALLOW");
1884 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1890 elm_autoperiod_allow_all_set(Eina_Bool on)
1892 #ifdef HAVE_ELEMENTARY_X
1893 static Ecore_X_Atom atom = 0;
1894 unsigned int on_i = (unsigned int)on;
1896 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_AUTOPERIOD_ALLOW");
1897 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1902 * Adjust size of an element for finger usage
1904 * This takes width and height sizes (in pixels) as input and a size multiple
1905 * (which is how many fingers you want to place within the area), and adjusts
1906 * the size tobe large enough to accommodate finger. On return the w and h
1907 * sizes poiner do by these parameters will be modified.
1909 * @param times_w How many fingers should fit horizontally
1910 * @param w Pointer to the width size to adjust
1911 * @param times_h How many fingers should fit vertically
1912 * @param h Pointer to the height size to adjust
1916 elm_coords_finger_size_adjust(int times_w,
1921 if ((w) && (*w < (_elm_config->finger_size * times_w)))
1922 *w = _elm_config->finger_size * times_w;
1923 if ((h) && (*h < (_elm_config->finger_size * times_h)))
1924 *h = _elm_config->finger_size * times_h;
1928 * @defgroup Caches Caches
1931 * These are functions which let one fine-tune some cache values for
1932 * Elementary applications, thus allowing for performance adjustments.
1936 * Flush all caches & dump all data that can be to lean down to use
1947 edje_file_cache_flush();
1948 edje_collection_cache_flush();
1950 EINA_LIST_FOREACH(_elm_win_list, l, obj)
1952 Evas *e = evas_object_evas_get(obj);
1953 evas_image_cache_flush(e);
1954 evas_font_cache_flush(e);
1955 evas_render_dump(e);
1960 * Get the configured cache flush interval time
1962 * This gets the globally configured cache flush interval time, in
1965 * @return The cache flush interval time
1968 * @see elm_all_flush()
1971 elm_cache_flush_interval_get(void)
1973 return _elm_config->cache_flush_poll_interval;
1977 * Set the configured cache flush interval time
1979 * This sets the globally configured cache flush interval time, in ticks
1981 * @param size The cache flush interval time
1984 * @see elm_all_flush()
1987 elm_cache_flush_interval_set(int size)
1989 if (_elm_config->cache_flush_poll_interval == size) return;
1990 _elm_config->cache_flush_poll_interval = size;
1996 * Set the configured cache flush interval time for all applications on the
1999 * This sets the globally configured cache flush interval time -- in ticks
2000 * -- for all applications on the display.
2002 * @param size The cache flush interval time
2006 elm_cache_flush_interval_all_set(int size)
2008 #ifdef HAVE_ELEMENTARY_X
2009 static Ecore_X_Atom atom = 0;
2010 unsigned int size_i = (unsigned int)size;
2012 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_CACHE_FLUSH_INTERVAL");
2013 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2019 * Get the configured cache flush enabled state
2021 * This gets the globally configured cache flush state - if it is enabled
2022 * or not. When cache flushing is enabled, elementary will regularly
2023 * (see elm_cache_flush_interval_get() ) flush caches and dump data out of
2024 * memory and allow usage to re-seed caches and data in memory where it
2025 * can do so. An idle application will thus minimise its memory usage as
2026 * data will be freed from memory and not be re-loaded as it is idle and
2027 * not rendering or doing anything graphically right now.
2029 * @return The cache flush state
2032 * @see elm_all_flush()
2035 elm_cache_flush_enabled_get(void)
2037 return _elm_config->cache_flush_enable;
2041 * Set the configured cache flush enabled state
2043 * This sets the globally configured cache flush enabled state
2045 * @param size The cache flush enabled state
2048 * @see elm_all_flush()
2051 elm_cache_flush_enabled_set(Eina_Bool enabled)
2053 enabled = !!enabled;
2054 if (_elm_config->cache_flush_enable == enabled) return;
2055 _elm_config->cache_flush_enable = enabled;
2061 * Set the configured cache flush enabled state for all applications on the
2064 * This sets the globally configured cache flush enabled state for all
2065 * applications on the display.
2067 * @param size The cache flush enabled state
2071 elm_cache_flush_enabled_all_set(Eina_Bool enabled)
2073 #ifdef HAVE_ELEMENTARY_X
2074 static Ecore_X_Atom atom = 0;
2075 unsigned int enabled_i = (unsigned int)enabled;
2077 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_CACHE_FLUSH_ENABLE");
2078 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2079 atom, &enabled_i, 1);
2084 * Get the configured font cache size
2086 * This gets the globally configured font cache size, in bytes
2088 * @return The font cache size
2092 elm_font_cache_get(void)
2094 return _elm_config->font_cache;
2098 * Set the configured font cache size
2100 * This sets the globally configured font cache size, in bytes
2102 * @param size The font cache size
2106 elm_font_cache_set(int size)
2108 if (_elm_config->font_cache == size) return;
2109 _elm_config->font_cache = size;
2115 * Set the configured font cache size for all applications on the
2118 * This sets the globally configured font cache size -- in bytes
2119 * -- for all applications on the display.
2121 * @param size The font cache size
2125 elm_font_cache_all_set(int size)
2127 #ifdef HAVE_ELEMENTARY_X
2128 static Ecore_X_Atom atom = 0;
2129 unsigned int size_i = (unsigned int)size;
2131 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FONT_CACHE");
2132 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2138 * Get the configured image cache size
2140 * This gets the globally configured image cache size, in bytes
2142 * @return The image cache size
2146 elm_image_cache_get(void)
2148 return _elm_config->image_cache;
2152 * Set the configured image cache size
2154 * This sets the globally configured image cache size, in bytes
2156 * @param size The image cache size
2160 elm_image_cache_set(int size)
2162 if (_elm_config->image_cache == size) return;
2163 _elm_config->image_cache = size;
2169 * Set the configured image cache size for all applications on the
2172 * This sets the globally configured image cache size -- in bytes
2173 * -- for all applications on the display.
2175 * @param size The image cache size
2179 elm_image_cache_all_set(int size)
2181 #ifdef HAVE_ELEMENTARY_X
2182 static Ecore_X_Atom atom = 0;
2183 unsigned int size_i = (unsigned int)size;
2185 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_IMAGE_CACHE");
2186 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2192 * Get the configured edje file cache size.
2194 * This gets the globally configured edje file cache size, in number
2197 * @return The edje file cache size
2201 elm_edje_file_cache_get(void)
2203 return _elm_config->edje_cache;
2207 * Set the configured edje file cache size
2209 * This sets the globally configured edje file cache size, in number
2212 * @param size The edje file cache size
2216 elm_edje_file_cache_set(int size)
2218 if (_elm_config->edje_cache == size) return;
2219 _elm_config->edje_cache = size;
2225 * Set the configured edje file cache size for all applications on the
2228 * This sets the globally configured edje file cache size -- in number
2229 * of files -- for all applications on the display.
2231 * @param size The edje file cache size
2235 elm_edje_file_cache_all_set(int size)
2237 #ifdef HAVE_ELEMENTARY_X
2238 static Ecore_X_Atom atom = 0;
2239 unsigned int size_i = (unsigned int)size;
2241 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_EDJE_FILE_CACHE");
2242 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2248 * Get the configured edje collections (groups) cache size.
2250 * This gets the globally configured edje collections cache size, in
2251 * number of collections.
2253 * @return The edje collections cache size
2257 elm_edje_collection_cache_get(void)
2259 return _elm_config->edje_collection_cache;
2263 * Set the configured edje collections (groups) cache size
2265 * This sets the globally configured edje collections cache size, in
2266 * number of collections.
2268 * @param size The edje collections cache size
2272 elm_edje_collection_cache_set(int size)
2274 if (_elm_config->edje_collection_cache == size) return;
2275 _elm_config->edje_collection_cache = size;
2281 * Set the configured edje collections (groups) cache size for all
2282 * applications on the display
2284 * This sets the globally configured edje collections cache size -- in
2285 * number of collections -- for all applications on the display.
2287 * @param size The edje collections cache size
2291 elm_edje_collection_cache_all_set(int size)
2293 #ifdef HAVE_ELEMENTARY_X
2294 static Ecore_X_Atom atom = 0;
2295 unsigned int size_i = (unsigned int)size;
2297 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_EDJE_COLLECTION_CACHE");
2298 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2304 * @defgroup Focus Focus
2307 * Objects have focus. This is what determines where the keyboard input goes to
2308 * within the application window.
2312 * Get the focus of the object
2314 * This gets the focused property of the object.
2316 * @param obj The object
2317 * @return 1 if the object is focused, 0 if not.
2321 elm_object_focus_get(const Evas_Object *obj)
2323 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
2324 return elm_widget_focus_get(obj);
2328 * Set the focus to the object
2330 * This sets the focus target for keyboard input to be the object indicated.
2332 * @param obj The object
2336 elm_object_focus(Evas_Object *obj)
2338 EINA_SAFETY_ON_NULL_RETURN(obj);
2339 if (elm_widget_focus_get(obj))
2342 elm_widget_focus_cycle(obj, ELM_FOCUS_NEXT);
2346 * Remove the focus from the object
2348 * This removes the focus target for keyboard input from be the object
2351 * @param obj The object
2355 elm_object_unfocus(Evas_Object *obj)
2357 EINA_SAFETY_ON_NULL_RETURN(obj);
2358 if (!elm_widget_can_focus_get(obj)) return;
2359 elm_widget_focused_object_clear(obj);
2363 * Set the ability for the object to focus
2365 * This sets the ability for the object to be able to get keyboard focus or
2366 * not. By default all objects are able to be focused.
2368 * @param obj The object
2369 * @param enable 1 if the object can be focused, 0 if not
2373 elm_object_focus_allow_set(Evas_Object *obj,
2376 EINA_SAFETY_ON_NULL_RETURN(obj);
2377 elm_widget_can_focus_set(obj, enable);
2381 * Get the ability for the object to focus
2383 * This gets the ability for the object to be able to get keyboard focus or
2384 * not. By default all objects are able to be focused.
2386 * @param obj The object
2387 * @return 1 if the object is allowed to be focused, 0 if not.
2391 elm_object_focus_allow_get(const Evas_Object *obj)
2393 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
2394 return (elm_widget_can_focus_get(obj)) || (elm_widget_child_can_focus_get(obj));
2398 * Set custom focus chain.
2400 * This function i set one new and overwrite any previous custom focus chain
2401 * with the list of objects. The previous list will be deleted and this list
2402 * will be managed. After setted, don't modity it.
2404 * @note On focus cycle, only will be evaluated children of this container.
2406 * @param obj The container object
2407 * @param objs Chain of objects to pass focus
2411 elm_object_focus_custom_chain_set(Evas_Object *obj,
2414 EINA_SAFETY_ON_NULL_RETURN(obj);
2415 elm_widget_focus_custom_chain_set(obj, objs);
2419 * Unset custom focus chain
2421 * @param obj The container object
2425 elm_object_focus_custom_chain_unset(Evas_Object *obj)
2427 EINA_SAFETY_ON_NULL_RETURN(obj);
2428 elm_widget_focus_custom_chain_unset(obj);
2432 * Get custom focus chain
2434 * @param obj The container object
2437 EAPI const Eina_List *
2438 elm_object_focus_custom_chain_get(const Evas_Object *obj)
2440 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
2441 return elm_widget_focus_custom_chain_get(obj);
2445 * Append object to custom focus chain.
2447 * @note If relative_child equal to NULL or not in custom chain, the object
2448 * will be added in end.
2450 * @note On focus cycle, only will be evaluated children of this container.
2452 * @param obj The container object
2453 * @param child The child to be added in custom chain
2454 * @param relative_child The relative object to position the child
2458 elm_object_focus_custom_chain_append(Evas_Object *obj,
2460 Evas_Object *relative_child)
2462 EINA_SAFETY_ON_NULL_RETURN(obj);
2463 EINA_SAFETY_ON_NULL_RETURN(child);
2464 elm_widget_focus_custom_chain_append(obj, child, relative_child);
2468 * Prepend object to custom focus chain.
2470 * @note If relative_child equal to NULL or not in custom chain, the object
2471 * will be added in begin.
2473 * @note On focus cycle, only will be evaluated children of this container.
2475 * @param obj The container object
2476 * @param child The child to be added in custom chain
2477 * @param relative_child The relative object to position the child
2481 elm_object_focus_custom_chain_prepend(Evas_Object *obj,
2483 Evas_Object *relative_child)
2485 EINA_SAFETY_ON_NULL_RETURN(obj);
2486 EINA_SAFETY_ON_NULL_RETURN(child);
2487 elm_widget_focus_custom_chain_prepend(obj, child, relative_child);
2491 * Give focus to next object in object tree.
2493 * Give focus to next object in focus chain of one object sub-tree.
2494 * If the last object of chain already have focus, the focus will go to the
2495 * first object of chain.
2497 * @param obj The object root of sub-tree
2498 * @param dir Direction to cycle the focus
2503 elm_object_focus_cycle(Evas_Object *obj,
2504 Elm_Focus_Direction dir)
2506 EINA_SAFETY_ON_NULL_RETURN(obj);
2507 elm_widget_focus_cycle(obj, dir);
2511 * Give focus to near object in one direction.
2513 * Give focus to near object in direction of one object.
2514 * If none focusable object in given direction, the focus will not change.
2516 * @param obj The reference object
2517 * @param x Horizontal component of direction to focus
2518 * @param y Vertical component of direction to focus
2523 elm_object_focus_direction_go(Evas_Object *obj,
2527 EINA_SAFETY_ON_NULL_RETURN(obj);
2528 elm_widget_focus_direction_go(obj, x, y);
2532 * Get the enable status of the focus highlight
2534 * This gets whether the highlight on focused objects is enabled or not
2538 elm_focus_highlight_enabled_get(void)
2540 return _elm_config->focus_highlight_enable;
2544 * Set the enable status of the focus highlight
2546 * Set whether to show or not the highlight on focused objects
2547 * @param enable Enable highlight if EINA_TRUE, disable otherwise
2551 elm_focus_highlight_enabled_set(Eina_Bool enable)
2553 _elm_config->focus_highlight_enable = !!enable;
2557 * Get the enable status of the highlight animation
2559 * Get whether the focus highlight, if enabled, will animate its switch from
2560 * one object to the next
2564 elm_focus_highlight_animate_get(void)
2566 return _elm_config->focus_highlight_animate;
2570 * Set the enable status of the highlight animation
2572 * Set whether the focus highlight, if enabled, will animate its switch from
2573 * one object to the next
2574 * @param animate Enable animation if EINA_TRUE, disable otherwise
2578 elm_focus_highlight_animate_set(Eina_Bool animate)
2580 _elm_config->focus_highlight_animate = !!animate;
2584 * @defgroup Scrolling Scrolling
2587 * These are functions setting how scrollable views in Elementary
2588 * widgets should behave on user interaction.
2592 * Get whether scrollers should bounce when they reach their
2593 * viewport's edge during a scroll.
2595 * @return the thumb scroll bouncing state
2597 * This is the default behavior for touch screens, in general.
2598 * @ingroup Scrolling
2601 elm_scroll_bounce_enabled_get(void)
2603 return _elm_config->thumbscroll_bounce_enable;
2607 * Set whether scrollers should bounce when they reach their
2608 * viewport's edge during a scroll.
2610 * @param enabled the thumb scroll bouncing state
2612 * @see elm_thumbscroll_bounce_enabled_get()
2613 * @ingroup Scrolling
2616 elm_scroll_bounce_enabled_set(Eina_Bool enabled)
2618 _elm_config->thumbscroll_bounce_enable = enabled;
2622 * Set whether scrollers should bounce when they reach their
2623 * viewport's edge during a scroll, for all Elementary application
2626 * @param enabled the thumb scroll bouncing state
2628 * @see elm_thumbscroll_bounce_enabled_get()
2629 * @ingroup Scrolling
2632 elm_scroll_bounce_enabled_all_set(Eina_Bool enabled)
2634 #ifdef HAVE_ELEMENTARY_X
2635 static Ecore_X_Atom atom = 0;
2636 unsigned int bounce_enable_i = (unsigned int)enabled;
2639 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BOUNCE_ENABLE");
2640 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2641 atom, &bounce_enable_i, 1);
2646 * Get the amount of inertia a scroller will impose at bounce
2649 * @return the thumb scroll bounce friction
2651 * @ingroup Scrolling
2654 elm_scroll_bounce_friction_get(void)
2656 return _elm_config->thumbscroll_bounce_friction;
2660 * Set the amount of inertia a scroller will impose at bounce
2663 * @param friction the thumb scroll bounce friction
2665 * @see elm_thumbscroll_bounce_friction_get()
2666 * @ingroup Scrolling
2669 elm_scroll_bounce_friction_set(double friction)
2671 _elm_config->thumbscroll_bounce_friction = friction;
2675 * Set the amount of inertia a scroller will impose at bounce
2676 * animations, for all Elementary application windows.
2678 * @param friction the thumb scroll bounce friction
2680 * @see elm_thumbscroll_bounce_friction_get()
2681 * @ingroup Scrolling
2684 elm_scroll_bounce_friction_all_set(double friction)
2686 #ifdef HAVE_ELEMENTARY_X
2687 static Ecore_X_Atom atom = 0;
2688 unsigned int bounce_friction_i = (unsigned int)(friction * 1000.0);
2691 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BOUNCE_FRICTION");
2692 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2693 atom, &bounce_friction_i, 1);
2698 * Get the amount of inertia a <b>paged</b> scroller will impose at
2699 * page fitting animations.
2701 * @return the page scroll friction
2703 * @ingroup Scrolling
2706 elm_scroll_page_scroll_friction_get(void)
2708 return _elm_config->page_scroll_friction;
2712 * Set the amount of inertia a <b>paged</b> scroller will impose at
2713 * page fitting animations.
2715 * @param friction the page scroll friction
2717 * @see elm_thumbscroll_page_scroll_friction_get()
2718 * @ingroup Scrolling
2721 elm_scroll_page_scroll_friction_set(double friction)
2723 _elm_config->page_scroll_friction = friction;
2727 * Set the amount of inertia a <b>paged</b> scroller will impose at
2728 * page fitting animations, for all Elementary application windows.
2730 * @param friction the page scroll friction
2732 * @see elm_thumbscroll_page_scroll_friction_get()
2733 * @ingroup Scrolling
2736 elm_scroll_page_scroll_friction_all_set(double friction)
2738 #ifdef HAVE_ELEMENTARY_X
2739 static Ecore_X_Atom atom = 0;
2740 unsigned int page_scroll_friction_i = (unsigned int)(friction * 1000.0);
2743 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_PAGE_SCROLL_FRICTION");
2744 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2745 atom, &page_scroll_friction_i, 1);
2750 * Get the amount of inertia a scroller will impose at region bring
2753 * @return the bring in scroll friction
2755 * @ingroup Scrolling
2758 elm_scroll_bring_in_scroll_friction_get(void)
2760 return _elm_config->bring_in_scroll_friction;
2764 * Set the amount of inertia a scroller will impose at region bring
2767 * @param friction the bring in scroll friction
2769 * @see elm_thumbscroll_bring_in_scroll_friction_get()
2770 * @ingroup Scrolling
2773 elm_scroll_bring_in_scroll_friction_set(double friction)
2775 _elm_config->bring_in_scroll_friction = friction;
2779 * Set the amount of inertia a scroller will impose at region bring
2780 * animations, for all Elementary application windows.
2782 * @param friction the bring in scroll friction
2784 * @see elm_thumbscroll_bring_in_scroll_friction_get()
2785 * @ingroup Scrolling
2788 elm_scroll_bring_in_scroll_friction_all_set(double friction)
2790 #ifdef HAVE_ELEMENTARY_X
2791 static Ecore_X_Atom atom = 0;
2792 unsigned int bring_in_scroll_friction_i = (unsigned int)(friction * 1000.0);
2796 ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BRING_IN_SCROLL_FRICTION");
2797 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2798 atom, &bring_in_scroll_friction_i, 1);
2803 * Get the amount of inertia scrollers will impose at animations
2804 * triggered by Elementary widgets' zooming API.
2806 * @return the zoom friction
2808 * @ingroup Scrolling
2811 elm_scroll_zoom_friction_get(void)
2813 return _elm_config->zoom_friction;
2817 * Set the amount of inertia scrollers will impose at animations
2818 * triggered by Elementary widgets' zooming API.
2820 * @param friction the zoom friction
2822 * @see elm_thumbscroll_zoom_friction_get()
2823 * @ingroup Scrolling
2826 elm_scroll_zoom_friction_set(double friction)
2828 _elm_config->zoom_friction = friction;
2832 * Set the amount of inertia scrollers will impose at animations
2833 * triggered by Elementary widgets' zooming API, for all Elementary
2834 * application windows.
2836 * @param friction the zoom friction
2838 * @see elm_thumbscroll_zoom_friction_get()
2839 * @ingroup Scrolling
2842 elm_scroll_zoom_friction_all_set(double friction)
2844 #ifdef HAVE_ELEMENTARY_X
2845 static Ecore_X_Atom atom = 0;
2846 unsigned int zoom_friction_i = (unsigned int)(friction * 1000.0);
2849 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_ZOOM_FRICTION");
2850 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2851 atom, &zoom_friction_i, 1);
2856 * Get whether scrollers should be draggable from any point in their
2859 * @return the thumb scroll state
2861 * @note This is the default behavior for touch screens, in general.
2862 * @note All other functions namespaced with "thumbscroll" will only
2863 * have effect if this mode is enabled.
2865 * @ingroup Scrolling
2868 elm_scroll_thumbscroll_enabled_get(void)
2870 return _elm_config->thumbscroll_enable;
2874 * Set whether scrollers should be draggable from any point in their
2877 * @param enabled the thumb scroll state
2879 * @see elm_thumbscroll_enabled_get()
2880 * @ingroup Scrolling
2883 elm_scroll_thumbscroll_enabled_set(Eina_Bool enabled)
2885 _elm_config->thumbscroll_enable = enabled;
2889 * Set whether scrollers should be draggable from any point in their
2890 * views, for all Elementary application windows.
2892 * @param enabled the thumb scroll state
2894 * @see elm_thumbscroll_enabled_get()
2895 * @ingroup Scrolling
2898 elm_scroll_thumbscroll_enabled_all_set(Eina_Bool enabled)
2900 #ifdef HAVE_ELEMENTARY_X
2901 static Ecore_X_Atom atom = 0;
2902 unsigned int ts_enable_i = (unsigned int)enabled;
2904 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_ENABLE");
2905 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2906 atom, &ts_enable_i, 1);
2911 * Get the number of pixels one should travel while dragging a
2912 * scroller's view to actually trigger scrolling.
2914 * @return the thumb scroll threshould
2916 * One would use higher values for touch screens, in general, because
2917 * of their inherent imprecision.
2918 * @ingroup Scrolling
2921 elm_scroll_thumbscroll_threshold_get(void)
2923 return _elm_config->thumbscroll_threshold;
2927 * Set the number of pixels one should travel while dragging a
2928 * scroller's view to actually trigger scrolling.
2930 * @param threshold the thumb scroll threshould
2932 * @see elm_thumbscroll_threshould_get()
2933 * @ingroup Scrolling
2936 elm_scroll_thumbscroll_threshold_set(unsigned int threshold)
2938 _elm_config->thumbscroll_threshold = threshold;
2942 * Set the number of pixels one should travel while dragging a
2943 * scroller's view to actually trigger scrolling, for all Elementary
2944 * application windows.
2946 * @param threshold the thumb scroll threshould
2948 * @see elm_thumbscroll_threshould_get()
2949 * @ingroup Scrolling
2952 elm_scroll_thumbscroll_threshold_all_set(unsigned int threshold)
2954 #ifdef HAVE_ELEMENTARY_X
2955 static Ecore_X_Atom atom = 0;
2956 unsigned int ts_threshold_i = (unsigned int)threshold;
2958 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_THRESHOLD");
2959 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2960 atom, &ts_threshold_i, 1);
2965 * Get the minimum speed of mouse cursor movement which will trigger
2966 * list self scrolling animation after a mouse up event
2969 * @return the thumb scroll momentum threshould
2971 * @ingroup Scrolling
2974 elm_scroll_thumbscroll_momentum_threshold_get(void)
2976 return _elm_config->thumbscroll_momentum_threshold;
2980 * Set the minimum speed of mouse cursor movement which will trigger
2981 * list self scrolling animation after a mouse up event
2984 * @param threshold the thumb scroll momentum threshould
2986 * @see elm_thumbscroll_momentum_threshould_get()
2987 * @ingroup Scrolling
2990 elm_scroll_thumbscroll_momentum_threshold_set(double threshold)
2992 _elm_config->thumbscroll_momentum_threshold = threshold;
2996 * Set the minimum speed of mouse cursor movement which will trigger
2997 * list self scrolling animation after a mouse up event
2998 * (pixels/second), for all Elementary application windows.
3000 * @param threshold the thumb scroll momentum threshould
3002 * @see elm_thumbscroll_momentum_threshould_get()
3003 * @ingroup Scrolling
3006 elm_scroll_thumbscroll_momentum_threshold_all_set(double threshold)
3008 #ifdef HAVE_ELEMENTARY_X
3009 static Ecore_X_Atom atom = 0;
3010 unsigned int ts_momentum_threshold_i = (unsigned int)(threshold * 1000.0);
3013 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_MOMENTUM_THRESHOLD");
3014 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
3015 atom, &ts_momentum_threshold_i, 1);
3020 * Get the amount of inertia a scroller will impose at self scrolling
3023 * @return the thumb scroll friction
3025 * @ingroup Scrolling
3028 elm_scroll_thumbscroll_friction_get(void)
3030 return _elm_config->thumbscroll_friction;
3034 * Set the amount of inertia a scroller will impose at self scrolling
3037 * @param friction the thumb scroll friction
3039 * @see elm_thumbscroll_friction_get()
3040 * @ingroup Scrolling
3043 elm_scroll_thumbscroll_friction_set(double friction)
3045 _elm_config->thumbscroll_friction = friction;
3049 * Set the amount of inertia a scroller will impose at self scrolling
3050 * animations, for all Elementary application windows.
3052 * @param friction the thumb scroll friction
3054 * @see elm_thumbscroll_friction_get()
3055 * @ingroup Scrolling
3058 elm_scroll_thumbscroll_friction_all_set(double friction)
3060 #ifdef HAVE_ELEMENTARY_X
3061 static Ecore_X_Atom atom = 0;
3062 unsigned int ts_friction_i = (unsigned int)(friction * 1000.0);
3064 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_FRICTION");
3065 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
3066 atom, &ts_friction_i, 1);
3071 * Get the amount of lag between your actual mouse cursor dragging
3072 * movement and a scroller's view movement itself, while pushing it
3073 * into bounce state manually.
3075 * @return the thumb scroll border friction
3077 * @ingroup Scrolling
3080 elm_scroll_thumbscroll_border_friction_get(void)
3082 return _elm_config->thumbscroll_border_friction;
3086 * Set the amount of lag between your actual mouse cursor dragging
3087 * movement and a scroller's view movement itself, while pushing it
3088 * into bounce state manually.
3090 * @param friction the thumb scroll border friction. @c 0.0 for
3091 * perfect synchrony between two movements, @c 1.0 for maximum
3094 * @see elm_thumbscroll_border_friction_get()
3095 * @note parameter value will get bound to 0.0 - 1.0 interval, always
3097 * @ingroup Scrolling
3100 elm_scroll_thumbscroll_border_friction_set(double friction)
3108 _elm_config->thumbscroll_friction = friction;
3112 * Set the amount of lag between your actual mouse cursor dragging
3113 * movement and a scroller's view movement itself, while pushing it
3114 * into bounce state manually, for all Elementary application windows.
3116 * @param friction the thumb scroll border friction. @c 0.0 for
3117 * perfect synchrony between two movements, @c 1.0 for maximum
3120 * @see elm_thumbscroll_border_friction_get()
3121 * @note parameter value will get bound to 0.0 - 1.0 interval, always
3123 * @ingroup Scrolling
3126 elm_scroll_thumbscroll_border_friction_all_set(double friction)
3134 #ifdef HAVE_ELEMENTARY_X
3135 static Ecore_X_Atom atom = 0;
3136 unsigned int border_friction_i = (unsigned int)(friction * 1000.0);
3139 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BORDER_FRICTION");
3140 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
3141 atom, &border_friction_i, 1);
3146 * @defgroup Scrollhints Scrollhints
3149 * Objects when inside a scroller can scroll, but this may not always be
3150 * desirable in certain situations. This allows an object to hint to itself
3151 * and parents to "not scroll" in one of 2 ways.
3153 * 1. To hold on scrolling. This means just flicking and dragging may no
3154 * longer scroll, but pressing/dragging near an edge of the scroller will
3155 * still scroll. This is automastically used by the entry object when
3157 * 2. To totally freeze scrolling. This means it stops. until popped/released.
3161 * Push the scroll hold by 1
3163 * This increments the scroll hold count by one. If it is more than 0 it will
3164 * take effect on the parents of the indicated object.
3166 * @param obj The object
3167 * @ingroup Scrollhints
3170 elm_object_scroll_hold_push(Evas_Object *obj)
3172 EINA_SAFETY_ON_NULL_RETURN(obj);
3173 elm_widget_scroll_hold_push(obj);
3177 * Pop the scroll hold by 1
3179 * This decrements the scroll hold count by one. If it is more than 0 it will
3180 * take effect on the parents of the indicated object.
3182 * @param obj The object
3183 * @ingroup Scrollhints
3186 elm_object_scroll_hold_pop(Evas_Object *obj)
3188 EINA_SAFETY_ON_NULL_RETURN(obj);
3189 elm_widget_scroll_hold_pop(obj);
3193 * Push the scroll freeze by 1
3195 * This increments the scroll freeze count by one. If it is more than 0 it will
3196 * take effect on the parents of the indicated object.
3198 * @param obj The object
3199 * @ingroup Scrollhints
3202 elm_object_scroll_freeze_push(Evas_Object *obj)
3204 EINA_SAFETY_ON_NULL_RETURN(obj);
3205 elm_widget_scroll_freeze_push(obj);
3209 * Lock the scrolling of the given widget (and thus all parents)
3211 * This locks the given object from scrolling in the X axis (and implicitly
3212 * also locks all parent scrollers too from doing the same).
3214 * @param obj The object
3215 * @param lock The lock state (1 == locked, 0 == unlocked)
3216 * @ingroup Scrollhints
3219 elm_object_scroll_lock_x_set(Evas_Object *obj,
3222 EINA_SAFETY_ON_NULL_RETURN(obj);
3223 elm_widget_drag_lock_x_set(obj, lock);
3227 * Lock the scrolling of the given widget (and thus all parents)
3229 * This locks the given object from scrolling in the Y axis (and implicitly
3230 * also locks all parent scrollers too from doing the same).
3232 * @param obj The object
3233 * @param lock The lock state (1 == locked, 0 == unlocked)
3234 * @ingroup Scrollhints
3237 elm_object_scroll_lock_y_set(Evas_Object *obj,
3240 EINA_SAFETY_ON_NULL_RETURN(obj);
3241 elm_widget_drag_lock_y_set(obj, lock);
3245 * Get the scrolling lock of the given widget
3247 * This gets the lock for X axis scrolling.
3249 * @param obj The object
3250 * @ingroup Scrollhints
3253 elm_object_scroll_lock_x_get(const Evas_Object *obj)
3255 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3256 return elm_widget_drag_lock_x_get(obj);
3260 * Get the scrolling lock of the given widget
3262 * This gets the lock for X axis scrolling.
3264 * @param obj The object
3265 * @ingroup Scrollhints
3268 elm_object_scroll_lock_y_get(const Evas_Object *obj)
3270 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3271 return elm_widget_drag_lock_y_get(obj);
3275 * Pop the scroll freeze by 1
3277 * This decrements the scroll freeze count by one. If it is more than 0 it will
3278 * take effect on the parents of the indicated object.
3280 * @param obj The object
3281 * @ingroup Scrollhints
3284 elm_object_scroll_freeze_pop(Evas_Object *obj)
3286 EINA_SAFETY_ON_NULL_RETURN(obj);
3287 elm_widget_scroll_freeze_pop(obj);
3291 * @defgroup WidgetNavigation Widget Tree Navigation.
3294 * How to check if an Evas Object is an Elementary widget? How to get
3295 * the first elementary widget that is parent of the given object?
3296 * These are all covered in widget tree navigation.
3300 * Check if the given Evas Object is an Elementary widget.
3302 * @param obj the object to query.
3303 * @return @c EINA_TRUE if it is an elementary widget variant,
3304 * @c EINA_FALSE otherwise
3305 * @ingroup WidgetNavigation
3308 elm_object_widget_check(const Evas_Object *obj)
3310 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3311 return elm_widget_is(obj);
3315 * Get the first parent of the given object that is an Elementary widget.
3317 * @param obj the object to query.
3318 * @return the parent object that is an Elementary widget, or @c NULL
3319 * if no parent is, or no parents at all.
3320 * @ingroup WidgetNavigation
3323 elm_object_parent_widget_get(const Evas_Object *obj)
3325 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3326 return elm_widget_parent_widget_get(obj);
3330 * Get the top level parent of an Elementary widget.
3332 * @param obj The object to query.
3333 * @return The top level Elementary widget, or @c NULL if parent cannot be
3335 * @ingroup WidgetNavigation
3338 elm_object_top_widget_get(const Evas_Object *obj)
3340 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3341 return elm_widget_top_get(obj);
3345 * Get the string that represents this Elementary widget.
3347 * @note Elementary is weird and exposes itself as a single
3348 * Evas_Object_Smart_Class of type "elm_widget", so
3349 * evas_object_type_get() always return that, making debug and
3350 * language bindings hard. This function tries to mitigate this
3351 * problem, but the solution is to change Elementary to use
3352 * proper inheritance.
3354 * @param obj the object to query.
3355 * @return Elementary widget name, or @c NULL if not a valid widget.
3356 * @ingroup WidgetNavigation
3359 elm_object_widget_type_get(const Evas_Object *obj)
3361 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3362 return elm_widget_type_get(obj);
3366 * Send a signal to the widget edje object.
3368 * This function sends a signal to the edje object of the obj. An edje program
3369 * can respond to a signal by specifying matching 'signal' and
3372 * @param obj The object
3373 * @param emission The signal's name.
3374 * @param source The signal's source.
3378 elm_object_signal_emit(Evas_Object *obj,
3379 const char *emission,
3382 EINA_SAFETY_ON_NULL_RETURN(obj);
3383 elm_widget_signal_emit(obj, emission, source);
3387 * Add a callback for a signal emitted by widget edje object.
3389 * This function connects a callback function to a signal emitted by the
3390 * edje object of the obj.
3391 * Globs can occur in either the emission or source name.
3393 * @param obj The object
3394 * @param emission The signal's name.
3395 * @param source The signal's source.
3396 * @param func The callback function to be executed when the signal is
3398 * @param data A pointer to data to pass in to the callback function.
3402 elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, void (*func) (void *data, Evas_Object *o, const char *emission, const char *source), void *data)
3404 EINA_SAFETY_ON_NULL_RETURN(obj);
3405 EINA_SAFETY_ON_NULL_RETURN(func);
3406 elm_widget_signal_callback_add(obj, emission, source, func, data);
3410 * Remove a signal-triggered callback from an widget edje object.
3412 * This function removes a callback, previoulsy attached to a signal emitted
3413 * by the edje object of the obj.
3414 * The parameters emission, source and func must match exactly those passed to
3415 * a previous call to elm_object_signal_callback_add(). The data pointer that
3416 * was passed to this call will be returned.
3418 * @param obj The object
3419 * @param emission The signal's name.
3420 * @param source The signal's source.
3421 * @param func The callback function to be executed when the signal is
3423 * @return The data pointer
3427 elm_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, void (*func) (void *data, Evas_Object *o, const char *emission, const char *source))
3429 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3430 EINA_SAFETY_ON_NULL_RETURN_VAL(func, NULL);
3431 return elm_widget_signal_callback_del(obj, emission, source, func);
3435 * Add a callback for a event emitted by widget or their children.
3437 * This function connects a callback function to any key_down key_up event
3438 * emitted by the @p obj or their children.
3439 * This only will be called if no other callback has consumed the event.
3440 * If you want consume the event, and no other get it, func should return
3441 * EINA_TRUE and put EVAS_EVENT_FLAG_ON_HOLD in event_flags.
3443 * @warning Accept duplicated callback addition.
3445 * @param obj The object
3446 * @param func The callback function to be executed when the event is
3448 * @param data Data to pass in to the callback function.
3452 elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data)
3454 EINA_SAFETY_ON_NULL_RETURN(obj);
3455 EINA_SAFETY_ON_NULL_RETURN(func);
3456 elm_widget_event_callback_add(obj, func, data);
3460 * Remove a event callback from an widget.
3462 * This function removes a callback, previoulsy attached to event emission
3464 * The parameters func and data must match exactly those passed to
3465 * a previous call to elm_object_event_callback_add(). The data pointer that
3466 * was passed to this call will be returned.
3468 * @param obj The object
3469 * @param func The callback function to be executed when the event is
3471 * @param data Data to pass in to the callback function.
3472 * @return The data pointer
3476 elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data)
3478 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3479 EINA_SAFETY_ON_NULL_RETURN_VAL(func, NULL);
3480 return elm_widget_event_callback_del(obj, func, data);
3485 * @defgroup Debug Debug
3490 * Print Tree object hierarchy in stdout
3492 * @param obj The root object
3496 elm_object_tree_dump(const Evas_Object *top)
3499 elm_widget_tree_dump(top);
3507 * Print Elm Objects tree hierarchy in file as dot(graphviz) syntax.
3509 * @param obj The root object
3510 * @param file The path of output file
3514 elm_object_tree_dot_dump(const Evas_Object *top,
3518 FILE *f = fopen(file, "w");
3519 elm_widget_tree_dot_dump(top, f);
3529 * Set the duration for occuring long press event.
3531 * @param lonpress_timeout Timeout for long press event
3532 * @ingroup Longpress
3535 elm_longpress_timeout_set(double longpress_timeout)
3537 _elm_config->longpress_timeout = longpress_timeout;
3541 * Get the duration for occuring long press event.
3543 * @return Timeout for long press event
3544 * @ingroup Longpress
3547 elm_longpress_timeout_get(void)
3549 return _elm_config->longpress_timeout;