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;
24 _elm_dangerous_call_check(const char *call)
29 snprintf(buf, sizeof(buf), "%i.%i.%i.%i", VMAJ, VMIN, VMIC, VREV);
30 eval = getenv("ELM_NO_FINGER_WAGGLING");
31 if ((eval) && (!strcmp(eval, buf)))
33 printf("ELEMENTARY FINGER WAGGLE!!!!!!!!!!\n"
36 "PLEASE see the API documentation for this function. This call\n"
37 "should almost never be used. Only in very special cases.\n"
39 "To remove this warning please set the environment variable:\n"
40 " ELM_NO_FINGER_WAGGLING\n"
41 "To the value of the Elementary version + revision number. e.g.:\n"
50 * @defgroup Start Getting Started
52 * To write an Elementary app, you can get started with the following:
55 * #include <Elementary.h>
56 * #ifndef ELM_LIB_QUICKLAUNCH
58 * elm_main(int argc, char **argv)
60 * // create window(s) here and do any application init
61 * elm_run(); // run main loop
62 * elm_shutdown(); // after mainloop finishes running, shutdown
63 * return 0; // exit 0 for exit code
69 * To take full advantage of the quicklaunch architecture for launching
70 * processes as quickly as possible (saving time at startup time like
71 * connecting to X11, loading and linking shared libraries) you may want to
72 * use the following configure.in/configure.ac and Makefile.am and autogen.sh
73 * script to generate your files. It is assumed your application uses the
74 * main.c file for its code.
76 * configure.in/configure.ac:
79 AC_INIT(myapp, 0.0.0, myname@mydomain.com)
81 AC_CONFIG_SRCDIR(configure.in)
83 AM_INIT_AUTOMAKE(1.6 dist-bzip2)
84 AM_CONFIG_HEADER(config.h)
94 define([AC_LIBTOOL_LANG_CXX_CONFIG], [:])dnl
95 define([AC_LIBTOOL_LANG_F77_CONFIG], [:])dnl
98 PKG_CHECK_MODULES([ELEMENTARY], elementary)
106 AUTOMAKE_OPTIONS = 1.4 foreign
107 MAINTAINERCLEANFILES = Makefile.in
109 INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@
112 myapp_LTLIBRARIES = myapp.la
116 myapp_la_SOURCES = main.c
117 myapp_la_LIBADD = @ELEMENTARY_LIBS@
119 myapp_la_LDFLAGS = -module -avoid-version -no-undefined
121 myapp_SOURCES = main.c
122 myapp_LDADD = @ELEMENTARY_LIBS@
123 myapp_CFLAGS = -DELM_LIB_QUICKLAUNCH=1
130 rm -rf autom4te.cache
131 rm -f aclocal.m4 ltmain.sh
136 echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS -I m4 || exit 1
137 echo "Running autoheader..." ; autoheader || exit 1
138 echo "Running autoconf..." ; autoconf || exit 1
139 echo "Running libtoolize..." ; (libtoolize --copy --automake || glibtoolize --automake) || exit 1
140 echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1
142 if [ -z "$NOCONFIGURE" ]; then
147 * To gnerate all the things needed to bootstrap just run:
153 * This will generate Makefile.in's, the confgure script and everything else.
154 * After this it works like all normal autotools projects:
161 * Note sudo was assumed to get root permissions, as this would install in
162 * /usr/local which is system-owned. Ue any way you like to gain root, or
163 * specify a different prefix with configure:
166 ./confiugre --prefix=$HOME/mysoftware
169 * Also remember that autotools buys you some useful commands like:
174 * This uninstalls the software after it was installed with "make install".
175 * It is very useful to clear up what you built if you wish to clean the
182 * This firstly checks if your build tree is "clean" and ready for
183 * distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is
184 * ready to upload and distribute to the world, that contains the generated
185 * Makefile.in's and configure script. The users do not need to run
186 * autogen.sh - just configure and on. They don't need autotools installed.
187 * This tarball also builds cleanly, has all the sources it needs to build
188 * included (that is sources for your application, not libraries it depends
189 * on like Elementary). It builds cleanly in a buildroot and does not
190 * contain any files that are temporarily generated like binaries and other
191 * build-gnerated files, so the tarball is clean, and no need to worry
192 * about cleaning up your tree before packaging.
198 * This cleans up all build files (binaries, objects etc.) from the tree.
204 * This cleans out all files from the build and from configure's output too.
207 make maintainer-clean
210 * This deletes all the files autogen.sh will produce so the tree is clean
211 * to be put into a revision-control system (like CVS, SVN or GIT for example).
213 * The above will build a library - libmyapp.so and install in the target
214 * library directory (default is /usr/local/lib). You will also get a
215 * myapp.a and myapp.la - these are useless and can be deleted. Libtool likes
216 * to generate these all the time. You will also get a binary in the target
217 * binary directory (default is /usr/local/bin). This is a "debug binary".
218 * This will run and dlopen() the myapp.so and then jump to it's elm_main
219 * function. This allows for easy debugging with GDB and Valgrind. When you
220 * are ready to go to production do the following:
222 * 1. delete the myapp binary. i.e. rm /usr/local/bin/myapp
224 * 2. symlink the myapp binary to elementary_run (supplied by elementary).
225 * i.e. ln -s elmentary_run /usr/local/bin/myapp
227 * 3. run elementary_quicklaunch as part of your graphical login session and
230 * This will man elementary_quicklaunch does pre-initialization before the
231 * application needs to be run, saving the effort at the time the application
232 * is needed, thus speeding up the time it takes to appear.
234 * If you don't want to use the quicklaunch infrastructure (which is
235 * optional), you can execute the old fashioned way by just running the
236 * myapp binary loader than will load the myapp.so for you, or you can
237 * remove the split-file binary and put it into one binary as things always
238 * have been with the following configure.in/configure.ac and Makfile.am
241 * configure.in/configure.ac:
244 AC_INIT(myapp, 0.0.0, myname@mydomain.com)
246 AC_CONFIG_SRCDIR(configure.in)
248 AM_INIT_AUTOMAKE(1.6 dist-bzip2)
249 AM_CONFIG_HEADER(config.h)
258 PKG_CHECK_MODULES([ELEMENTARY], elementary)
266 AUTOMAKE_OPTIONS = 1.4 foreign
267 MAINTAINERCLEANFILES = Makefile.in
269 INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@
273 myapp_SOURCES = main.c
274 myapp_LDADD = @ELEMENTARY_LIBS@
278 * Notice that they are the same as before, just with libtool and library
279 * building sections removed. Both ways work for building elementary
280 * applications. It is up to you to decide what is best for you. If you just
281 * follow the template above, you can do it both ways and can decide at build
282 * time. The more advanced of you may suggest making it a configure option.
283 * That is perfectly valid, but has been left out here for simplicity, as our
284 * aim to have an Elementary (and EFL) tutorial, not an autoconf & automake
289 static Eina_Bool _elm_signal_exit(void *data,
293 char *_elm_appname = NULL;
294 const char *_elm_data_dir = NULL;
295 const char *_elm_lib_dir = NULL;
296 int _elm_log_dom = -1;
298 EAPI int ELM_EVENT_POLICY_CHANGED = 0;
300 static int _elm_init_count = 0;
301 static int _elm_sub_init_count = 0;
302 static int _elm_ql_init_count = 0;
303 static int _elm_policies[ELM_POLICY_LAST];
304 static Ecore_Event_Handler *_elm_exit_handler = NULL;
305 static Eina_Bool quicklaunch_on = 0;
308 _elm_signal_exit(void *data __UNUSED__,
309 int ev_type __UNUSED__,
313 return ECORE_CALLBACK_PASS_ON;
319 edje_scale_set(_elm_config->scale);
320 _elm_win_rescale(NULL, EINA_FALSE);
324 * @defgroup General General
328 * Inititalise Elementary
330 * @return The init counter value.
332 * This call is exported only for use by the ELM_MAIN() macro. There is no
333 * need to use this if you use this macro (which is highly advisable).
341 if (_elm_init_count > 1) return _elm_init_count;
342 elm_quicklaunch_init(argc, argv);
343 elm_quicklaunch_sub_init(argc, argv);
344 return _elm_init_count;
348 * Shut down Elementary
350 * @return The init counter value.
352 * This should be called at the end of your application just before it ceases
353 * to do any more processing. This will clean up any permanent resources your
354 * application may have allocated via Elementary that would otherwise persist
355 * on an exit without this call.
362 if (_elm_init_count > 0) return _elm_init_count;
363 elm_quicklaunch_sub_shutdown();
364 elm_quicklaunch_shutdown();
365 return _elm_init_count;
369 static int _elm_need_e_dbus = 0;
372 elm_need_e_dbus(void)
375 if (_elm_need_e_dbus++) return EINA_TRUE;
384 _elm_unneed_e_dbus(void)
387 if (--_elm_need_e_dbus) return;
389 _elm_need_e_dbus = 0;
395 static int _elm_need_efreet = 0;
398 elm_need_efreet(void)
401 if (_elm_need_efreet++) return EINA_TRUE;
409 list = efreet_icon_extra_list_get();
412 e_user_dir_concat_static(buf, "icons");
413 *list = eina_list_prepend(*list, (void *)eina_stringshare_add(buf));
414 e_prefix_data_concat_static(buf, "data/icons");
415 *list = eina_list_prepend(*list, (void *)eina_stringshare_add(buf));
426 _elm_unneed_efreet(void)
429 if (--_elm_need_efreet) return;
431 _elm_need_efreet = 0;
432 efreet_trash_shutdown();
433 efreet_mime_shutdown();
439 elm_quicklaunch_mode_set(Eina_Bool ql_on)
441 quicklaunch_on = ql_on;
445 elm_quicklaunch_mode_get(void)
447 return quicklaunch_on;
451 elm_quicklaunch_init(int argc,
454 char buf[PATH_MAX], *s;
456 _elm_ql_init_count++;
457 if (_elm_ql_init_count > 1) return _elm_ql_init_count;
459 _elm_log_dom = eina_log_domain_register("elementary", EINA_COLOR_LIGHTBLUE);
462 EINA_LOG_ERR("could not register elementary log domain.");
463 _elm_log_dom = EINA_LOG_DOMAIN_GLOBAL;
468 ecore_app_args_set(argc, (const char **)argv);
470 memset(_elm_policies, 0, sizeof(_elm_policies));
471 if (!ELM_EVENT_POLICY_CHANGED)
472 ELM_EVENT_POLICY_CHANGED = ecore_event_type_new();
476 _elm_exit_handler = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT, _elm_signal_exit, NULL);
478 if (argv) _elm_appname = strdup(ecore_file_file_get(argv[0]));
482 s = getenv("ELM_DATA_DIR");
483 _elm_data_dir = eina_stringshare_add(s);
487 s = getenv("ELM_PREFIX");
490 snprintf(buf, sizeof(buf), "%s/share/elementary", s);
491 _elm_data_dir = eina_stringshare_add(buf);
496 s = getenv("ELM_LIB_DIR");
497 _elm_lib_dir = eina_stringshare_add(s);
501 s = getenv("ELM_PREFIX");
504 snprintf(buf, sizeof(buf), "%s/lib", s);
505 _elm_lib_dir = eina_stringshare_add(buf);
509 if ((!_elm_data_dir) || (!_elm_lib_dir))
511 Dl_info elementary_dl;
512 // libelementary.so/../../share/elementary/
513 if (dladdr(elm_init, &elementary_dl))
517 dir = ecore_file_dir_get(elementary_dl.dli_fname);
522 if (ecore_file_is_dir(dir))
523 _elm_lib_dir = eina_stringshare_add(dir);
527 dir2 = ecore_file_dir_get(dir);
530 snprintf(buf, sizeof(buf), "%s/share/elementary", dir2);
531 if (ecore_file_is_dir(buf))
532 _elm_data_dir = eina_stringshare_add(buf);
542 _elm_data_dir = eina_stringshare_add(PACKAGE_DATA_DIR);
544 _elm_data_dir = eina_stringshare_add("/");
546 _elm_lib_dir = eina_stringshare_add(PACKAGE_LIB_DIR);
548 _elm_lib_dir = eina_stringshare_add("/");
551 return _elm_ql_init_count;
555 elm_quicklaunch_sub_init(int argc,
558 _elm_sub_init_count++;
559 if (_elm_sub_init_count > 1) return _elm_sub_init_count;
562 #ifdef SEMI_BROKEN_QUICKLAUNCH
563 return _elm_sub_init_count;
568 ecore_app_args_set(argc, (const char **)argv);
572 _elm_config_sub_init();
573 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
574 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
575 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
576 ENGINE_COMPARE(ELM_XRENDER_X11) ||
577 ENGINE_COMPARE(ELM_OPENGL_X11))
578 #undef ENGINE_COMPARE
580 #ifdef HAVE_ELEMENTARY_X
584 ecore_evas_init(); // FIXME: check errors
587 return _elm_sub_init_count;
591 elm_quicklaunch_sub_shutdown(void)
593 _elm_sub_init_count--;
594 if (_elm_sub_init_count > 0) return _elm_sub_init_count;
597 #ifdef SEMI_BROKEN_QUICKLAUNCH
598 return _elm_sub_init_count;
604 _elm_module_shutdown();
605 ecore_imf_shutdown();
606 ecore_evas_shutdown();
607 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
608 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
609 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
610 ENGINE_COMPARE(ELM_XRENDER_X11) ||
611 ENGINE_COMPARE(ELM_OPENGL_X11))
612 #undef ENGINE_COMPARE
614 #ifdef HAVE_ELEMENTARY_X
615 ecore_x_disconnect();
618 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
619 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
620 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
621 ENGINE_COMPARE(ELM_XRENDER_X11) ||
622 ENGINE_COMPARE(ELM_OPENGL_X11) ||
623 ENGINE_COMPARE(ELM_SOFTWARE_SDL) ||
624 ENGINE_COMPARE(ELM_SOFTWARE_16_SDL) ||
625 ENGINE_COMPARE(ELM_OPENGL_SDL) ||
626 ENGINE_COMPARE(ELM_SOFTWARE_WIN32) ||
627 ENGINE_COMPARE(ELM_SOFTWARE_16_WINCE))
628 #undef ENGINE_COMPARE
629 evas_cserve_disconnect();
633 return _elm_sub_init_count;
637 elm_quicklaunch_shutdown(void)
639 _elm_ql_init_count--;
640 if (_elm_ql_init_count > 0) return _elm_ql_init_count;
641 eina_stringshare_del(_elm_data_dir);
642 _elm_data_dir = NULL;
643 eina_stringshare_del(_elm_lib_dir);
649 _elm_config_shutdown();
651 ecore_event_handler_del(_elm_exit_handler);
652 _elm_exit_handler = NULL;
654 _elm_theme_shutdown();
655 _elm_unneed_efreet();
656 _elm_unneed_e_dbus();
657 _elm_unneed_ethumb();
658 ecore_file_shutdown();
662 if ((_elm_log_dom > -1) && (_elm_log_dom != EINA_LOG_DOMAIN_GLOBAL))
664 eina_log_domain_unregister(_elm_log_dom);
668 _elm_widget_type_clear();
671 return _elm_ql_init_count;
675 elm_quicklaunch_seed(void)
677 #ifndef SEMI_BROKEN_QUICKLAUNCH
680 Evas_Object *win, *bg, *bt;
682 win = elm_win_add(NULL, "seed", ELM_WIN_BASIC);
683 bg = elm_bg_add(win);
684 elm_win_resize_object_add(win, bg);
685 evas_object_show(bg);
686 bt = elm_button_add(win);
687 elm_button_label_set(bt, " abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789~-_=+\\|]}[{;:'\",<.>/?");
688 elm_win_resize_object_add(win, bt);
689 ecore_main_loop_iterate();
690 evas_object_del(win);
691 ecore_main_loop_iterate();
692 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
693 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
694 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
695 ENGINE_COMPARE(ELM_XRENDER_X11) ||
696 ENGINE_COMPARE(ELM_OPENGL_X11))
697 #undef ENGINE_COMPARE
699 # ifdef HAVE_ELEMENTARY_X
703 ecore_main_loop_iterate();
708 static void *qr_handle = NULL;
709 static int (*qr_main)(int argc,
713 elm_quicklaunch_prepare(int argc __UNUSED__,
717 char *exe = elm_quicklaunch_exe_path_get(argv[0]);
720 ERR("requested quicklaunch binary '%s' does not exist\n", argv[0]);
728 exe2 = malloc(strlen(exe) + 1 + 10);
730 p = strrchr(exe2, '/');
733 exename = alloca(strlen(p) + 1);
736 strcat(p, "../lib/");
739 if (!access(exe2, R_OK | X_OK))
747 qr_handle = dlopen(exe, RTLD_NOW | RTLD_GLOBAL);
750 fprintf(stderr, "dlerr: %s\n", dlerror());
751 WRN("dlopen('%s') failed: %s", exe, dlerror());
755 INF("dlopen('%s') = %p", exe, qr_handle);
756 qr_main = dlsym(qr_handle, "elm_main");
757 INF("dlsym(%p, 'elm_main') = %p", qr_handle, qr_main);
760 WRN("not quicklauncher capable: no elm_main in '%s'", exe);
779 extern char **environ;
784 for (i = 0, size = 0; environ[i]; i++)
785 size += strlen(environ[i]) + 1;
787 p = malloc((i + 1) * sizeof(char *));
792 for (i = 0; oldenv[i]; i++)
793 environ[i] = strdup(oldenv[i]);
800 elm_quicklaunch_fork(int argc,
803 void (postfork_func) (void *data),
813 // need to accept current environment from elementary_run
820 if (child > 0) return EINA_TRUE;
823 perror("could not fork");
828 perror("could not chdir");
829 args = alloca((argc + 1) * sizeof(char *));
830 for (i = 0; i < argc; i++) args[i] = argv[i];
832 WRN("%s not quicklaunch capable, fallback...", argv[0]);
833 execvp(argv[0], args);
834 ERR("failed to execute '%s': %s", argv[0], strerror(errno));
838 if (child > 0) return EINA_TRUE;
841 perror("could not fork");
844 if (postfork_func) postfork_func(postfork_data);
848 #ifdef SEMI_BROKEN_QUICKLAUNCH
849 ecore_app_args_set(argc, (const char **)argv);
852 _elm_config_sub_init();
853 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
854 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
855 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
856 ENGINE_COMPARE(ELM_XRENDER_X11) ||
857 ENGINE_COMPARE(ELM_OPENGL_X11))
858 #undef ENGINE_COMPARE
860 # ifdef HAVE_ELEMENTARY_X
864 ecore_evas_init(); // FIXME: check errors
872 perror("could not chdir");
873 // FIXME: this is very linux specific. it changes argv[0] of the process
874 // so ps etc. report what you'd expect. for other unixes and os's this
881 ecore_app_args_get(&real_argc, &real_argv);
882 lastarg = real_argv[real_argc - 1] + strlen(real_argv[real_argc - 1]);
883 for (p = real_argv[0]; p < lastarg; p++) *p = 0;
884 strcpy(real_argv[0], argv[0]);
886 ecore_app_args_set(argc, (const char **)argv);
887 ret = qr_main(argc, argv);
901 elm_quicklaunch_cleanup(void)
914 elm_quicklaunch_fallback(int argc,
918 elm_quicklaunch_init(argc, argv);
919 elm_quicklaunch_sub_init(argc, argv);
920 elm_quicklaunch_prepare(argc, argv);
921 ret = qr_main(argc, argv);
927 elm_quicklaunch_exe_path_get(const char *exe)
929 static char *path = NULL;
930 static Eina_List *pathlist = NULL;
934 if (exe[0] == '/') return strdup(exe);
935 if ((exe[0] == '.') && (exe[1] == '/')) return strdup(exe);
936 if ((exe[0] == '.') && (exe[1] == '.') && (exe[2] == '/')) return strdup(exe);
941 path = getenv("PATH");
942 buf2 = alloca(strlen(path) + 1);
947 if ((*p == ':') || (!*p))
952 strncpy(buf2, pp, len);
954 pathlist = eina_list_append(pathlist, eina_stringshare_add(buf2));
966 EINA_LIST_FOREACH(pathlist, l, pathitr)
968 snprintf(buf, sizeof(buf), "%s/%s", pathitr, exe);
969 if (!access(buf, R_OK | X_OK)) return strdup(buf);
977 * This call should be called just after all initialization is complete. This
978 * function will not return until elm_exit() is called. It will keep looping
979 * running the main event/processing loop for Elementary.
985 ecore_main_loop_begin();
991 * If this call is called, it will flag the main loop to cease processing and
992 * return back to its parent function.
998 ecore_main_loop_quit();
1002 * Set new policy value.
1004 * This will emit the ecore event ELM_EVENT_POLICY_CHANGED in the main
1005 * loop giving the event information Elm_Event_Policy_Changed with
1006 * policy identifier, new and old values.
1008 * @param policy policy identifier as in Elm_Policy.
1009 * @param value policy value, depends on identifiers, usually there is
1010 * an enumeration with the same prefix as the policy name, for
1011 * example: ELM_POLICY_QUIT and Elm_Policy_Quit
1012 * (ELM_POLICY_QUIT_NONE, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED).
1015 * @return @c EINA_TRUE on success or @c EINA_FALSE on error (right
1016 * now just invalid policy identifier, but in future policy
1017 * value might be enforced).
1020 elm_policy_set(unsigned int policy,
1023 Elm_Event_Policy_Changed *ev;
1025 if (policy >= ELM_POLICY_LAST)
1028 if (value == _elm_policies[policy])
1031 /* TODO: validade policy? */
1033 ev = malloc(sizeof(*ev));
1034 ev->policy = policy;
1035 ev->new_value = value;
1036 ev->old_value = _elm_policies[policy];
1038 _elm_policies[policy] = value;
1040 ecore_event_add(ELM_EVENT_POLICY_CHANGED, ev, NULL, NULL);
1046 * Gets the policy value set for given identifier.
1048 * @param policy policy identifier as in Elm_Policy.
1051 * @return policy value. Will be 0 if policy identifier is invalid.
1054 elm_policy_get(unsigned int policy)
1056 if (policy >= ELM_POLICY_LAST)
1058 return _elm_policies[policy];
1062 * @defgroup Scaling Selective Widget Scaling
1064 * Different widgets can be scaled independently. These functions allow you to
1065 * manipulate this scaling on a per-widget basis. The object and all its
1066 * children get their scaling factors multiplied by the scale factor set.
1067 * This is multiplicative, in that if a child also has a scale size set it is
1068 * in turn multiplied by its parent's scale size. 1.0 means “don't scale”,
1069 * 2.0 is double size, 0.5 is half etc.
1073 * Set the scaling factor
1075 * @param obj The object
1076 * @param scale Scale factor (from 0.0 up, with 1.0 == no scaling)
1080 elm_object_scale_set(Evas_Object *obj,
1083 EINA_SAFETY_ON_NULL_RETURN(obj);
1084 elm_widget_scale_set(obj, scale);
1088 * Get the scaling factor
1090 * @param obj The object
1091 * @return The scaling factor set by elm_object_scale_set()
1095 elm_object_scale_get(const Evas_Object *obj)
1097 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, 0.0);
1098 return elm_widget_scale_get(obj);
1102 * Get the global scaling factor
1104 * This gets the globally configured scaling factor that is applied to all
1107 * @return The scaling factor
1113 return _elm_config->scale;
1117 * Set the global scaling factor
1119 * This sets the globally configured scaling factor that is applied to all
1122 * @param scale The scaling factor to set
1126 elm_scale_set(double scale)
1128 if (_elm_config->scale == scale) return;
1129 _elm_config->scale = scale;
1134 * Set the global scaling factor for all applications on the display
1136 * This sets the globally configured scaling factor that is applied to all
1137 * objects for all applications.
1138 * @param scale The scaling factor to set
1142 elm_scale_all_set(double scale)
1144 #ifdef HAVE_ELEMENTARY_X
1145 static Ecore_X_Atom atom = 0;
1146 unsigned int scale_i = (unsigned int)(scale * 1000.0);
1148 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_SCALE");
1149 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1155 * @defgroup Styles Styles
1157 * Widgets can have different styles of look. These generic API's set
1158 * styles of widgets, if they support them (and if the theme(s) do).
1164 * This sets the name of the style
1165 * @param obj The object
1166 * @param style The style name to use
1170 elm_object_style_set(Evas_Object *obj,
1173 EINA_SAFETY_ON_NULL_RETURN(obj);
1174 elm_widget_style_set(obj, style);
1180 * This gets the style being used for that widget. Note that the string
1181 * pointer is only valid as longas the object is valid and the style doesn't
1184 * @param obj The object
1185 * @return The style name
1189 elm_object_style_get(const Evas_Object *obj)
1191 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
1192 return elm_widget_style_get(obj);
1196 * Set the disable state
1198 * This sets the disable state for the widget.
1200 * @param obj The object
1201 * @param disabled The state
1205 elm_object_disabled_set(Evas_Object *obj,
1208 EINA_SAFETY_ON_NULL_RETURN(obj);
1209 elm_widget_disabled_set(obj, disabled);
1213 * Get the disable state
1215 * This gets the disable state for the widget.
1217 * @param obj The object
1218 * @return True, if the widget is disabled
1222 elm_object_disabled_get(const Evas_Object *obj)
1224 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
1225 return elm_widget_disabled_get(obj);
1229 * @defgroup Config Elementary Config
1231 * Elementary configuration is formed by a set options bounded to a
1232 * given @ref Profile profile, like @ref Theme theme, @ref Fingers
1233 * "finger size", etc. These are functions with which one syncronizes
1234 * changes made to those values to the configuration storing files, de
1235 * facto. You most probably don't want to use the functions in this
1236 * group unlees you're writing an elementary configuration manager.
1240 * Save back Elementary's configuration, so that it will persist on
1243 * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
1246 * This function will take effect -- thus, do I/O -- immediately. Use
1247 * it when you want to apply all configuration changes at once. The
1248 * current configuration set will get saved onto the current profile
1249 * configuration file.
1253 elm_config_save(void)
1255 return _elm_config_save();
1259 * Reload Elementary's configuration, bounded to current selected
1262 * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
1265 * Useful when you want to force reloading of configuration values for
1266 * a profile. If one removes user custom configuration directories,
1267 * for example, it will force a reload with system values insted.
1271 elm_config_reload(void)
1273 _elm_config_reload();
1277 * @defgroup Profile Elementary Profile
1279 * Profiles are pre-set options that affect the whole look-and-feel of
1280 * Elementary-based applications. There are, for example, profiles
1281 * aimed at desktop computer applications and others aimed at mobile,
1282 * touchscreen-based ones. You most probably don't want to use the
1283 * functions in this group unlees you're writing an elementary
1284 * configuration manager.
1288 * Get Elementary's profile in use.
1290 * This gets the global profile that is applied to all Elementary
1293 * @return The profile's name
1297 elm_profile_current_get(void)
1299 return _elm_config_current_profile_get();
1303 * Get an Elementary's profile directory path in the filesystem. One
1304 * may want to fetch a system profile's dir or an user one (fetched
1307 * @param profile The profile's name
1308 * @param is_user Whether to lookup for an user profile (@c EINA_TRUE)
1309 * or a system one (@c EINA_FALSE)
1310 * @return The profile's directory path.
1313 * @note You must free it with elm_profile_dir_free().
1316 elm_profile_dir_get(const char *profile,
1319 return _elm_config_profile_dir_get(profile, is_user);
1323 * Free an Elementary's profile directory path, as returned by
1324 * elm_profile_dir_get().
1326 * @param p_dir The profile's path
1331 elm_profile_dir_free(const char *p_dir)
1333 free((void *)p_dir);
1337 * Get Elementary's list of available profiles.
1339 * @return The profiles list. List node data are the profile name
1343 * @note One must free this list, after usage, with the function
1344 * elm_profile_list_free().
1347 elm_profile_list_get(void)
1349 return _elm_config_profiles_list();
1353 * Free Elementary's list of available profiles.
1355 * @param The profiles list, as returned by elm_profile_list_get().
1360 elm_profile_list_free(Eina_List *l)
1364 EINA_LIST_FREE(l, dir)
1365 eina_stringshare_del(dir);
1369 * Set Elementary's profile.
1371 * This sets the global profile that is applied to Elementary
1372 * applications. Just the process the call comes from will be
1375 * @param profile The profile's name
1380 elm_profile_set(const char *profile)
1382 EINA_SAFETY_ON_NULL_RETURN(profile);
1383 _elm_config_profile_set(profile);
1387 * Set Elementary's profile.
1389 * This sets the global profile that is applied to all Elementary
1390 * applications. All running Elementary windows will be affected.
1392 * @param profile The profile's name
1397 elm_profile_all_set(const char *profile)
1399 #ifdef HAVE_ELEMENTARY_X
1400 static Ecore_X_Atom atom = 0;
1402 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_PROFILE");
1403 ecore_x_window_prop_string_set(ecore_x_window_root_first_get(),
1409 * @defgroup Engine Elementary Engine
1411 * These are functions setting and querying which rendering engine
1412 * Elementary will use for drawing its windows' pixels.
1416 * Get Elementary's rendering engine in use.
1418 * This gets the global rendering engine that is applied to all
1419 * Elementary applications.
1421 * @return The rendering engine's name
1424 * @note there's no need to free the returned string, here.
1427 elm_engine_current_get(void)
1429 return _elm_config->engine;
1433 * Set Elementary's rendering engine for use.
1435 * This gets sets global rendering engine that is applied to all
1436 * Elementary applications. Note that it will take effect only to
1437 * subsequent Elementary window creations.
1439 * @param The rendering engine's name
1442 * @note there's no need to free the returned string, here.
1445 elm_engine_set(const char *engine)
1447 EINA_SAFETY_ON_NULL_RETURN(engine);
1449 _elm_config_engine_set(engine);
1453 * @defgroup Fonts Elementary Fonts
1455 * These are functions dealing with font rendering, selection and the
1456 * like for Elementary applications. One might fetch which system
1457 * fonts are there to use and set custom fonts for individual classes
1458 * of UI items containing text (text classes).
1462 * Get Elementary's list of supported text classes.
1464 * @return The text classes list, with @c Elm_Text_Class blobs as data.
1467 * Release the list with elm_text_classes_list_free().
1469 EAPI const Eina_List *
1470 elm_text_classes_list_get(void)
1472 return _elm_config_text_classes_get();
1476 * Free Elementary's list of supported text classes.
1480 * @see elm_text_classes_list_get().
1483 elm_text_classes_list_free(const Eina_List *list)
1485 _elm_config_text_classes_free((Eina_List *)list);
1489 * Get Elementary's list of font overlays, set with
1490 * elm_font_overlay_set().
1492 * @return The font overlays list, with @c Elm_Font_Overlay blobs as
1497 * For each text class, one can set a <b>font overlay</b> for it,
1498 * overriding the default font properties for that class coming from
1499 * the theme in use. There is no need to free this list.
1501 * @see elm_font_overlay_set() and elm_font_overlay_unset().
1503 EAPI const Eina_List *
1504 elm_font_overlay_list_get(void)
1506 return _elm_config_font_overlays_list();
1510 * Set a font overlay for a given Elementary text class.
1512 * @param text_class Text class name
1513 * @param font Font name and style string
1514 * @param size Font size
1518 * @p font has to be in the format returned by
1519 * elm_font_fontconfig_name_get(). @see elm_font_overlay_list_get()
1520 * and @elm_font_overlay_unset().
1523 elm_font_overlay_set(const char *text_class,
1525 Evas_Font_Size size)
1527 _elm_config_font_overlay_set(text_class, font, size);
1531 * Unset a font overlay for a given Elementary text class.
1533 * @param text_class Text class name
1537 * This will bring back text elements belonging to text class @p
1538 * text_class back to their default font settings.
1541 elm_font_overlay_unset(const char *text_class)
1543 _elm_config_font_overlay_remove(text_class);
1547 * Apply the changes made with elm_font_overlay_set() and
1548 * elm_font_overlay_unset() on the current Elementary window.
1552 * This applies all font overlays set to all objects in the UI.
1555 elm_font_overlay_apply(void)
1557 _elm_config_font_overlay_apply();
1561 * Apply the changes made with elm_font_overlay_set() and
1562 * elm_font_overlay_unset() on all Elementary application windows.
1566 * This applies all font overlays set to all objects in the UI.
1569 elm_font_overlay_all_apply(void)
1571 #ifdef HAVE_ELEMENTARY_X
1572 static Ecore_X_Atom atom = 0;
1573 unsigned int dummy = (unsigned int)(1 * 1000.0);
1575 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FONT_OVERLAY");
1576 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(), atom, &dummy,
1582 * Translate a font (family) name string in fontconfig's font names
1583 * syntax into an @c Elm_Font_Properties struct.
1585 * @param font The font name and styles string
1586 * @return the font properties struct
1590 * @note The reverse translation can be achived with
1591 * elm_font_fontconfig_name_get(), for one style only (single font
1592 * instance, not family).
1594 EAPI Elm_Font_Properties *
1595 elm_font_properties_get(const char *font)
1597 EINA_SAFETY_ON_NULL_RETURN_VAL(font, NULL);
1598 return _elm_font_properties_get(NULL, font);
1602 * Free font properties return by elm_font_properties_get().
1604 * @param efp the font properties struct
1609 elm_font_properties_free(Elm_Font_Properties *efp)
1613 EINA_SAFETY_ON_NULL_RETURN(efp);
1614 EINA_LIST_FREE(efp->styles, str)
1615 if (str) eina_stringshare_del(str);
1616 if (efp->name) eina_stringshare_del(efp->name);
1621 * Translate a font name, bound to a style, into fontconfig's font names
1624 * @param name The font (family) name
1625 * @param style The given style (may be @c NULL)
1627 * @return the font name and style string
1631 * @note The reverse translation can be achived with
1632 * elm_font_properties_get(), for one style only (single font
1633 * instance, not family).
1636 elm_font_fontconfig_name_get(const char *name,
1641 EINA_SAFETY_ON_NULL_RETURN_VAL(name, NULL);
1642 if (!style || style[0] == 0) return eina_stringshare_add(name);
1643 snprintf(buf, 256, "%s" ELM_FONT_TOKEN_STYLE "%s", name, style);
1644 return eina_stringshare_add(buf);
1648 * Free the font string return by elm_font_fontconfig_name_get().
1650 * @param efp the font properties struct
1655 elm_font_fontconfig_name_free(const char *name)
1657 eina_stringshare_del(name);
1661 * Create a font hash table of available system fonts.
1663 * One must call it with @p list being the return value of
1664 * evas_font_available_list(). The hash will be indexed by font
1665 * (family) names, being its values @c Elm_Font_Properties blobs.
1667 * @param list The list of available system fonts, as returned by
1668 * evas_font_available_list().
1669 * @return the font hash.
1673 * @note The user is supposed to get it populated at least with 3
1674 * default font families (Sans, Serif, Monospace), which should be
1675 * present on most systems.
1678 elm_font_available_hash_add(Eina_List *list)
1680 Eina_Hash *font_hash;
1686 /* populate with default font families */
1687 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Regular");
1688 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Bold");
1689 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Oblique");
1690 font_hash = _elm_font_available_hash_add(font_hash,
1691 "Sans:style=Bold Oblique");
1693 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Regular");
1694 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Bold");
1695 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Oblique");
1696 font_hash = _elm_font_available_hash_add(font_hash,
1697 "Serif:style=Bold Oblique");
1699 font_hash = _elm_font_available_hash_add(font_hash,
1700 "Monospace:style=Regular");
1701 font_hash = _elm_font_available_hash_add(font_hash,
1702 "Monospace:style=Bold");
1703 font_hash = _elm_font_available_hash_add(font_hash,
1704 "Monospace:style=Oblique");
1705 font_hash = _elm_font_available_hash_add(font_hash,
1706 "Monospace:style=Bold Oblique");
1708 EINA_LIST_FOREACH(list, l, key)
1709 font_hash = _elm_font_available_hash_add(font_hash, key);
1715 * Free the hash return by elm_font_available_hash_add().
1717 * @param hash the hash to be freed.
1722 elm_font_available_hash_del(Eina_Hash *hash)
1724 _elm_font_available_hash_del(hash);
1728 * @defgroup Fingers Fingers
1730 * Elementary is designed to be finger-friendly for touchscreens, and so in
1731 * addition to scaling for display resolution, it can also scale based on
1732 * finger "resolution" (or size).
1736 * Get the configured finger size
1738 * This gets the globally configured finger size in pixels
1740 * @return The finger size
1744 elm_finger_size_get(void)
1746 return _elm_config->finger_size;
1750 * Set the configured finger size
1752 * This sets the globally configured finger size in pixels
1754 * @param size The finger size
1758 elm_finger_size_set(Evas_Coord size)
1760 if (_elm_config->finger_size == size) return;
1761 _elm_config->finger_size = size;
1766 * Set the configured finger size for all applications on the display
1768 * This sets the globally configured finger size in pixels for all applications
1771 * @param size The finger size
1775 elm_finger_size_all_set(Evas_Coord size)
1777 #ifdef HAVE_ELEMENTARY_X
1778 static Ecore_X_Atom atom = 0;
1779 unsigned int size_i = (unsigned int)size;
1781 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FINGER_SIZE");
1782 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1788 * Adjust size of an element for finger usage
1790 * This takes width and height sizes (in pixels) as input and a size multiple
1791 * (which is how many fingers you want to place within the area), and adjusts
1792 * the size tobe large enough to accommodate finger. On return the w and h
1793 * sizes poiner do by these parameters will be modified.
1795 * @param times_w How many fingers should fit horizontally
1796 * @param w Pointer to the width size to adjust
1797 * @param times_h How many fingers should fit vertically
1798 * @param h Pointer to the height size to adjust
1802 elm_coords_finger_size_adjust(int times_w,
1807 if ((w) && (*w < (_elm_config->finger_size * times_w)))
1808 *w = _elm_config->finger_size * times_w;
1809 if ((h) && (*h < (_elm_config->finger_size * times_h)))
1810 *h = _elm_config->finger_size * times_h;
1814 * @defgroup Caches Caches
1816 * These are functions which let one fine-tune some cache values for
1817 * Elementary applications, thus allowing for performance adjustments.
1821 * Flush all caches & dump all data that can be to lean down to use
1832 edje_file_cache_flush();
1833 edje_collection_cache_flush();
1835 EINA_LIST_FOREACH(_elm_win_list, l, obj)
1837 Evas *e = evas_object_evas_get(obj);
1838 evas_image_cache_flush(e);
1839 evas_font_cache_flush(e);
1840 evas_render_dump(e);
1845 * Get the configured cache flush interval time
1847 * This gets the globally configured cache flush interval time, in
1850 * @return The cache flush interval time
1853 * @see elm_all_flush()
1856 elm_cache_flush_interval_get(void)
1858 return _elm_config->cache_flush_poll_interval;
1862 * Set the configured cache flush interval time
1864 * This sets the globally configured cache flush interval time, in ticks
1866 * @param size The cache flush interval time
1869 * @see elm_all_flush()
1872 elm_cache_flush_interval_set(int size)
1874 if (_elm_config->cache_flush_poll_interval == size) return;
1875 _elm_config->cache_flush_poll_interval = size;
1881 * Set the configured cache flush interval time for all applications on the
1884 * This sets the globally configured cache flush interval time -- in ticks
1885 * -- for all applications on the display.
1887 * @param size The cache flush interval time
1891 elm_cache_flush_interval_all_set(int size)
1893 #ifdef HAVE_ELEMENTARY_X
1894 static Ecore_X_Atom atom = 0;
1895 unsigned int size_i = (unsigned int)size;
1897 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_CACHE_FLUSH_INTERVAL");
1898 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1904 * Get the configured cache flush enabled state
1906 * This gets the globally configured cache flush state - if it is enabled
1907 * or not. When cache flushing is enabled, elementary will regularly
1908 * (see elm_cache_flush_interval_get() ) flush caches and dump data out of
1909 * memory and allow usage to re-seed caches and data in memory where it
1910 * can do so. An idle application will thus minimise its memory usage as
1911 * data will be freed from memory and not be re-loaded as it is idle and
1912 * not rendering or doing anything graphically right now.
1914 * @return The cache flush state
1917 * @see elm_all_flush()
1920 elm_cache_flush_enmabled_get(void)
1922 return _elm_config->cache_flush_enable;
1926 * Set the configured cache flush enabled state
1928 * This sets the globally configured cache flush enabled state
1930 * @param size The cache flush enabled state
1933 * @see elm_all_flush()
1936 elm_cache_flush_enabled_set(Eina_Bool enabled)
1938 enabled = !!enabled;
1939 if (_elm_config->cache_flush_enable == enabled) return;
1940 _elm_config->cache_flush_enable = enabled;
1946 * Set the configured cache flush enabled state for all applications on the
1949 * This sets the globally configured cache flush enabled state for all
1950 * applications on the display.
1952 * @param size The cache flush enabled state
1956 elm_cache_flush_enabled_all_set(Eina_Bool enabled)
1958 #ifdef HAVE_ELEMENTARY_X
1959 static Ecore_X_Atom atom = 0;
1960 unsigned int enabled_i = (unsigned int)enabled;
1962 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_CACHE_FLUSH_ENABLE");
1963 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1964 atom, &enabled_i, 1);
1969 * Get the configured font cache size
1971 * This gets the globally configured font cache size, in bytes
1973 * @return The font cache size
1977 elm_font_cache_get(void)
1979 return _elm_config->font_cache;
1983 * Set the configured font cache size
1985 * This sets the globally configured font cache size, in bytes
1987 * @param size The font cache size
1991 elm_font_cache_set(int size)
1993 if (_elm_config->font_cache == size) return;
1994 _elm_config->font_cache = size;
2000 * Set the configured font cache size for all applications on the
2003 * This sets the globally configured font cache size -- in bytes
2004 * -- for all applications on the display.
2006 * @param size The font cache size
2010 elm_font_cache_all_set(int size)
2012 #ifdef HAVE_ELEMENTARY_X
2013 static Ecore_X_Atom atom = 0;
2014 unsigned int size_i = (unsigned int)size;
2016 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FONT_CACHE");
2017 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2023 * Get the configured image cache size
2025 * This gets the globally configured image cache size, in bytes
2027 * @return The image cache size
2031 elm_image_cache_get(void)
2033 return _elm_config->image_cache;
2037 * Set the configured image cache size
2039 * This sets the globally configured image cache size, in bytes
2041 * @param size The image cache size
2045 elm_image_cache_set(int size)
2047 if (_elm_config->image_cache == size) return;
2048 _elm_config->image_cache = size;
2054 * Set the configured image cache size for all applications on the
2057 * This sets the globally configured image cache size -- in bytes
2058 * -- for all applications on the display.
2060 * @param size The image cache size
2064 elm_image_cache_all_set(int size)
2066 #ifdef HAVE_ELEMENTARY_X
2067 static Ecore_X_Atom atom = 0;
2068 unsigned int size_i = (unsigned int)size;
2070 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_IMAGE_CACHE");
2071 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2077 * Get the configured edje file cache size.
2079 * This gets the globally configured edje file cache size, in number
2082 * @return The edje file cache size
2086 elm_edje_file_cache_get(void)
2088 return _elm_config->edje_cache;
2092 * Set the configured edje file cache size
2094 * This sets the globally configured edje file cache size, in number
2097 * @param size The edje file cache size
2101 elm_edje_file_cache_set(int size)
2103 if (_elm_config->edje_cache == size) return;
2104 _elm_config->edje_cache = size;
2110 * Set the configured edje file cache size for all applications on the
2113 * This sets the globally configured edje file cache size -- in number
2114 * of files -- for all applications on the display.
2116 * @param size The edje file cache size
2120 elm_edje_file_cache_all_set(int size)
2122 #ifdef HAVE_ELEMENTARY_X
2123 static Ecore_X_Atom atom = 0;
2124 unsigned int size_i = (unsigned int)size;
2126 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_EDJE_FILE_CACHE");
2127 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2133 * Get the configured edje collections (groups) cache size.
2135 * This gets the globally configured edje collections cache size, in
2136 * number of collections.
2138 * @return The edje collections cache size
2142 elm_edje_collection_cache_get(void)
2144 return _elm_config->edje_collection_cache;
2148 * Set the configured edje collections (groups) cache size
2150 * This sets the globally configured edje collections cache size, in
2151 * number of collections.
2153 * @param size The edje collections cache size
2157 elm_edje_collection_cache_set(int size)
2159 if (_elm_config->edje_collection_cache == size) return;
2160 _elm_config->edje_collection_cache = size;
2166 * Set the configured edje collections (groups) cache size for all
2167 * applications on the display
2169 * This sets the globally configured edje collections cache size -- in
2170 * number of collections -- for all applications on the display.
2172 * @param size The edje collections cache size
2176 elm_edje_collection_cache_all_set(int size)
2178 #ifdef HAVE_ELEMENTARY_X
2179 static Ecore_X_Atom atom = 0;
2180 unsigned int size_i = (unsigned int)size;
2182 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_EDJE_COLLECTION_CACHE");
2183 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2189 * @defgroup Focus Focus
2191 * Objects have focus. This is what determines where the keyboard input goes to
2192 * within the application window.
2196 * Get the focus of the object
2198 * This gets the focused property of the object.
2200 * @param obj The object
2201 * @return 1 if the object is focused, 0 if not.
2205 elm_object_focus_get(const Evas_Object *obj)
2207 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
2208 return elm_widget_focus_get(obj);
2212 * Set the focus to the object
2214 * This sets the focus target for keyboard input to be the object indicated.
2216 * @param obj The object
2220 elm_object_focus(Evas_Object *obj)
2222 EINA_SAFETY_ON_NULL_RETURN(obj);
2223 if (elm_widget_focus_get(obj))
2226 elm_widget_focus_cycle(obj, ELM_FOCUS_NEXT);
2230 * Remove the focus from the object
2232 * This removes the focus target for keyboard input from be the object
2235 * @param obj The object
2239 elm_object_unfocus(Evas_Object *obj)
2241 EINA_SAFETY_ON_NULL_RETURN(obj);
2242 if (!elm_widget_can_focus_get(obj)) return;
2243 elm_widget_focused_object_clear(obj);
2247 * Set the ability for the object to focus
2249 * This sets the ability for the object to be able to get keyboard focus or
2250 * not. By default all objects are able to be focused.
2252 * @param obj The object
2253 * @param enable 1 if the object can be focused, 0 if not
2257 elm_object_focus_allow_set(Evas_Object *obj,
2260 EINA_SAFETY_ON_NULL_RETURN(obj);
2261 elm_widget_can_focus_set(obj, enable);
2265 * Get the ability for the object to focus
2267 * This gets the ability for the object to be able to get keyboard focus or
2268 * not. By default all objects are able to be focused.
2270 * @param obj The object
2271 * @return 1 if the object is allowed to be focused, 0 if not.
2275 elm_object_focus_allow_get(const Evas_Object *obj)
2277 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
2278 return (elm_widget_can_focus_get(obj)) || (elm_widget_child_can_focus_get(obj));
2282 * Set custom focus chain.
2284 * This function i set one new and overwrite any previous custom focus chain
2285 * with the list of objects. The previous list will be deleted and this list
2286 * will be managed. After setted, don't modity it.
2288 * @note On focus cycle, only will be evaluated children of this container.
2290 * @param obj The container object
2291 * @param objs Chain of objects to pass focus
2295 elm_object_focus_custom_chain_set(Evas_Object *obj,
2298 EINA_SAFETY_ON_NULL_RETURN(obj);
2299 elm_widget_focus_custom_chain_set(obj, objs);
2303 * Unset custom focus chain
2305 * @param obj The container object
2309 elm_object_focus_custom_chain_unset(Evas_Object *obj)
2311 EINA_SAFETY_ON_NULL_RETURN(obj);
2312 elm_widget_focus_custom_chain_unset(obj);
2316 * Get custom focus chain
2318 * @param obj The container object
2321 EAPI const Eina_List *
2322 elm_object_focus_custom_chain_get(const Evas_Object *obj)
2324 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
2325 return elm_widget_focus_custom_chain_get(obj);
2329 * Append object to custom focus chain.
2331 * @note If relative_child equal to NULL or not in custom chain, the object
2332 * will be added in end.
2334 * @note On focus cycle, only will be evaluated children of this container.
2336 * @param obj The container object
2337 * @param child The child to be added in custom chain
2338 * @param relative_child The relative object to position the child
2342 elm_object_focus_custom_chain_append(Evas_Object *obj,
2344 Evas_Object *relative_child)
2346 EINA_SAFETY_ON_NULL_RETURN(obj);
2347 EINA_SAFETY_ON_NULL_RETURN(child);
2348 elm_widget_focus_custom_chain_append(obj, child, relative_child);
2352 * Prepend object to custom focus chain.
2354 * @note If relative_child equal to NULL or not in custom chain, the object
2355 * will be added in begin.
2357 * @note On focus cycle, only will be evaluated children of this container.
2359 * @param obj The container object
2360 * @param child The child to be added in custom chain
2361 * @param relative_child The relative object to position the child
2365 elm_object_focus_custom_chain_prepend(Evas_Object *obj,
2367 Evas_Object *relative_child)
2369 EINA_SAFETY_ON_NULL_RETURN(obj);
2370 EINA_SAFETY_ON_NULL_RETURN(child);
2371 elm_widget_focus_custom_chain_prepend(obj, child, relative_child);
2375 * Give focus to next object in object tree.
2377 * Give focus to next object in focus chain of one object sub-tree.
2378 * If the last object of chain already have focus, the focus will go to the
2379 * first object of chain.
2381 * @param obj The object root of sub-tree
2382 * @param dir Direction to cycle the focus
2387 elm_object_focus_cycle(Evas_Object *obj,
2388 Elm_Focus_Direction dir)
2390 EINA_SAFETY_ON_NULL_RETURN(obj);
2391 elm_widget_focus_cycle(obj, dir);
2395 * Give focus to near object in one direction.
2397 * Give focus to near object in direction of one object.
2398 * If none focusable object in given direction, the focus will not change.
2400 * @param obj The reference object
2401 * @param x Horizontal component of direction to focus
2402 * @param y Vertical component of direction to focus
2407 elm_object_focus_direction_go(Evas_Object *obj,
2411 EINA_SAFETY_ON_NULL_RETURN(obj);
2412 elm_widget_focus_direction_go(obj, x, y);
2416 * Get the enable status of the focus highlight
2418 * This gets whether the highlight on focused objects is enabled or not
2422 elm_focus_highlight_enabled_get(void)
2424 return _elm_config->focus_highlight_enable;
2428 * Set the enable status of the focus highlight
2430 * Set whether to show or not the highlight on focused objects
2431 * @param enable Enable highlight if EINA_TRUE, disable otherwise
2435 elm_focus_highlight_enabled_set(Eina_Bool enable)
2437 _elm_config->focus_highlight_enable = !!enable;
2441 * Get the enable status of the highlight animation
2443 * Get whether the focus highlight, if enabled, will animate its switch from
2444 * one object to the next
2448 elm_focus_highlight_animate_get(void)
2450 return _elm_config->focus_highlight_animate;
2454 * Set the enable status of the highlight animation
2456 * Set whether the focus highlight, if enabled, will animate its switch from
2457 * one object to the next
2458 * @param animate Enable animation if EINA_TRUE, disable otherwise
2462 elm_focus_highlight_animate_set(Eina_Bool animate)
2464 _elm_config->focus_highlight_animate = !!animate;
2468 * @defgroup Scrolling Scrolling
2470 * These are functions setting how scrollable views in Elementary
2471 * widgets should behave on user interaction.
2475 * Get whether scrollers should bounce when they reach their
2476 * viewport's edge during a scroll.
2478 * @return the thumb scroll bouncing state
2480 * This is the default behavior for touch screens, in general.
2481 * @ingroup Scrolling
2484 elm_scroll_bounce_enabled_get(void)
2486 return _elm_config->thumbscroll_bounce_enable;
2490 * Set whether scrollers should bounce when they reach their
2491 * viewport's edge during a scroll.
2493 * @param enabled the thumb scroll bouncing state
2495 * @see elm_thumbscroll_bounce_enabled_get()
2496 * @ingroup Scrolling
2499 elm_scroll_bounce_enabled_set(Eina_Bool enabled)
2501 _elm_config->thumbscroll_bounce_enable = enabled;
2505 * Set whether scrollers should bounce when they reach their
2506 * viewport's edge during a scroll, for all Elementary application
2509 * @param enabled the thumb scroll bouncing state
2511 * @see elm_thumbscroll_bounce_enabled_get()
2512 * @ingroup Scrolling
2515 elm_scroll_bounce_enabled_all_set(Eina_Bool enabled)
2517 #ifdef HAVE_ELEMENTARY_X
2518 static Ecore_X_Atom atom = 0;
2519 unsigned int bounce_enable_i = (unsigned int)enabled;
2522 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BOUNCE_ENABLE");
2523 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2524 atom, &bounce_enable_i, 1);
2529 * Get the amount of inertia a scroller will impose at bounce
2532 * @return the thumb scroll bounce friction
2534 * @ingroup Scrolling
2537 elm_scroll_bounce_friction_get(void)
2539 return _elm_config->thumbscroll_bounce_friction;
2543 * Set the amount of inertia a scroller will impose at bounce
2546 * @param friction the thumb scroll bounce friction
2548 * @see elm_thumbscroll_bounce_friction_get()
2549 * @ingroup Scrolling
2552 elm_scroll_bounce_friction_set(double friction)
2554 _elm_config->thumbscroll_bounce_friction = friction;
2558 * Set the amount of inertia a scroller will impose at bounce
2559 * animations, for all Elementary application windows.
2561 * @param friction the thumb scroll bounce friction
2563 * @see elm_thumbscroll_bounce_friction_get()
2564 * @ingroup Scrolling
2567 elm_scroll_bounce_friction_all_set(double friction)
2569 #ifdef HAVE_ELEMENTARY_X
2570 static Ecore_X_Atom atom = 0;
2571 unsigned int bounce_friction_i = (unsigned int)(friction * 1000.0);
2574 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BOUNCE_FRICTION");
2575 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2576 atom, &bounce_friction_i, 1);
2581 * Get the amount of inertia a <b>paged</b> scroller will impose at
2582 * page fitting animations.
2584 * @return the page scroll friction
2586 * @ingroup Scrolling
2589 elm_scroll_page_scroll_friction_get(void)
2591 return _elm_config->page_scroll_friction;
2595 * Set the amount of inertia a <b>paged</b> scroller will impose at
2596 * page fitting animations.
2598 * @param friction the page scroll friction
2600 * @see elm_thumbscroll_page_scroll_friction_get()
2601 * @ingroup Scrolling
2604 elm_scroll_page_scroll_friction_set(double friction)
2606 _elm_config->page_scroll_friction = friction;
2610 * Set the amount of inertia a <b>paged</b> scroller will impose at
2611 * page fitting animations, for all Elementary application windows.
2613 * @param friction the page scroll friction
2615 * @see elm_thumbscroll_page_scroll_friction_get()
2616 * @ingroup Scrolling
2619 elm_scroll_page_scroll_friction_all_set(double friction)
2621 #ifdef HAVE_ELEMENTARY_X
2622 static Ecore_X_Atom atom = 0;
2623 unsigned int page_scroll_friction_i = (unsigned int)(friction * 1000.0);
2626 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_PAGE_SCROLL_FRICTION");
2627 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2628 atom, &page_scroll_friction_i, 1);
2633 * Get the amount of inertia a scroller will impose at region bring
2636 * @return the bring in scroll friction
2638 * @ingroup Scrolling
2641 elm_scroll_bring_in_scroll_friction_get(void)
2643 return _elm_config->bring_in_scroll_friction;
2647 * Set the amount of inertia a scroller will impose at region bring
2650 * @param friction the bring in scroll friction
2652 * @see elm_thumbscroll_bring_in_scroll_friction_get()
2653 * @ingroup Scrolling
2656 elm_scroll_bring_in_scroll_friction_set(double friction)
2658 _elm_config->bring_in_scroll_friction = friction;
2662 * Set the amount of inertia a scroller will impose at region bring
2663 * animations, for all Elementary application windows.
2665 * @param friction the bring in scroll friction
2667 * @see elm_thumbscroll_bring_in_scroll_friction_get()
2668 * @ingroup Scrolling
2671 elm_scroll_bring_in_scroll_friction_all_set(double friction)
2673 #ifdef HAVE_ELEMENTARY_X
2674 static Ecore_X_Atom atom = 0;
2675 unsigned int bring_in_scroll_friction_i = (unsigned int)(friction * 1000.0);
2679 ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BRING_IN_SCROLL_FRICTION");
2680 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2681 atom, &bring_in_scroll_friction_i, 1);
2686 * Get the amount of inertia scrollers will impose at animations
2687 * triggered by Elementary widgets' zooming API.
2689 * @return the zoom friction
2691 * @ingroup Scrolling
2694 elm_scroll_zoom_friction_get(void)
2696 return _elm_config->zoom_friction;
2700 * Set the amount of inertia scrollers will impose at animations
2701 * triggered by Elementary widgets' zooming API.
2703 * @param friction the zoom friction
2705 * @see elm_thumbscroll_zoom_friction_get()
2706 * @ingroup Scrolling
2709 elm_scroll_zoom_friction_set(double friction)
2711 _elm_config->zoom_friction = friction;
2715 * Set the amount of inertia scrollers will impose at animations
2716 * triggered by Elementary widgets' zooming API, for all Elementary
2717 * application windows.
2719 * @param friction the zoom friction
2721 * @see elm_thumbscroll_zoom_friction_get()
2722 * @ingroup Scrolling
2725 elm_scroll_zoom_friction_all_set(double friction)
2727 #ifdef HAVE_ELEMENTARY_X
2728 static Ecore_X_Atom atom = 0;
2729 unsigned int zoom_friction_i = (unsigned int)(friction * 1000.0);
2732 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_ZOOM_FRICTION");
2733 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2734 atom, &zoom_friction_i, 1);
2739 * Get whether scrollers should be draggable from any point in their
2742 * @return the thumb scroll state
2744 * @note This is the default behavior for touch screens, in general.
2745 * @note All other functions namespaced with "thumbscroll" will only
2746 * have effect if this mode is enabled.
2748 * @ingroup Scrolling
2751 elm_scroll_thumbscroll_enabled_get(void)
2753 return _elm_config->thumbscroll_enable;
2757 * Set whether scrollers should be draggable from any point in their
2760 * @param enabled the thumb scroll state
2762 * @see elm_thumbscroll_enabled_get()
2763 * @ingroup Scrolling
2766 elm_scroll_thumbscroll_enabled_set(Eina_Bool enabled)
2768 _elm_config->thumbscroll_enable = enabled;
2772 * Set whether scrollers should be draggable from any point in their
2773 * views, for all Elementary application windows.
2775 * @param enabled the thumb scroll state
2777 * @see elm_thumbscroll_enabled_get()
2778 * @ingroup Scrolling
2781 elm_scroll_thumbscroll_enabled_all_set(Eina_Bool enabled)
2783 #ifdef HAVE_ELEMENTARY_X
2784 static Ecore_X_Atom atom = 0;
2785 unsigned int ts_enable_i = (unsigned int)enabled;
2787 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_ENABLE");
2788 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2789 atom, &ts_enable_i, 1);
2794 * Get the number of pixels one should travel while dragging a
2795 * scroller's view to actually trigger scrolling.
2797 * @return the thumb scroll threshould
2799 * One would use higher values for touch screens, in general, because
2800 * of their inherent imprecision.
2801 * @ingroup Scrolling
2804 elm_scroll_thumbscroll_threshold_get(void)
2806 return _elm_config->thumbscroll_threshold;
2810 * Set the number of pixels one should travel while dragging a
2811 * scroller's view to actually trigger scrolling.
2813 * @param threshold the thumb scroll threshould
2815 * @see elm_thumbscroll_threshould_get()
2816 * @ingroup Scrolling
2819 elm_scroll_thumbscroll_threshold_set(unsigned int threshold)
2821 _elm_config->thumbscroll_threshold = threshold;
2825 * Set the number of pixels one should travel while dragging a
2826 * scroller's view to actually trigger scrolling, for all Elementary
2827 * application windows.
2829 * @param threshold the thumb scroll threshould
2831 * @see elm_thumbscroll_threshould_get()
2832 * @ingroup Scrolling
2835 elm_scroll_thumbscroll_threshold_all_set(unsigned int threshold)
2837 #ifdef HAVE_ELEMENTARY_X
2838 static Ecore_X_Atom atom = 0;
2839 unsigned int ts_threshold_i = (unsigned int)threshold;
2841 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_THRESHOLD");
2842 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2843 atom, &ts_threshold_i, 1);
2848 * Get the minimum speed of mouse cursor movement which will trigger
2849 * list self scrolling animation after a mouse up event
2852 * @return the thumb scroll momentum threshould
2854 * @ingroup Scrolling
2857 elm_scroll_thumbscroll_momentum_threshold_get(void)
2859 return _elm_config->thumbscroll_momentum_threshold;
2863 * Set the minimum speed of mouse cursor movement which will trigger
2864 * list self scrolling animation after a mouse up event
2867 * @param threshold the thumb scroll momentum threshould
2869 * @see elm_thumbscroll_momentum_threshould_get()
2870 * @ingroup Scrolling
2873 elm_scroll_thumbscroll_momentum_threshold_set(double threshold)
2875 _elm_config->thumbscroll_momentum_threshold = threshold;
2879 * Set the minimum speed of mouse cursor movement which will trigger
2880 * list self scrolling animation after a mouse up event
2881 * (pixels/second), for all Elementary application windows.
2883 * @param threshold the thumb scroll momentum threshould
2885 * @see elm_thumbscroll_momentum_threshould_get()
2886 * @ingroup Scrolling
2889 elm_scroll_thumbscroll_momentum_threshold_all_set(double threshold)
2891 #ifdef HAVE_ELEMENTARY_X
2892 static Ecore_X_Atom atom = 0;
2893 unsigned int ts_momentum_threshold_i = (unsigned int)(threshold * 1000.0);
2896 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_MOMENTUM_THRESHOLD");
2897 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2898 atom, &ts_momentum_threshold_i, 1);
2903 * Get the amount of inertia a scroller will impose at self scrolling
2906 * @return the thumb scroll friction
2908 * @ingroup Scrolling
2911 elm_scroll_thumbscroll_friction_get(void)
2913 return _elm_config->thumbscroll_friction;
2917 * Set the amount of inertia a scroller will impose at self scrolling
2920 * @param friction the thumb scroll friction
2922 * @see elm_thumbscroll_friction_get()
2923 * @ingroup Scrolling
2926 elm_scroll_thumbscroll_friction_set(double friction)
2928 _elm_config->thumbscroll_friction = friction;
2932 * Set the amount of inertia a scroller will impose at self scrolling
2933 * animations, for all Elementary application windows.
2935 * @param friction the thumb scroll friction
2937 * @see elm_thumbscroll_friction_get()
2938 * @ingroup Scrolling
2941 elm_scroll_thumbscroll_friction_all_set(double friction)
2943 #ifdef HAVE_ELEMENTARY_X
2944 static Ecore_X_Atom atom = 0;
2945 unsigned int ts_friction_i = (unsigned int)(friction * 1000.0);
2947 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_FRICTION");
2948 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2949 atom, &ts_friction_i, 1);
2954 * Get the amount of lag between your actual mouse cursor dragging
2955 * movement and a scroller's view movement itself, while pushing it
2956 * into bounce state manually.
2958 * @return the thumb scroll border friction
2960 * @ingroup Scrolling
2963 elm_scroll_thumbscroll_border_friction_get(void)
2965 return _elm_config->thumbscroll_border_friction;
2969 * Set the amount of lag between your actual mouse cursor dragging
2970 * movement and a scroller's view movement itself, while pushing it
2971 * into bounce state manually.
2973 * @param friction the thumb scroll border friction. @c 0.0 for
2974 * perfect synchrony between two movements, @c 1.0 for maximum
2977 * @see elm_thumbscroll_border_friction_get()
2978 * @note parameter value will get bound to 0.0 - 1.0 interval, always
2980 * @ingroup Scrolling
2983 elm_scroll_thumbscroll_border_friction_set(double friction)
2991 _elm_config->thumbscroll_friction = friction;
2995 * Set the amount of lag between your actual mouse cursor dragging
2996 * movement and a scroller's view movement itself, while pushing it
2997 * into bounce state manually, for all Elementary application windows.
2999 * @param friction the thumb scroll border friction. @c 0.0 for
3000 * perfect synchrony between two movements, @c 1.0 for maximum
3003 * @see elm_thumbscroll_border_friction_get()
3004 * @note parameter value will get bound to 0.0 - 1.0 interval, always
3006 * @ingroup Scrolling
3009 elm_scroll_thumbscroll_border_friction_all_set(double friction)
3017 #ifdef HAVE_ELEMENTARY_X
3018 static Ecore_X_Atom atom = 0;
3019 unsigned int border_friction_i = (unsigned int)(friction * 1000.0);
3022 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BORDER_FRICTION");
3023 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
3024 atom, &border_friction_i, 1);
3029 * @defgroup Scrollhints Scrollhints
3031 * Objects when inside a scroller can scroll, but this may not always be
3032 * desirable in certain situations. This allows an object to hint to itself
3033 * and parents to "not scroll" in one of 2 ways.
3035 * 1. To hold on scrolling. This means just flicking and dragging may no
3036 * longer scroll, but pressing/dragging near an edge of the scroller will
3037 * still scroll. This is automastically used by the entry object when
3039 * 2. To totally freeze scrolling. This means it stops. until popped/released.
3043 * Push the scroll hold by 1
3045 * This increments the scroll hold count by one. If it is more than 0 it will
3046 * take effect on the parents of the indicated object.
3048 * @param obj The object
3049 * @ingroup Scrollhints
3052 elm_object_scroll_hold_push(Evas_Object *obj)
3054 EINA_SAFETY_ON_NULL_RETURN(obj);
3055 elm_widget_scroll_hold_push(obj);
3059 * Pop the scroll hold by 1
3061 * This decrements the scroll hold count by one. If it is more than 0 it will
3062 * take effect on the parents of the indicated object.
3064 * @param obj The object
3065 * @ingroup Scrollhints
3068 elm_object_scroll_hold_pop(Evas_Object *obj)
3070 EINA_SAFETY_ON_NULL_RETURN(obj);
3071 elm_widget_scroll_hold_pop(obj);
3075 * Push the scroll freeze by 1
3077 * This increments the scroll freeze count by one. If it is more than 0 it will
3078 * take effect on the parents of the indicated object.
3080 * @param obj The object
3081 * @ingroup Scrollhints
3084 elm_object_scroll_freeze_push(Evas_Object *obj)
3086 EINA_SAFETY_ON_NULL_RETURN(obj);
3087 elm_widget_scroll_freeze_push(obj);
3091 * Lock the scrolling of the given widget (and thus all parents)
3093 * This locks the given object from scrolling in the X axis (and implicitly
3094 * also locks all parent scrollers too from doing the same).
3096 * @param obj The object
3097 * @param lock The lock state (1 == locked, 0 == unlocked)
3098 * @ingroup Scrollhints
3101 elm_object_scroll_lock_x_set(Evas_Object *obj,
3104 EINA_SAFETY_ON_NULL_RETURN(obj);
3105 elm_widget_drag_lock_x_set(obj, lock);
3109 * Lock the scrolling of the given widget (and thus all parents)
3111 * This locks the given object from scrolling in the Y axis (and implicitly
3112 * also locks all parent scrollers too from doing the same).
3114 * @param obj The object
3115 * @param lock The lock state (1 == locked, 0 == unlocked)
3116 * @ingroup Scrollhints
3119 elm_object_scroll_lock_y_set(Evas_Object *obj,
3122 EINA_SAFETY_ON_NULL_RETURN(obj);
3123 elm_widget_drag_lock_y_set(obj, lock);
3127 * Get the scrolling lock of the given widget
3129 * This gets the lock for X axis scrolling.
3131 * @param obj The object
3132 * @ingroup Scrollhints
3135 elm_object_scroll_lock_x_get(const Evas_Object *obj)
3137 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3138 return elm_widget_drag_lock_x_get(obj);
3142 * Get the scrolling lock of the given widget
3144 * This gets the lock for X axis scrolling.
3146 * @param obj The object
3147 * @ingroup Scrollhints
3150 elm_object_scroll_lock_y_get(const Evas_Object *obj)
3152 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3153 return elm_widget_drag_lock_y_get(obj);
3157 * Pop the scroll freeze by 1
3159 * This decrements the scroll freeze count by one. If it is more than 0 it will
3160 * take effect on the parents of the indicated object.
3162 * @param obj The object
3163 * @ingroup Scrollhints
3166 elm_object_scroll_freeze_pop(Evas_Object *obj)
3168 EINA_SAFETY_ON_NULL_RETURN(obj);
3169 elm_widget_scroll_freeze_pop(obj);
3173 * @defgroup WidgetNavigation Widget Tree Navigation.
3175 * How to check if an Evas Object is an Elementary widget? How to get
3176 * the first elementary widget that is parent of the given object?
3177 * These are all covered in widget tree navigation.
3181 * Check if the given Evas Object is an Elementary widget.
3183 * @param obj the object to query.
3184 * @return @c EINA_TRUE if it is an elementary widget variant,
3185 * @c EINA_FALSE otherwise
3186 * @ingroup WidgetNavigation
3189 elm_object_widget_check(const Evas_Object *obj)
3191 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3192 return elm_widget_is(obj);
3196 * Get the first parent of the given object that is an Elementary widget.
3198 * @param obj the object to query.
3199 * @return the parent object that is an Elementary widget, or @c NULL
3200 * if no parent is, or no parents at all.
3201 * @ingroup WidgetNavigation
3204 elm_object_parent_widget_get(const Evas_Object *obj)
3206 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3207 return elm_widget_parent_widget_get(obj);
3211 * Get the top level parent of an Elementary widget.
3213 * @param obj The object to query.
3214 * @return The top level Elementary widget, or @c NULL if parent cannot be
3216 * @ingroup WidgetNavigation
3219 elm_object_top_widget_get(const Evas_Object *obj)
3221 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3222 return elm_widget_top_get(obj);
3226 * Get the string that represents this Elementary widget.
3228 * @note Elementary is weird and exposes itself as a single
3229 * Evas_Object_Smart_Class of type "elm_widget", so
3230 * evas_object_type_get() always return that, making debug and
3231 * language bindings hard. This function tries to mitigate this
3232 * problem, but the solution is to change Elementary to use
3233 * proper inheritance.
3235 * @param obj the object to query.
3236 * @return Elementary widget name, or @c NULL if not a valid widget.
3237 * @ingroup WidgetNavigation
3240 elm_object_widget_type_get(const Evas_Object *obj)
3242 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3243 return elm_widget_type_get(obj);
3247 * Send a signal to the widget edje object.
3249 * This function sends a signal to the edje object of the obj. An edje program
3250 * can respond to a signal by specifying matching 'signal' and
3253 * @param obj The object
3254 * @param emission The signal's name.
3255 * @param source The signal's source.
3259 elm_object_signal_emit(Evas_Object *obj,
3260 const char *emission,
3263 EINA_SAFETY_ON_NULL_RETURN(obj);
3264 elm_widget_signal_emit(obj, emission, source);
3268 * Add a callback for a signal emitted by widget edje object.
3270 * This function connects a callback function to a signal emitted by the
3271 * edje object of the obj.
3272 * Globs can occur in either the emission or source name.
3274 * @param obj The object
3275 * @param emission The signal's name.
3276 * @param source The signal's source.
3277 * @param func The callback function to be executed when the signal is
3279 * @param data A pointer to data to pass in to the callback function.
3283 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)
3285 EINA_SAFETY_ON_NULL_RETURN(obj);
3286 EINA_SAFETY_ON_NULL_RETURN(func);
3287 elm_widget_signal_callback_add(obj, emission, source, func, data);
3291 * Remove a signal-triggered callback from an widget edje object.
3293 * This function removes a callback, previoulsy attached to a signal emitted
3294 * by the edje object of the obj.
3295 * The parameters emission, source and func must match exactly those passed to
3296 * a previous call to elm_object_signal_callback_add(). The data pointer that
3297 * was passed to this call will be returned.
3299 * @param obj The object
3300 * @param emission The signal's name.
3301 * @param source The signal's source.
3302 * @param func The callback function to be executed when the signal is
3304 * @return The data pointer
3308 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))
3310 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3311 EINA_SAFETY_ON_NULL_RETURN_VAL(func, NULL);
3312 return elm_widget_signal_callback_del(obj, emission, source, func);
3316 * Add a callback for a event emitted by widget or their children.
3318 * This function connects a callback function to any key_down key_up event
3319 * emitted by the @p obj or their children.
3320 * This only will be called if no other callback has consumed the event.
3321 * If you want consume the event, and no other get it, func should return
3322 * EINA_TRUE and put EVAS_EVENT_FLAG_ON_HOLD in event_flags.
3324 * @warning Accept duplicated callback addition.
3326 * @param obj The object
3327 * @param func The callback function to be executed when the event is
3329 * @param data Data to pass in to the callback function.
3333 elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data)
3335 EINA_SAFETY_ON_NULL_RETURN(obj);
3336 EINA_SAFETY_ON_NULL_RETURN(func);
3337 elm_widget_event_callback_add(obj, func, data);
3341 * Remove a event callback from an widget.
3343 * This function removes a callback, previoulsy attached to event emission
3345 * The parameters func and data must match exactly those passed to
3346 * a previous call to elm_object_event_callback_add(). The data pointer that
3347 * was passed to this call will be returned.
3349 * @param obj The object
3350 * @param func The callback function to be executed when the event is
3352 * @param data Data to pass in to the callback function.
3353 * @return The data pointer
3357 elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data)
3359 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3360 EINA_SAFETY_ON_NULL_RETURN_VAL(func, NULL);
3361 return elm_widget_event_callback_del(obj, func, data);
3366 * @defgroup Debug Debug
3370 * Print Tree object hierarchy in stdout
3372 * @param obj The root object
3376 elm_object_tree_dump(const Evas_Object *top)
3379 elm_widget_tree_dump(top);
3387 * Print Elm Objects tree hierarchy in file as dot(graphviz) syntax.
3389 * @param obj The root object
3390 * @param file The path of output file
3394 elm_object_tree_dot_dump(const Evas_Object *top,
3398 FILE *f = fopen(file, "w");
3399 elm_widget_tree_dot_dump(top, f);
3409 * Set the duration for occuring long press event.
3411 * @param lonpress_timeout Timeout for long press event
3412 * @ingroup Longpress
3415 elm_longpress_timeout_set(double longpress_timeout)
3417 _elm_config->longpress_timeout = longpress_timeout;
3421 * Get the duration for occuring long press event.
3423 * @return Timeout for long press event
3424 * @ingroup Longpress
3427 elm_longpress_timeout_get(void)
3429 return _elm_config->longpress_timeout;