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 elm_quicklaunch_sub_shutdown();
373 elm_quicklaunch_shutdown();
374 return _elm_init_count;
378 static int _elm_need_e_dbus = 0;
381 elm_need_e_dbus(void)
384 if (_elm_need_e_dbus++) return EINA_TRUE;
394 _elm_unneed_e_dbus(void)
397 if (--_elm_need_e_dbus) return;
399 _elm_need_e_dbus = 0;
406 static int _elm_need_efreet = 0;
409 elm_need_efreet(void)
412 if (_elm_need_efreet++) return EINA_TRUE;
420 list = efreet_icon_extra_list_get();
423 e_user_dir_concat_static(buf, "icons");
424 *list = eina_list_prepend(*list, (void *)eina_stringshare_add(buf));
425 e_prefix_data_concat_static(buf, "data/icons");
426 *list = eina_list_prepend(*list, (void *)eina_stringshare_add(buf));
437 _elm_unneed_efreet(void)
440 if (--_elm_need_efreet) return;
442 _elm_need_efreet = 0;
443 efreet_trash_shutdown();
444 efreet_mime_shutdown();
450 elm_quicklaunch_mode_set(Eina_Bool ql_on)
452 quicklaunch_on = ql_on;
456 elm_quicklaunch_mode_get(void)
458 return quicklaunch_on;
462 elm_quicklaunch_init(int argc,
465 char buf[PATH_MAX], *s;
467 _elm_ql_init_count++;
468 if (_elm_ql_init_count > 1) return _elm_ql_init_count;
470 _elm_log_dom = eina_log_domain_register("elementary", EINA_COLOR_LIGHTBLUE);
473 EINA_LOG_ERR("could not register elementary log domain.");
474 _elm_log_dom = EINA_LOG_DOMAIN_GLOBAL;
479 ecore_app_args_set(argc, (const char **)argv);
481 memset(_elm_policies, 0, sizeof(_elm_policies));
482 if (!ELM_EVENT_POLICY_CHANGED)
483 ELM_EVENT_POLICY_CHANGED = ecore_event_type_new();
487 _elm_exit_handler = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT, _elm_signal_exit, NULL);
489 if (argv) _elm_appname = strdup(ecore_file_file_get(argv[0]));
493 s = getenv("ELM_DATA_DIR");
494 _elm_data_dir = eina_stringshare_add(s);
498 s = getenv("ELM_PREFIX");
501 snprintf(buf, sizeof(buf), "%s/share/elementary", s);
502 _elm_data_dir = eina_stringshare_add(buf);
507 s = getenv("ELM_LIB_DIR");
508 _elm_lib_dir = eina_stringshare_add(s);
512 s = getenv("ELM_PREFIX");
515 snprintf(buf, sizeof(buf), "%s/lib", s);
516 _elm_lib_dir = eina_stringshare_add(buf);
520 if ((!_elm_data_dir) || (!_elm_lib_dir))
522 Dl_info elementary_dl;
523 // libelementary.so/../../share/elementary/
524 if (dladdr(elm_init, &elementary_dl))
528 dir = ecore_file_dir_get(elementary_dl.dli_fname);
533 if (ecore_file_is_dir(dir))
534 _elm_lib_dir = eina_stringshare_add(dir);
538 dir2 = ecore_file_dir_get(dir);
541 snprintf(buf, sizeof(buf), "%s/share/elementary", dir2);
542 if (ecore_file_is_dir(buf))
543 _elm_data_dir = eina_stringshare_add(buf);
553 _elm_data_dir = eina_stringshare_add(PACKAGE_DATA_DIR);
555 _elm_data_dir = eina_stringshare_add("/");
557 _elm_lib_dir = eina_stringshare_add(PACKAGE_LIB_DIR);
559 _elm_lib_dir = eina_stringshare_add("/");
562 return _elm_ql_init_count;
566 elm_quicklaunch_sub_init(int argc,
569 _elm_sub_init_count++;
570 if (_elm_sub_init_count > 1) return _elm_sub_init_count;
573 #ifdef SEMI_BROKEN_QUICKLAUNCH
574 return _elm_sub_init_count;
579 ecore_app_args_set(argc, (const char **)argv);
583 _elm_config_sub_init();
584 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
585 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
586 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
587 ENGINE_COMPARE(ELM_XRENDER_X11) ||
588 ENGINE_COMPARE(ELM_OPENGL_X11))
589 #undef ENGINE_COMPARE
591 #ifdef HAVE_ELEMENTARY_X
595 ecore_evas_init(); // FIXME: check errors
598 return _elm_sub_init_count;
602 elm_quicklaunch_sub_shutdown(void)
604 _elm_sub_init_count--;
605 if (_elm_sub_init_count > 0) return _elm_sub_init_count;
608 #ifdef SEMI_BROKEN_QUICKLAUNCH
609 return _elm_sub_init_count;
615 _elm_module_shutdown();
616 ecore_imf_shutdown();
617 ecore_evas_shutdown();
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 #undef ENGINE_COMPARE
625 #ifdef HAVE_ELEMENTARY_X
626 ecore_x_disconnect();
629 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
630 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
631 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
632 ENGINE_COMPARE(ELM_XRENDER_X11) ||
633 ENGINE_COMPARE(ELM_OPENGL_X11) ||
634 ENGINE_COMPARE(ELM_SOFTWARE_SDL) ||
635 ENGINE_COMPARE(ELM_SOFTWARE_16_SDL) ||
636 ENGINE_COMPARE(ELM_OPENGL_SDL) ||
637 ENGINE_COMPARE(ELM_SOFTWARE_WIN32) ||
638 ENGINE_COMPARE(ELM_SOFTWARE_16_WINCE))
639 #undef ENGINE_COMPARE
640 evas_cserve_disconnect();
644 return _elm_sub_init_count;
648 elm_quicklaunch_shutdown(void)
650 _elm_ql_init_count--;
651 if (_elm_ql_init_count > 0) return _elm_ql_init_count;
652 eina_stringshare_del(_elm_data_dir);
653 _elm_data_dir = NULL;
654 eina_stringshare_del(_elm_lib_dir);
660 _elm_config_shutdown();
662 ecore_event_handler_del(_elm_exit_handler);
663 _elm_exit_handler = NULL;
665 _elm_theme_shutdown();
666 _elm_unneed_efreet();
667 _elm_unneed_e_dbus();
668 _elm_unneed_ethumb();
669 ecore_file_shutdown();
673 if ((_elm_log_dom > -1) && (_elm_log_dom != EINA_LOG_DOMAIN_GLOBAL))
675 eina_log_domain_unregister(_elm_log_dom);
679 _elm_widget_type_clear();
682 return _elm_ql_init_count;
686 elm_quicklaunch_seed(void)
688 #ifndef SEMI_BROKEN_QUICKLAUNCH
691 Evas_Object *win, *bg, *bt;
693 win = elm_win_add(NULL, "seed", ELM_WIN_BASIC);
694 bg = elm_bg_add(win);
695 elm_win_resize_object_add(win, bg);
696 evas_object_show(bg);
697 bt = elm_button_add(win);
698 elm_button_label_set(bt, " abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789~-_=+\\|]}[{;:'\",<.>/?");
699 elm_win_resize_object_add(win, bt);
700 ecore_main_loop_iterate();
701 evas_object_del(win);
702 ecore_main_loop_iterate();
703 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
704 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
705 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
706 ENGINE_COMPARE(ELM_XRENDER_X11) ||
707 ENGINE_COMPARE(ELM_OPENGL_X11))
708 #undef ENGINE_COMPARE
710 # ifdef HAVE_ELEMENTARY_X
714 ecore_main_loop_iterate();
719 static void *qr_handle = NULL;
720 static int (*qr_main)(int argc,
724 elm_quicklaunch_prepare(int argc __UNUSED__,
728 char *exe = elm_quicklaunch_exe_path_get(argv[0]);
731 ERR("requested quicklaunch binary '%s' does not exist\n", argv[0]);
739 exe2 = malloc(strlen(exe) + 1 + 10);
741 p = strrchr(exe2, '/');
744 exename = alloca(strlen(p) + 1);
747 strcat(p, "../lib/");
750 if (!access(exe2, R_OK | X_OK))
758 qr_handle = dlopen(exe, RTLD_NOW | RTLD_GLOBAL);
761 fprintf(stderr, "dlerr: %s\n", dlerror());
762 WRN("dlopen('%s') failed: %s", exe, dlerror());
766 INF("dlopen('%s') = %p", exe, qr_handle);
767 qr_main = dlsym(qr_handle, "elm_main");
768 INF("dlsym(%p, 'elm_main') = %p", qr_handle, qr_main);
771 WRN("not quicklauncher capable: no elm_main in '%s'", exe);
790 extern char **environ;
795 for (i = 0, size = 0; environ[i]; i++)
796 size += strlen(environ[i]) + 1;
798 p = malloc((i + 1) * sizeof(char *));
803 for (i = 0; oldenv[i]; i++)
804 environ[i] = strdup(oldenv[i]);
811 elm_quicklaunch_fork(int argc,
814 void (postfork_func) (void *data),
824 // need to accept current environment from elementary_run
831 if (child > 0) return EINA_TRUE;
834 perror("could not fork");
839 perror("could not chdir");
840 args = alloca((argc + 1) * sizeof(char *));
841 for (i = 0; i < argc; i++) args[i] = argv[i];
843 WRN("%s not quicklaunch capable, fallback...", argv[0]);
844 execvp(argv[0], args);
845 ERR("failed to execute '%s': %s", argv[0], strerror(errno));
849 if (child > 0) return EINA_TRUE;
852 perror("could not fork");
855 if (postfork_func) postfork_func(postfork_data);
859 #ifdef SEMI_BROKEN_QUICKLAUNCH
860 ecore_app_args_set(argc, (const char **)argv);
863 _elm_config_sub_init();
864 #define ENGINE_COMPARE(name) (!strcmp(_elm_config->engine, name))
865 if (ENGINE_COMPARE(ELM_SOFTWARE_X11) ||
866 ENGINE_COMPARE(ELM_SOFTWARE_16_X11) ||
867 ENGINE_COMPARE(ELM_XRENDER_X11) ||
868 ENGINE_COMPARE(ELM_OPENGL_X11))
869 #undef ENGINE_COMPARE
871 # ifdef HAVE_ELEMENTARY_X
875 ecore_evas_init(); // FIXME: check errors
883 perror("could not chdir");
884 // FIXME: this is very linux specific. it changes argv[0] of the process
885 // so ps etc. report what you'd expect. for other unixes and os's this
892 ecore_app_args_get(&real_argc, &real_argv);
893 lastarg = real_argv[real_argc - 1] + strlen(real_argv[real_argc - 1]);
894 for (p = real_argv[0]; p < lastarg; p++) *p = 0;
895 strcpy(real_argv[0], argv[0]);
897 ecore_app_args_set(argc, (const char **)argv);
898 ret = qr_main(argc, argv);
912 elm_quicklaunch_cleanup(void)
925 elm_quicklaunch_fallback(int argc,
929 elm_quicklaunch_init(argc, argv);
930 elm_quicklaunch_sub_init(argc, argv);
931 elm_quicklaunch_prepare(argc, argv);
932 ret = qr_main(argc, argv);
938 elm_quicklaunch_exe_path_get(const char *exe)
940 static char *path = NULL;
941 static Eina_List *pathlist = NULL;
945 if (exe[0] == '/') return strdup(exe);
946 if ((exe[0] == '.') && (exe[1] == '/')) return strdup(exe);
947 if ((exe[0] == '.') && (exe[1] == '.') && (exe[2] == '/')) return strdup(exe);
952 path = getenv("PATH");
953 buf2 = alloca(strlen(path) + 1);
958 if ((*p == ':') || (!*p))
963 strncpy(buf2, pp, len);
965 pathlist = eina_list_append(pathlist, eina_stringshare_add(buf2));
977 EINA_LIST_FOREACH(pathlist, l, pathitr)
979 snprintf(buf, sizeof(buf), "%s/%s", pathitr, exe);
980 if (!access(buf, R_OK | X_OK)) return strdup(buf);
988 * This call should be called just after all initialization is complete. This
989 * function will not return until elm_exit() is called. It will keep looping
990 * running the main event/processing loop for Elementary.
996 ecore_main_loop_begin();
1000 * Exit the main loop
1002 * If this call is called, it will flag the main loop to cease processing and
1003 * return back to its parent function.
1009 ecore_main_loop_quit();
1013 * Set new policy value.
1015 * This will emit the ecore event ELM_EVENT_POLICY_CHANGED in the main
1016 * loop giving the event information Elm_Event_Policy_Changed with
1017 * policy identifier, new and old values.
1019 * @param policy policy identifier as in Elm_Policy.
1020 * @param value policy value, depends on identifiers, usually there is
1021 * an enumeration with the same prefix as the policy name, for
1022 * example: ELM_POLICY_QUIT and Elm_Policy_Quit
1023 * (ELM_POLICY_QUIT_NONE, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED).
1026 * @return @c EINA_TRUE on success or @c EINA_FALSE on error (right
1027 * now just invalid policy identifier, but in future policy
1028 * value might be enforced).
1031 elm_policy_set(unsigned int policy,
1034 Elm_Event_Policy_Changed *ev;
1036 if (policy >= ELM_POLICY_LAST)
1039 if (value == _elm_policies[policy])
1042 /* TODO: validade policy? */
1044 ev = malloc(sizeof(*ev));
1045 ev->policy = policy;
1046 ev->new_value = value;
1047 ev->old_value = _elm_policies[policy];
1049 _elm_policies[policy] = value;
1051 ecore_event_add(ELM_EVENT_POLICY_CHANGED, ev, NULL, NULL);
1057 * Gets the policy value set for given identifier.
1059 * @param policy policy identifier as in Elm_Policy.
1062 * @return policy value. Will be 0 if policy identifier is invalid.
1065 elm_policy_get(unsigned int policy)
1067 if (policy >= ELM_POLICY_LAST)
1069 return _elm_policies[policy];
1073 * @defgroup Scaling Selective Widget Scaling
1076 * Different widgets can be scaled independently. These functions allow you to
1077 * manipulate this scaling on a per-widget basis. The object and all its
1078 * children get their scaling factors multiplied by the scale factor set.
1079 * This is multiplicative, in that if a child also has a scale size set it is
1080 * in turn multiplied by its parent's scale size. 1.0 means “don't scale”,
1081 * 2.0 is double size, 0.5 is half etc.
1085 * Set the scaling factor
1087 * @param obj The object
1088 * @param scale Scale factor (from 0.0 up, with 1.0 == no scaling)
1092 elm_object_scale_set(Evas_Object *obj,
1095 EINA_SAFETY_ON_NULL_RETURN(obj);
1096 elm_widget_scale_set(obj, scale);
1100 * Get the scaling factor
1102 * @param obj The object
1103 * @return The scaling factor set by elm_object_scale_set()
1107 elm_object_scale_get(const Evas_Object *obj)
1109 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, 0.0);
1110 return elm_widget_scale_get(obj);
1114 * Get the global scaling factor
1116 * This gets the globally configured scaling factor that is applied to all
1119 * @return The scaling factor
1125 return _elm_config->scale;
1129 * Set the global scaling factor
1131 * This sets the globally configured scaling factor that is applied to all
1134 * @param scale The scaling factor to set
1138 elm_scale_set(double scale)
1140 if (_elm_config->scale == scale) return;
1141 _elm_config->scale = scale;
1146 * Set the global scaling factor for all applications on the display
1148 * This sets the globally configured scaling factor that is applied to all
1149 * objects for all applications.
1150 * @param scale The scaling factor to set
1154 elm_scale_all_set(double scale)
1156 #ifdef HAVE_ELEMENTARY_X
1157 static Ecore_X_Atom atom = 0;
1158 unsigned int scale_i = (unsigned int)(scale * 1000.0);
1160 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_SCALE");
1161 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1167 * @defgroup Styles Styles
1170 * Widgets can have different styles of look. These generic API's set
1171 * styles of widgets, if they support them (and if the theme(s) do).
1177 * This sets the name of the style
1178 * @param obj The object
1179 * @param style The style name to use
1183 elm_object_style_set(Evas_Object *obj,
1186 EINA_SAFETY_ON_NULL_RETURN(obj);
1187 elm_widget_style_set(obj, style);
1193 * This gets the style being used for that widget. Note that the string
1194 * pointer is only valid as longas the object is valid and the style doesn't
1197 * @param obj The object
1198 * @return The style name
1202 elm_object_style_get(const Evas_Object *obj)
1204 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
1205 return elm_widget_style_get(obj);
1209 * Set the disable state
1211 * This sets the disable state for the widget.
1213 * @param obj The object
1214 * @param disabled The state
1218 elm_object_disabled_set(Evas_Object *obj,
1221 EINA_SAFETY_ON_NULL_RETURN(obj);
1222 elm_widget_disabled_set(obj, disabled);
1226 * Get the disable state
1228 * This gets the disable state for the widget.
1230 * @param obj The object
1231 * @return True, if the widget is disabled
1235 elm_object_disabled_get(const Evas_Object *obj)
1237 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
1238 return elm_widget_disabled_get(obj);
1242 * @defgroup Config Elementary Config
1245 * Elementary configuration is formed by a set options bounded to a
1246 * given @ref Profile profile, like @ref Theme theme, @ref Fingers
1247 * "finger size", etc. These are functions with which one syncronizes
1248 * changes made to those values to the configuration storing files, de
1249 * facto. You most probably don't want to use the functions in this
1250 * group unlees you're writing an elementary configuration manager.
1254 * Save back Elementary's configuration, so that it will persist on
1257 * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
1260 * This function will take effect -- thus, do I/O -- immediately. Use
1261 * it when you want to apply all configuration changes at once. The
1262 * current configuration set will get saved onto the current profile
1263 * configuration file.
1267 elm_config_save(void)
1269 return _elm_config_save();
1273 * Reload Elementary's configuration, bounded to current selected
1276 * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
1279 * Useful when you want to force reloading of configuration values for
1280 * a profile. If one removes user custom configuration directories,
1281 * for example, it will force a reload with system values insted.
1285 elm_config_reload(void)
1287 _elm_config_reload();
1291 * @defgroup Profile Elementary Profile
1294 * Profiles are pre-set options that affect the whole look-and-feel of
1295 * Elementary-based applications. There are, for example, profiles
1296 * aimed at desktop computer applications and others aimed at mobile,
1297 * touchscreen-based ones. You most probably don't want to use the
1298 * functions in this group unlees you're writing an elementary
1299 * configuration manager.
1303 * Get Elementary's profile in use.
1305 * This gets the global profile that is applied to all Elementary
1308 * @return The profile's name
1312 elm_profile_current_get(void)
1314 return _elm_config_current_profile_get();
1318 * Get an Elementary's profile directory path in the filesystem. One
1319 * may want to fetch a system profile's dir or an user one (fetched
1322 * @param profile The profile's name
1323 * @param is_user Whether to lookup for an user profile (@c EINA_TRUE)
1324 * or a system one (@c EINA_FALSE)
1325 * @return The profile's directory path.
1328 * @note You must free it with elm_profile_dir_free().
1331 elm_profile_dir_get(const char *profile,
1334 return _elm_config_profile_dir_get(profile, is_user);
1338 * Free an Elementary's profile directory path, as returned by
1339 * elm_profile_dir_get().
1341 * @param p_dir The profile's path
1346 elm_profile_dir_free(const char *p_dir)
1348 free((void *)p_dir);
1352 * Get Elementary's list of available profiles.
1354 * @return The profiles list. List node data are the profile name
1358 * @note One must free this list, after usage, with the function
1359 * elm_profile_list_free().
1362 elm_profile_list_get(void)
1364 return _elm_config_profiles_list();
1368 * Free Elementary's list of available profiles.
1370 * @param The profiles list, as returned by elm_profile_list_get().
1375 elm_profile_list_free(Eina_List *l)
1379 EINA_LIST_FREE(l, dir)
1380 eina_stringshare_del(dir);
1384 * Set Elementary's profile.
1386 * This sets the global profile that is applied to Elementary
1387 * applications. Just the process the call comes from will be
1390 * @param profile The profile's name
1395 elm_profile_set(const char *profile)
1397 EINA_SAFETY_ON_NULL_RETURN(profile);
1398 _elm_config_profile_set(profile);
1402 * Set Elementary's profile.
1404 * This sets the global profile that is applied to all Elementary
1405 * applications. All running Elementary windows will be affected.
1407 * @param profile The profile's name
1412 elm_profile_all_set(const char *profile)
1414 #ifdef HAVE_ELEMENTARY_X
1415 static Ecore_X_Atom atom = 0;
1417 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_PROFILE");
1418 ecore_x_window_prop_string_set(ecore_x_window_root_first_get(),
1424 * @defgroup Engine Elementary Engine
1427 * These are functions setting and querying which rendering engine
1428 * Elementary will use for drawing its windows' pixels.
1432 * Get Elementary's rendering engine in use.
1434 * This gets the global rendering engine that is applied to all
1435 * Elementary applications.
1437 * @return The rendering engine's name
1440 * @note there's no need to free the returned string, here.
1443 elm_engine_current_get(void)
1445 return _elm_config->engine;
1449 * Set Elementary's rendering engine for use.
1451 * This gets sets global rendering engine that is applied to all
1452 * Elementary applications. Note that it will take effect only to
1453 * subsequent Elementary window creations.
1455 * @param The rendering engine's name
1458 * @note there's no need to free the returned string, here.
1461 elm_engine_set(const char *engine)
1463 EINA_SAFETY_ON_NULL_RETURN(engine);
1465 _elm_config_engine_set(engine);
1469 * @defgroup Fonts Elementary Fonts
1472 * These are functions dealing with font rendering, selection and the
1473 * like for Elementary applications. One might fetch which system
1474 * fonts are there to use and set custom fonts for individual classes
1475 * of UI items containing text (text classes).
1479 * Get Elementary's list of supported text classes.
1481 * @return The text classes list, with @c Elm_Text_Class blobs as data.
1484 * Release the list with elm_text_classes_list_free().
1486 EAPI const Eina_List *
1487 elm_text_classes_list_get(void)
1489 return _elm_config_text_classes_get();
1493 * Free Elementary's list of supported text classes.
1497 * @see elm_text_classes_list_get().
1500 elm_text_classes_list_free(const Eina_List *list)
1502 _elm_config_text_classes_free((Eina_List *)list);
1506 * Get Elementary's list of font overlays, set with
1507 * elm_font_overlay_set().
1509 * @return The font overlays list, with @c Elm_Font_Overlay blobs as
1514 * For each text class, one can set a <b>font overlay</b> for it,
1515 * overriding the default font properties for that class coming from
1516 * the theme in use. There is no need to free this list.
1518 * @see elm_font_overlay_set() and elm_font_overlay_unset().
1520 EAPI const Eina_List *
1521 elm_font_overlay_list_get(void)
1523 return _elm_config_font_overlays_list();
1527 * Set a font overlay for a given Elementary text class.
1529 * @param text_class Text class name
1530 * @param font Font name and style string
1531 * @param size Font size
1535 * @p font has to be in the format returned by
1536 * elm_font_fontconfig_name_get(). @see elm_font_overlay_list_get()
1537 * and @elm_font_overlay_unset().
1540 elm_font_overlay_set(const char *text_class,
1542 Evas_Font_Size size)
1544 _elm_config_font_overlay_set(text_class, font, size);
1548 * Unset a font overlay for a given Elementary text class.
1550 * @param text_class Text class name
1554 * This will bring back text elements belonging to text class @p
1555 * text_class back to their default font settings.
1558 elm_font_overlay_unset(const char *text_class)
1560 _elm_config_font_overlay_remove(text_class);
1564 * Apply the changes made with elm_font_overlay_set() and
1565 * elm_font_overlay_unset() on the current Elementary window.
1569 * This applies all font overlays set to all objects in the UI.
1572 elm_font_overlay_apply(void)
1574 _elm_config_font_overlay_apply();
1578 * Apply the changes made with elm_font_overlay_set() and
1579 * elm_font_overlay_unset() on all Elementary application windows.
1583 * This applies all font overlays set to all objects in the UI.
1586 elm_font_overlay_all_apply(void)
1588 #ifdef HAVE_ELEMENTARY_X
1589 static Ecore_X_Atom atom = 0;
1590 unsigned int dummy = (unsigned int)(1 * 1000.0);
1592 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FONT_OVERLAY");
1593 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(), atom, &dummy,
1599 * Translate a font (family) name string in fontconfig's font names
1600 * syntax into an @c Elm_Font_Properties struct.
1602 * @param font The font name and styles string
1603 * @return the font properties struct
1607 * @note The reverse translation can be achived with
1608 * elm_font_fontconfig_name_get(), for one style only (single font
1609 * instance, not family).
1611 EAPI Elm_Font_Properties *
1612 elm_font_properties_get(const char *font)
1614 EINA_SAFETY_ON_NULL_RETURN_VAL(font, NULL);
1615 return _elm_font_properties_get(NULL, font);
1619 * Free font properties return by elm_font_properties_get().
1621 * @param efp the font properties struct
1626 elm_font_properties_free(Elm_Font_Properties *efp)
1630 EINA_SAFETY_ON_NULL_RETURN(efp);
1631 EINA_LIST_FREE(efp->styles, str)
1632 if (str) eina_stringshare_del(str);
1633 if (efp->name) eina_stringshare_del(efp->name);
1638 * Translate a font name, bound to a style, into fontconfig's font names
1641 * @param name The font (family) name
1642 * @param style The given style (may be @c NULL)
1644 * @return the font name and style string
1648 * @note The reverse translation can be achived with
1649 * elm_font_properties_get(), for one style only (single font
1650 * instance, not family).
1653 elm_font_fontconfig_name_get(const char *name,
1658 EINA_SAFETY_ON_NULL_RETURN_VAL(name, NULL);
1659 if (!style || style[0] == 0) return eina_stringshare_add(name);
1660 snprintf(buf, 256, "%s" ELM_FONT_TOKEN_STYLE "%s", name, style);
1661 return eina_stringshare_add(buf);
1665 * Free the font string return by elm_font_fontconfig_name_get().
1667 * @param efp the font properties struct
1672 elm_font_fontconfig_name_free(const char *name)
1674 eina_stringshare_del(name);
1678 * Create a font hash table of available system fonts.
1680 * One must call it with @p list being the return value of
1681 * evas_font_available_list(). The hash will be indexed by font
1682 * (family) names, being its values @c Elm_Font_Properties blobs.
1684 * @param list The list of available system fonts, as returned by
1685 * evas_font_available_list().
1686 * @return the font hash.
1690 * @note The user is supposed to get it populated at least with 3
1691 * default font families (Sans, Serif, Monospace), which should be
1692 * present on most systems.
1695 elm_font_available_hash_add(Eina_List *list)
1697 Eina_Hash *font_hash;
1703 /* populate with default font families */
1704 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Regular");
1705 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Bold");
1706 font_hash = _elm_font_available_hash_add(font_hash, "Sans:style=Oblique");
1707 font_hash = _elm_font_available_hash_add(font_hash,
1708 "Sans:style=Bold Oblique");
1710 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Regular");
1711 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Bold");
1712 font_hash = _elm_font_available_hash_add(font_hash, "Serif:style=Oblique");
1713 font_hash = _elm_font_available_hash_add(font_hash,
1714 "Serif:style=Bold Oblique");
1716 font_hash = _elm_font_available_hash_add(font_hash,
1717 "Monospace:style=Regular");
1718 font_hash = _elm_font_available_hash_add(font_hash,
1719 "Monospace:style=Bold");
1720 font_hash = _elm_font_available_hash_add(font_hash,
1721 "Monospace:style=Oblique");
1722 font_hash = _elm_font_available_hash_add(font_hash,
1723 "Monospace:style=Bold Oblique");
1725 EINA_LIST_FOREACH(list, l, key)
1726 font_hash = _elm_font_available_hash_add(font_hash, key);
1732 * Free the hash return by elm_font_available_hash_add().
1734 * @param hash the hash to be freed.
1739 elm_font_available_hash_del(Eina_Hash *hash)
1741 _elm_font_available_hash_del(hash);
1745 * @defgroup Fingers Fingers
1748 * Elementary is designed to be finger-friendly for touchscreens, and so in
1749 * addition to scaling for display resolution, it can also scale based on
1750 * finger "resolution" (or size).
1754 * Get the configured finger size
1756 * This gets the globally configured finger size in pixels
1758 * @return The finger size
1762 elm_finger_size_get(void)
1764 return _elm_config->finger_size;
1768 * Set the configured finger size
1770 * This sets the globally configured finger size in pixels
1772 * @param size The finger size
1776 elm_finger_size_set(Evas_Coord size)
1778 if (_elm_config->finger_size == size) return;
1779 _elm_config->finger_size = size;
1784 * Set the configured finger size for all applications on the display
1786 * This sets the globally configured finger size in pixels for all applications
1789 * @param size The finger size
1793 elm_finger_size_all_set(Evas_Coord size)
1795 #ifdef HAVE_ELEMENTARY_X
1796 static Ecore_X_Atom atom = 0;
1797 unsigned int size_i = (unsigned int)size;
1799 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FINGER_SIZE");
1800 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1806 elm_autocapitalization_allow_all_set(Eina_Bool on)
1808 #ifdef HAVE_ELEMENTARY_X
1809 static Ecore_X_Atom atom = 0;
1810 unsigned int on_i = (unsigned int)on;
1812 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_AUTOCAPITAL_ALLOW");
1813 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1819 elm_autoperiod_allow_all_set(Eina_Bool on)
1821 #ifdef HAVE_ELEMENTARY_X
1822 static Ecore_X_Atom atom = 0;
1823 unsigned int on_i = (unsigned int)on;
1825 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_AUTOPERIOD_ALLOW");
1826 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1833 * Adjust size of an element for finger usage
1835 * This takes width and height sizes (in pixels) as input and a size multiple
1836 * (which is how many fingers you want to place within the area), and adjusts
1837 * the size tobe large enough to accommodate finger. On return the w and h
1838 * sizes poiner do by these parameters will be modified.
1840 * @param times_w How many fingers should fit horizontally
1841 * @param w Pointer to the width size to adjust
1842 * @param times_h How many fingers should fit vertically
1843 * @param h Pointer to the height size to adjust
1847 elm_coords_finger_size_adjust(int times_w,
1852 if ((w) && (*w < (_elm_config->finger_size * times_w)))
1853 *w = _elm_config->finger_size * times_w;
1854 if ((h) && (*h < (_elm_config->finger_size * times_h)))
1855 *h = _elm_config->finger_size * times_h;
1859 * @defgroup Caches Caches
1862 * These are functions which let one fine-tune some cache values for
1863 * Elementary applications, thus allowing for performance adjustments.
1867 * Flush all caches & dump all data that can be to lean down to use
1878 EINA_LIST_FOREACH(_elm_win_list, l, obj)
1880 Evas *e = evas_object_evas_get(obj);
1881 edje_file_cache_flush();
1882 edje_collection_cache_flush();
1884 evas_image_cache_flush(e);
1885 evas_font_cache_flush(e);
1886 evas_render_dump(e);
1891 * Get the configured cache flush interval time
1893 * This gets the globally configured cache flush interval time, in
1896 * @return The cache flush interval time
1899 * @see elm_all_flush()
1902 elm_cache_flush_interval_get(void)
1904 return _elm_config->cache_flush_poll_interval;
1908 * Set the configured cache flush interval time
1910 * This sets the globally configured cache flush interval time, in ticks
1912 * @param size The cache flush interval time
1915 * @see elm_all_flush()
1918 elm_cache_flush_interval_set(int size)
1920 if (_elm_config->cache_flush_poll_interval == size) return;
1921 _elm_config->cache_flush_poll_interval = size;
1927 * Set the configured cache flush interval time for all applications on the
1930 * This sets the globally configured cache flush interval time -- in ticks
1931 * -- for all applications on the display.
1933 * @param size The cache flush interval time
1937 elm_cache_flush_interval_all_set(int size)
1939 #ifdef HAVE_ELEMENTARY_X
1940 static Ecore_X_Atom atom = 0;
1941 unsigned int size_i = (unsigned int)size;
1943 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_CACHE_FLUSH_INTERVAL");
1944 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
1950 * Get the configured cache flush enabled state
1952 * This gets the globally configured cache flush state - if it is enabled
1953 * or not. When cache flushing is enabled, elementary will regularly
1954 * (see elm_cache_flush_interval_get() ) flush caches and dump data out of
1955 * memory and allow usage to re-seed caches and data in memory where it
1956 * can do so. An idle application will thus minimise its memory usage as
1957 * data will be freed from memory and not be re-loaded as it is idle and
1958 * not rendering or doing anything graphically right now.
1960 * @return The cache flush state
1963 * @see elm_all_flush()
1966 elm_cache_flush_enmabled_get(void)
1968 return _elm_config->cache_flush_enable;
1972 * Set the configured cache flush enabled state
1974 * This sets the globally configured cache flush enabled state
1976 * @param size The cache flush enabled state
1979 * @see elm_all_flush()
1982 elm_cache_flush_enabled_set(Eina_Bool enabled)
1984 enabled = !!enabled;
1985 if (_elm_config->cache_flush_enable == enabled) return;
1986 _elm_config->cache_flush_enable = enabled;
1992 * Set the configured cache flush enabled state for all applications on the
1995 * This sets the globally configured cache flush enabled state for all
1996 * applications on the display.
1998 * @param size The cache flush enabled state
2002 elm_cache_flush_enabled_all_set(Eina_Bool enabled)
2004 #ifdef HAVE_ELEMENTARY_X
2005 static Ecore_X_Atom atom = 0;
2006 unsigned int enabled_i = (unsigned int)enabled;
2008 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_CACHE_FLUSH_ENABLE");
2009 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2010 atom, &enabled_i, 1);
2015 * Get the configured font cache size
2017 * This gets the globally configured font cache size, in bytes
2019 * @return The font cache size
2023 elm_font_cache_get(void)
2025 return _elm_config->font_cache;
2029 * Set the configured font cache size
2031 * This sets the globally configured font cache size, in bytes
2033 * @param size The font cache size
2037 elm_font_cache_set(int size)
2039 if (_elm_config->font_cache == size) return;
2040 _elm_config->font_cache = size;
2046 * Set the configured font cache size for all applications on the
2049 * This sets the globally configured font cache size -- in bytes
2050 * -- for all applications on the display.
2052 * @param size The font cache size
2056 elm_font_cache_all_set(int size)
2058 #ifdef HAVE_ELEMENTARY_X
2059 static Ecore_X_Atom atom = 0;
2060 unsigned int size_i = (unsigned int)size;
2062 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_FONT_CACHE");
2063 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2069 * Get the configured image cache size
2071 * This gets the globally configured image cache size, in bytes
2073 * @return The image cache size
2077 elm_image_cache_get(void)
2079 return _elm_config->image_cache;
2083 * Set the configured image cache size
2085 * This sets the globally configured image cache size, in bytes
2087 * @param size The image cache size
2091 elm_image_cache_set(int size)
2093 if (_elm_config->image_cache == size) return;
2094 _elm_config->image_cache = size;
2100 * Set the configured image cache size for all applications on the
2103 * This sets the globally configured image cache size -- in bytes
2104 * -- for all applications on the display.
2106 * @param size The image cache size
2110 elm_image_cache_all_set(int size)
2112 #ifdef HAVE_ELEMENTARY_X
2113 static Ecore_X_Atom atom = 0;
2114 unsigned int size_i = (unsigned int)size;
2116 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_IMAGE_CACHE");
2117 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2123 * Get the configured edje file cache size.
2125 * This gets the globally configured edje file cache size, in number
2128 * @return The edje file cache size
2132 elm_edje_file_cache_get(void)
2134 return _elm_config->edje_cache;
2138 * Set the configured edje file cache size
2140 * This sets the globally configured edje file cache size, in number
2143 * @param size The edje file cache size
2147 elm_edje_file_cache_set(int size)
2149 if (_elm_config->edje_cache == size) return;
2150 _elm_config->edje_cache = size;
2156 * Set the configured edje file cache size for all applications on the
2159 * This sets the globally configured edje file cache size -- in number
2160 * of files -- for all applications on the display.
2162 * @param size The edje file cache size
2166 elm_edje_file_cache_all_set(int size)
2168 #ifdef HAVE_ELEMENTARY_X
2169 static Ecore_X_Atom atom = 0;
2170 unsigned int size_i = (unsigned int)size;
2172 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_EDJE_FILE_CACHE");
2173 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2179 * Get the configured edje collections (groups) cache size.
2181 * This gets the globally configured edje collections cache size, in
2182 * number of collections.
2184 * @return The edje collections cache size
2188 elm_edje_collection_cache_get(void)
2190 return _elm_config->edje_collection_cache;
2194 * Set the configured edje collections (groups) cache size
2196 * This sets the globally configured edje collections cache size, in
2197 * number of collections.
2199 * @param size The edje collections cache size
2203 elm_edje_collection_cache_set(int size)
2205 if (_elm_config->edje_collection_cache == size) return;
2206 _elm_config->edje_collection_cache = size;
2212 * Set the configured edje collections (groups) cache size for all
2213 * applications on the display
2215 * This sets the globally configured edje collections cache size -- in
2216 * number of collections -- for all applications on the display.
2218 * @param size The edje collections cache size
2222 elm_edje_collection_cache_all_set(int size)
2224 #ifdef HAVE_ELEMENTARY_X
2225 static Ecore_X_Atom atom = 0;
2226 unsigned int size_i = (unsigned int)size;
2228 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_EDJE_COLLECTION_CACHE");
2229 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2235 * @defgroup Focus Focus
2238 * Objects have focus. This is what determines where the keyboard input goes to
2239 * within the application window.
2243 * Get the focus of the object
2245 * This gets the focused property of the object.
2247 * @param obj The object
2248 * @return 1 if the object is focused, 0 if not.
2252 elm_object_focus_get(const Evas_Object *obj)
2254 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
2255 return elm_widget_focus_get(obj);
2259 * Set the focus to the object
2261 * This sets the focus target for keyboard input to be the object indicated.
2263 * @param obj The object
2267 elm_object_focus(Evas_Object *obj)
2269 EINA_SAFETY_ON_NULL_RETURN(obj);
2270 if (elm_widget_focus_get(obj))
2273 elm_widget_focus_cycle(obj, ELM_FOCUS_NEXT);
2277 * Remove the focus from the object
2279 * This removes the focus target for keyboard input from be the object
2282 * @param obj The object
2286 elm_object_unfocus(Evas_Object *obj)
2288 EINA_SAFETY_ON_NULL_RETURN(obj);
2289 if (!elm_widget_can_focus_get(obj)) return;
2290 elm_widget_focused_object_clear(obj);
2294 * Set the ability for the object to focus
2296 * This sets the ability for the object to be able to get keyboard focus or
2297 * not. By default all objects are able to be focused.
2299 * @param obj The object
2300 * @param enable 1 if the object can be focused, 0 if not
2304 elm_object_focus_allow_set(Evas_Object *obj,
2307 EINA_SAFETY_ON_NULL_RETURN(obj);
2308 elm_widget_can_focus_set(obj, enable);
2312 * Get the ability for the object to focus
2314 * This gets the ability for the object to be able to get keyboard focus or
2315 * not. By default all objects are able to be focused.
2317 * @param obj The object
2318 * @return 1 if the object is allowed to be focused, 0 if not.
2322 elm_object_focus_allow_get(const Evas_Object *obj)
2324 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
2325 return (elm_widget_can_focus_get(obj)) || (elm_widget_child_can_focus_get(obj));
2329 * Set custom focus chain.
2331 * This function i set one new and overwrite any previous custom focus chain
2332 * with the list of objects. The previous list will be deleted and this list
2333 * will be managed. After setted, don't modity it.
2335 * @note On focus cycle, only will be evaluated children of this container.
2337 * @param obj The container object
2338 * @param objs Chain of objects to pass focus
2342 elm_object_focus_custom_chain_set(Evas_Object *obj,
2345 EINA_SAFETY_ON_NULL_RETURN(obj);
2346 elm_widget_focus_custom_chain_set(obj, objs);
2350 * Unset custom focus chain
2352 * @param obj The container object
2356 elm_object_focus_custom_chain_unset(Evas_Object *obj)
2358 EINA_SAFETY_ON_NULL_RETURN(obj);
2359 elm_widget_focus_custom_chain_unset(obj);
2363 * Get custom focus chain
2365 * @param obj The container object
2368 EAPI const Eina_List *
2369 elm_object_focus_custom_chain_get(const Evas_Object *obj)
2371 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
2372 return elm_widget_focus_custom_chain_get(obj);
2376 * Append object to custom focus chain.
2378 * @note If relative_child equal to NULL or not in custom chain, the object
2379 * will be added in end.
2381 * @note On focus cycle, only will be evaluated children of this container.
2383 * @param obj The container object
2384 * @param child The child to be added in custom chain
2385 * @param relative_child The relative object to position the child
2389 elm_object_focus_custom_chain_append(Evas_Object *obj,
2391 Evas_Object *relative_child)
2393 EINA_SAFETY_ON_NULL_RETURN(obj);
2394 EINA_SAFETY_ON_NULL_RETURN(child);
2395 elm_widget_focus_custom_chain_append(obj, child, relative_child);
2399 * Prepend object to custom focus chain.
2401 * @note If relative_child equal to NULL or not in custom chain, the object
2402 * will be added in begin.
2404 * @note On focus cycle, only will be evaluated children of this container.
2406 * @param obj The container object
2407 * @param child The child to be added in custom chain
2408 * @param relative_child The relative object to position the child
2412 elm_object_focus_custom_chain_prepend(Evas_Object *obj,
2414 Evas_Object *relative_child)
2416 EINA_SAFETY_ON_NULL_RETURN(obj);
2417 EINA_SAFETY_ON_NULL_RETURN(child);
2418 elm_widget_focus_custom_chain_prepend(obj, child, relative_child);
2422 * Give focus to next object in object tree.
2424 * Give focus to next object in focus chain of one object sub-tree.
2425 * If the last object of chain already have focus, the focus will go to the
2426 * first object of chain.
2428 * @param obj The object root of sub-tree
2429 * @param dir Direction to cycle the focus
2434 elm_object_focus_cycle(Evas_Object *obj,
2435 Elm_Focus_Direction dir)
2437 EINA_SAFETY_ON_NULL_RETURN(obj);
2438 elm_widget_focus_cycle(obj, dir);
2442 * Give focus to near object in one direction.
2444 * Give focus to near object in direction of one object.
2445 * If none focusable object in given direction, the focus will not change.
2447 * @param obj The reference object
2448 * @param x Horizontal component of direction to focus
2449 * @param y Vertical component of direction to focus
2454 elm_object_focus_direction_go(Evas_Object *obj,
2458 EINA_SAFETY_ON_NULL_RETURN(obj);
2459 elm_widget_focus_direction_go(obj, x, y);
2463 * Get the enable status of the focus highlight
2465 * This gets whether the highlight on focused objects is enabled or not
2469 elm_focus_highlight_enabled_get(void)
2471 return _elm_config->focus_highlight_enable;
2475 * Set the enable status of the focus highlight
2477 * Set whether to show or not the highlight on focused objects
2478 * @param enable Enable highlight if EINA_TRUE, disable otherwise
2482 elm_focus_highlight_enabled_set(Eina_Bool enable)
2484 _elm_config->focus_highlight_enable = !!enable;
2488 * Get the enable status of the highlight animation
2490 * Get whether the focus highlight, if enabled, will animate its switch from
2491 * one object to the next
2495 elm_focus_highlight_animate_get(void)
2497 return _elm_config->focus_highlight_animate;
2501 * Set the enable status of the highlight animation
2503 * Set whether the focus highlight, if enabled, will animate its switch from
2504 * one object to the next
2505 * @param animate Enable animation if EINA_TRUE, disable otherwise
2509 elm_focus_highlight_animate_set(Eina_Bool animate)
2511 _elm_config->focus_highlight_animate = !!animate;
2515 * @defgroup Scrolling Scrolling
2518 * These are functions setting how scrollable views in Elementary
2519 * widgets should behave on user interaction.
2523 * Get whether scrollers should bounce when they reach their
2524 * viewport's edge during a scroll.
2526 * @return the thumb scroll bouncing state
2528 * This is the default behavior for touch screens, in general.
2529 * @ingroup Scrolling
2532 elm_scroll_bounce_enabled_get(void)
2534 return _elm_config->thumbscroll_bounce_enable;
2538 * Set whether scrollers should bounce when they reach their
2539 * viewport's edge during a scroll.
2541 * @param enabled the thumb scroll bouncing state
2543 * @see elm_thumbscroll_bounce_enabled_get()
2544 * @ingroup Scrolling
2547 elm_scroll_bounce_enabled_set(Eina_Bool enabled)
2549 _elm_config->thumbscroll_bounce_enable = enabled;
2553 * Set whether scrollers should bounce when they reach their
2554 * viewport's edge during a scroll, for all Elementary application
2557 * @param enabled the thumb scroll bouncing state
2559 * @see elm_thumbscroll_bounce_enabled_get()
2560 * @ingroup Scrolling
2563 elm_scroll_bounce_enabled_all_set(Eina_Bool enabled)
2565 #ifdef HAVE_ELEMENTARY_X
2566 static Ecore_X_Atom atom = 0;
2567 unsigned int bounce_enable_i = (unsigned int)enabled;
2570 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BOUNCE_ENABLE");
2571 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2572 atom, &bounce_enable_i, 1);
2577 * Get the amount of inertia a scroller will impose at bounce
2580 * @return the thumb scroll bounce friction
2582 * @ingroup Scrolling
2585 elm_scroll_bounce_friction_get(void)
2587 return _elm_config->thumbscroll_bounce_friction;
2591 * Set the amount of inertia a scroller will impose at bounce
2594 * @param friction the thumb scroll bounce friction
2596 * @see elm_thumbscroll_bounce_friction_get()
2597 * @ingroup Scrolling
2600 elm_scroll_bounce_friction_set(double friction)
2602 _elm_config->thumbscroll_bounce_friction = friction;
2606 * Set the amount of inertia a scroller will impose at bounce
2607 * animations, for all Elementary application windows.
2609 * @param friction the thumb scroll bounce friction
2611 * @see elm_thumbscroll_bounce_friction_get()
2612 * @ingroup Scrolling
2615 elm_scroll_bounce_friction_all_set(double friction)
2617 #ifdef HAVE_ELEMENTARY_X
2618 static Ecore_X_Atom atom = 0;
2619 unsigned int bounce_friction_i = (unsigned int)(friction * 1000.0);
2622 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BOUNCE_FRICTION");
2623 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2624 atom, &bounce_friction_i, 1);
2629 * Get the amount of inertia a <b>paged</b> scroller will impose at
2630 * page fitting animations.
2632 * @return the page scroll friction
2634 * @ingroup Scrolling
2637 elm_scroll_page_scroll_friction_get(void)
2639 return _elm_config->page_scroll_friction;
2643 * Set the amount of inertia a <b>paged</b> scroller will impose at
2644 * page fitting animations.
2646 * @param friction the page scroll friction
2648 * @see elm_thumbscroll_page_scroll_friction_get()
2649 * @ingroup Scrolling
2652 elm_scroll_page_scroll_friction_set(double friction)
2654 _elm_config->page_scroll_friction = friction;
2658 * Set the amount of inertia a <b>paged</b> scroller will impose at
2659 * page fitting animations, for all Elementary application windows.
2661 * @param friction the page scroll friction
2663 * @see elm_thumbscroll_page_scroll_friction_get()
2664 * @ingroup Scrolling
2667 elm_scroll_page_scroll_friction_all_set(double friction)
2669 #ifdef HAVE_ELEMENTARY_X
2670 static Ecore_X_Atom atom = 0;
2671 unsigned int page_scroll_friction_i = (unsigned int)(friction * 1000.0);
2674 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_PAGE_SCROLL_FRICTION");
2675 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2676 atom, &page_scroll_friction_i, 1);
2681 * Get the amount of inertia a scroller will impose at region bring
2684 * @return the bring in scroll friction
2686 * @ingroup Scrolling
2689 elm_scroll_bring_in_scroll_friction_get(void)
2691 return _elm_config->bring_in_scroll_friction;
2695 * Set the amount of inertia a scroller will impose at region bring
2698 * @param friction the bring in scroll friction
2700 * @see elm_thumbscroll_bring_in_scroll_friction_get()
2701 * @ingroup Scrolling
2704 elm_scroll_bring_in_scroll_friction_set(double friction)
2706 _elm_config->bring_in_scroll_friction = friction;
2710 * Set the amount of inertia a scroller will impose at region bring
2711 * animations, for all Elementary application windows.
2713 * @param friction the bring in scroll friction
2715 * @see elm_thumbscroll_bring_in_scroll_friction_get()
2716 * @ingroup Scrolling
2719 elm_scroll_bring_in_scroll_friction_all_set(double friction)
2721 #ifdef HAVE_ELEMENTARY_X
2722 static Ecore_X_Atom atom = 0;
2723 unsigned int bring_in_scroll_friction_i = (unsigned int)(friction * 1000.0);
2727 ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BRING_IN_SCROLL_FRICTION");
2728 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2729 atom, &bring_in_scroll_friction_i, 1);
2734 * Get the amount of inertia scrollers will impose at animations
2735 * triggered by Elementary widgets' zooming API.
2737 * @return the zoom friction
2739 * @ingroup Scrolling
2742 elm_scroll_zoom_friction_get(void)
2744 return _elm_config->zoom_friction;
2748 * Set the amount of inertia scrollers will impose at animations
2749 * triggered by Elementary widgets' zooming API.
2751 * @param friction the zoom friction
2753 * @see elm_thumbscroll_zoom_friction_get()
2754 * @ingroup Scrolling
2757 elm_scroll_zoom_friction_set(double friction)
2759 _elm_config->zoom_friction = friction;
2763 * Set the amount of inertia scrollers will impose at animations
2764 * triggered by Elementary widgets' zooming API, for all Elementary
2765 * application windows.
2767 * @param friction the zoom friction
2769 * @see elm_thumbscroll_zoom_friction_get()
2770 * @ingroup Scrolling
2773 elm_scroll_zoom_friction_all_set(double friction)
2775 #ifdef HAVE_ELEMENTARY_X
2776 static Ecore_X_Atom atom = 0;
2777 unsigned int zoom_friction_i = (unsigned int)(friction * 1000.0);
2780 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_ZOOM_FRICTION");
2781 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2782 atom, &zoom_friction_i, 1);
2787 * Get whether scrollers should be draggable from any point in their
2790 * @return the thumb scroll state
2792 * @note This is the default behavior for touch screens, in general.
2793 * @note All other functions namespaced with "thumbscroll" will only
2794 * have effect if this mode is enabled.
2796 * @ingroup Scrolling
2799 elm_scroll_thumbscroll_enabled_get(void)
2801 return _elm_config->thumbscroll_enable;
2805 * Set whether scrollers should be draggable from any point in their
2808 * @param enabled the thumb scroll state
2810 * @see elm_thumbscroll_enabled_get()
2811 * @ingroup Scrolling
2814 elm_scroll_thumbscroll_enabled_set(Eina_Bool enabled)
2816 _elm_config->thumbscroll_enable = enabled;
2820 * Set whether scrollers should be draggable from any point in their
2821 * views, for all Elementary application windows.
2823 * @param enabled the thumb scroll state
2825 * @see elm_thumbscroll_enabled_get()
2826 * @ingroup Scrolling
2829 elm_scroll_thumbscroll_enabled_all_set(Eina_Bool enabled)
2831 #ifdef HAVE_ELEMENTARY_X
2832 static Ecore_X_Atom atom = 0;
2833 unsigned int ts_enable_i = (unsigned int)enabled;
2835 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_ENABLE");
2836 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2837 atom, &ts_enable_i, 1);
2842 * Get the number of pixels one should travel while dragging a
2843 * scroller's view to actually trigger scrolling.
2845 * @return the thumb scroll threshould
2847 * One would use higher values for touch screens, in general, because
2848 * of their inherent imprecision.
2849 * @ingroup Scrolling
2852 elm_scroll_thumbscroll_threshold_get(void)
2854 return _elm_config->thumbscroll_threshold;
2858 * Set the number of pixels one should travel while dragging a
2859 * scroller's view to actually trigger scrolling.
2861 * @param threshold the thumb scroll threshould
2863 * @see elm_thumbscroll_threshould_get()
2864 * @ingroup Scrolling
2867 elm_scroll_thumbscroll_threshold_set(unsigned int threshold)
2869 _elm_config->thumbscroll_threshold = threshold;
2873 * Set the number of pixels one should travel while dragging a
2874 * scroller's view to actually trigger scrolling, for all Elementary
2875 * application windows.
2877 * @param threshold the thumb scroll threshould
2879 * @see elm_thumbscroll_threshould_get()
2880 * @ingroup Scrolling
2883 elm_scroll_thumbscroll_threshold_all_set(unsigned int threshold)
2885 #ifdef HAVE_ELEMENTARY_X
2886 static Ecore_X_Atom atom = 0;
2887 unsigned int ts_threshold_i = (unsigned int)threshold;
2889 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_THRESHOLD");
2890 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2891 atom, &ts_threshold_i, 1);
2896 * Get the minimum speed of mouse cursor movement which will trigger
2897 * list self scrolling animation after a mouse up event
2900 * @return the thumb scroll momentum threshould
2902 * @ingroup Scrolling
2905 elm_scroll_thumbscroll_momentum_threshold_get(void)
2907 return _elm_config->thumbscroll_momentum_threshold;
2911 * Set the minimum speed of mouse cursor movement which will trigger
2912 * list self scrolling animation after a mouse up event
2915 * @param threshold the thumb scroll momentum threshould
2917 * @see elm_thumbscroll_momentum_threshould_get()
2918 * @ingroup Scrolling
2921 elm_scroll_thumbscroll_momentum_threshold_set(double threshold)
2923 _elm_config->thumbscroll_momentum_threshold = threshold;
2927 * Set the minimum speed of mouse cursor movement which will trigger
2928 * list self scrolling animation after a mouse up event
2929 * (pixels/second), for all Elementary application windows.
2931 * @param threshold the thumb scroll momentum threshould
2933 * @see elm_thumbscroll_momentum_threshould_get()
2934 * @ingroup Scrolling
2937 elm_scroll_thumbscroll_momentum_threshold_all_set(double threshold)
2939 #ifdef HAVE_ELEMENTARY_X
2940 static Ecore_X_Atom atom = 0;
2941 unsigned int ts_momentum_threshold_i = (unsigned int)(threshold * 1000.0);
2944 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_MOMENTUM_THRESHOLD");
2945 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2946 atom, &ts_momentum_threshold_i, 1);
2951 * Get the amount of inertia a scroller will impose at self scrolling
2954 * @return the thumb scroll friction
2956 * @ingroup Scrolling
2959 elm_scroll_thumbscroll_friction_get(void)
2961 return _elm_config->thumbscroll_friction;
2965 * Set the amount of inertia a scroller will impose at self scrolling
2968 * @param friction the thumb scroll friction
2970 * @see elm_thumbscroll_friction_get()
2971 * @ingroup Scrolling
2974 elm_scroll_thumbscroll_friction_set(double friction)
2976 _elm_config->thumbscroll_friction = friction;
2980 * Set the amount of inertia a scroller will impose at self scrolling
2981 * animations, for all Elementary application windows.
2983 * @param friction the thumb scroll friction
2985 * @see elm_thumbscroll_friction_get()
2986 * @ingroup Scrolling
2989 elm_scroll_thumbscroll_friction_all_set(double friction)
2991 #ifdef HAVE_ELEMENTARY_X
2992 static Ecore_X_Atom atom = 0;
2993 unsigned int ts_friction_i = (unsigned int)(friction * 1000.0);
2995 if (!atom) atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_FRICTION");
2996 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
2997 atom, &ts_friction_i, 1);
3002 * Get the amount of lag between your actual mouse cursor dragging
3003 * movement and a scroller's view movement itself, while pushing it
3004 * into bounce state manually.
3006 * @return the thumb scroll border friction
3008 * @ingroup Scrolling
3011 elm_scroll_thumbscroll_border_friction_get(void)
3013 return _elm_config->thumbscroll_border_friction;
3017 * Set the amount of lag between your actual mouse cursor dragging
3018 * movement and a scroller's view movement itself, while pushing it
3019 * into bounce state manually.
3021 * @param friction the thumb scroll border friction. @c 0.0 for
3022 * perfect synchrony between two movements, @c 1.0 for maximum
3025 * @see elm_thumbscroll_border_friction_get()
3026 * @note parameter value will get bound to 0.0 - 1.0 interval, always
3028 * @ingroup Scrolling
3031 elm_scroll_thumbscroll_border_friction_set(double friction)
3039 _elm_config->thumbscroll_friction = friction;
3043 * Set the amount of lag between your actual mouse cursor dragging
3044 * movement and a scroller's view movement itself, while pushing it
3045 * into bounce state manually, for all Elementary application windows.
3047 * @param friction the thumb scroll border friction. @c 0.0 for
3048 * perfect synchrony between two movements, @c 1.0 for maximum
3051 * @see elm_thumbscroll_border_friction_get()
3052 * @note parameter value will get bound to 0.0 - 1.0 interval, always
3054 * @ingroup Scrolling
3057 elm_scroll_thumbscroll_border_friction_all_set(double friction)
3065 #ifdef HAVE_ELEMENTARY_X
3066 static Ecore_X_Atom atom = 0;
3067 unsigned int border_friction_i = (unsigned int)(friction * 1000.0);
3070 atom = ecore_x_atom_get("ENLIGHTENMENT_THUMBSCROLL_BORDER_FRICTION");
3071 ecore_x_window_prop_card32_set(ecore_x_window_root_first_get(),
3072 atom, &border_friction_i, 1);
3077 * @defgroup Scrollhints Scrollhints
3080 * Objects when inside a scroller can scroll, but this may not always be
3081 * desirable in certain situations. This allows an object to hint to itself
3082 * and parents to "not scroll" in one of 2 ways.
3084 * 1. To hold on scrolling. This means just flicking and dragging may no
3085 * longer scroll, but pressing/dragging near an edge of the scroller will
3086 * still scroll. This is automastically used by the entry object when
3088 * 2. To totally freeze scrolling. This means it stops. until popped/released.
3092 * Push the scroll hold by 1
3094 * This increments the scroll hold count by one. If it is more than 0 it will
3095 * take effect on the parents of the indicated object.
3097 * @param obj The object
3098 * @ingroup Scrollhints
3101 elm_object_scroll_hold_push(Evas_Object *obj)
3103 EINA_SAFETY_ON_NULL_RETURN(obj);
3104 elm_widget_scroll_hold_push(obj);
3108 * Pop the scroll hold by 1
3110 * This decrements the scroll hold count by one. If it is more than 0 it will
3111 * take effect on the parents of the indicated object.
3113 * @param obj The object
3114 * @ingroup Scrollhints
3117 elm_object_scroll_hold_pop(Evas_Object *obj)
3119 EINA_SAFETY_ON_NULL_RETURN(obj);
3120 elm_widget_scroll_hold_pop(obj);
3124 * Push the scroll freeze by 1
3126 * This increments the scroll freeze count by one. If it is more than 0 it will
3127 * take effect on the parents of the indicated object.
3129 * @param obj The object
3130 * @ingroup Scrollhints
3133 elm_object_scroll_freeze_push(Evas_Object *obj)
3135 EINA_SAFETY_ON_NULL_RETURN(obj);
3136 elm_widget_scroll_freeze_push(obj);
3140 * Lock the scrolling of the given widget (and thus all parents)
3142 * This locks the given object from scrolling in the X axis (and implicitly
3143 * also locks all parent scrollers too from doing the same).
3145 * @param obj The object
3146 * @param lock The lock state (1 == locked, 0 == unlocked)
3147 * @ingroup Scrollhints
3150 elm_object_scroll_lock_x_set(Evas_Object *obj,
3153 EINA_SAFETY_ON_NULL_RETURN(obj);
3154 elm_widget_drag_lock_x_set(obj, lock);
3158 * Lock the scrolling of the given widget (and thus all parents)
3160 * This locks the given object from scrolling in the Y axis (and implicitly
3161 * also locks all parent scrollers too from doing the same).
3163 * @param obj The object
3164 * @param lock The lock state (1 == locked, 0 == unlocked)
3165 * @ingroup Scrollhints
3168 elm_object_scroll_lock_y_set(Evas_Object *obj,
3171 EINA_SAFETY_ON_NULL_RETURN(obj);
3172 elm_widget_drag_lock_y_set(obj, lock);
3176 * Get the scrolling lock of the given widget
3178 * This gets the lock for X axis scrolling.
3180 * @param obj The object
3181 * @ingroup Scrollhints
3184 elm_object_scroll_lock_x_get(const Evas_Object *obj)
3186 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3187 return elm_widget_drag_lock_x_get(obj);
3191 * Get the scrolling lock of the given widget
3193 * This gets the lock for X axis scrolling.
3195 * @param obj The object
3196 * @ingroup Scrollhints
3199 elm_object_scroll_lock_y_get(const Evas_Object *obj)
3201 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3202 return elm_widget_drag_lock_y_get(obj);
3206 * Pop the scroll freeze by 1
3208 * This decrements the scroll freeze count by one. If it is more than 0 it will
3209 * take effect on the parents of the indicated object.
3211 * @param obj The object
3212 * @ingroup Scrollhints
3215 elm_object_scroll_freeze_pop(Evas_Object *obj)
3217 EINA_SAFETY_ON_NULL_RETURN(obj);
3218 elm_widget_scroll_freeze_pop(obj);
3222 * @defgroup WidgetNavigation Widget Tree Navigation.
3225 * How to check if an Evas Object is an Elementary widget? How to get
3226 * the first elementary widget that is parent of the given object?
3227 * These are all covered in widget tree navigation.
3231 * Check if the given Evas Object is an Elementary widget.
3233 * @param obj the object to query.
3234 * @return @c EINA_TRUE if it is an elementary widget variant,
3235 * @c EINA_FALSE otherwise
3236 * @ingroup WidgetNavigation
3239 elm_object_widget_check(const Evas_Object *obj)
3241 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, EINA_FALSE);
3242 return elm_widget_is(obj);
3246 * Get the first parent of the given object that is an Elementary widget.
3248 * @param obj the object to query.
3249 * @return the parent object that is an Elementary widget, or @c NULL
3250 * if no parent is, or no parents at all.
3251 * @ingroup WidgetNavigation
3254 elm_object_parent_widget_get(const Evas_Object *obj)
3256 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3257 return elm_widget_parent_widget_get(obj);
3261 * Get the top level parent of an Elementary widget.
3263 * @param obj The object to query.
3264 * @return The top level Elementary widget, or @c NULL if parent cannot be
3266 * @ingroup WidgetNavigation
3269 elm_object_top_widget_get(const Evas_Object *obj)
3271 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3272 return elm_widget_top_get(obj);
3276 * Get the string that represents this Elementary widget.
3278 * @note Elementary is weird and exposes itself as a single
3279 * Evas_Object_Smart_Class of type "elm_widget", so
3280 * evas_object_type_get() always return that, making debug and
3281 * language bindings hard. This function tries to mitigate this
3282 * problem, but the solution is to change Elementary to use
3283 * proper inheritance.
3285 * @param obj the object to query.
3286 * @return Elementary widget name, or @c NULL if not a valid widget.
3287 * @ingroup WidgetNavigation
3290 elm_object_widget_type_get(const Evas_Object *obj)
3292 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3293 return elm_widget_type_get(obj);
3297 * Send a signal to the widget edje object.
3299 * This function sends a signal to the edje object of the obj. An edje program
3300 * can respond to a signal by specifying matching 'signal' and
3303 * @param obj The object
3304 * @param emission The signal's name.
3305 * @param source The signal's source.
3309 elm_object_signal_emit(Evas_Object *obj,
3310 const char *emission,
3313 EINA_SAFETY_ON_NULL_RETURN(obj);
3314 elm_widget_signal_emit(obj, emission, source);
3318 * Add a callback for a signal emitted by widget edje object.
3320 * This function connects a callback function to a signal emitted by the
3321 * edje object of the obj.
3322 * Globs can occur in either the emission or source name.
3324 * @param obj The object
3325 * @param emission The signal's name.
3326 * @param source The signal's source.
3327 * @param func The callback function to be executed when the signal is
3329 * @param data A pointer to data to pass in to the callback function.
3333 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)
3335 EINA_SAFETY_ON_NULL_RETURN(obj);
3336 EINA_SAFETY_ON_NULL_RETURN(func);
3337 elm_widget_signal_callback_add(obj, emission, source, func, data);
3341 * Remove a signal-triggered callback from an widget edje object.
3343 * This function removes a callback, previoulsy attached to a signal emitted
3344 * by the edje object of the obj.
3345 * The parameters emission, source and func must match exactly those passed to
3346 * a previous call to elm_object_signal_callback_add(). The data pointer that
3347 * was passed to this call will be returned.
3349 * @param obj The object
3350 * @param emission The signal's name.
3351 * @param source The signal's source.
3352 * @param func The callback function to be executed when the signal is
3354 * @return The data pointer
3358 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))
3360 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3361 EINA_SAFETY_ON_NULL_RETURN_VAL(func, NULL);
3362 return elm_widget_signal_callback_del(obj, emission, source, func);
3366 * Add a callback for a event emitted by widget or their children.
3368 * This function connects a callback function to any key_down key_up event
3369 * emitted by the @p obj or their children.
3370 * This only will be called if no other callback has consumed the event.
3371 * If you want consume the event, and no other get it, func should return
3372 * EINA_TRUE and put EVAS_EVENT_FLAG_ON_HOLD in event_flags.
3374 * @warning Accept duplicated callback addition.
3376 * @param obj The object
3377 * @param func The callback function to be executed when the event is
3379 * @param data Data to pass in to the callback function.
3383 elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data)
3385 EINA_SAFETY_ON_NULL_RETURN(obj);
3386 EINA_SAFETY_ON_NULL_RETURN(func);
3387 elm_widget_event_callback_add(obj, func, data);
3391 * Remove a event callback from an widget.
3393 * This function removes a callback, previoulsy attached to event emission
3395 * The parameters func and data must match exactly those passed to
3396 * a previous call to elm_object_event_callback_add(). The data pointer that
3397 * was passed to this call will be returned.
3399 * @param obj The object
3400 * @param func The callback function to be executed when the event is
3402 * @param data Data to pass in to the callback function.
3403 * @return The data pointer
3407 elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data)
3409 EINA_SAFETY_ON_NULL_RETURN_VAL(obj, NULL);
3410 EINA_SAFETY_ON_NULL_RETURN_VAL(func, NULL);
3411 return elm_widget_event_callback_del(obj, func, data);
3416 * @defgroup Debug Debug
3421 * Print Tree object hierarchy in stdout
3423 * @param obj The root object
3427 elm_object_tree_dump(const Evas_Object *top)
3430 elm_widget_tree_dump(top);
3438 * Print Elm Objects tree hierarchy in file as dot(graphviz) syntax.
3440 * @param obj The root object
3441 * @param file The path of output file
3445 elm_object_tree_dot_dump(const Evas_Object *top,
3449 FILE *f = fopen(file, "w");
3450 elm_widget_tree_dot_dump(top, f);
3460 * Set the duration for occuring long press event.
3462 * @param lonpress_timeout Timeout for long press event
3463 * @ingroup Longpress
3466 elm_longpress_timeout_set(double longpress_timeout)
3468 _elm_config->longpress_timeout = longpress_timeout;
3472 * Get the duration for occuring long press event.
3474 * @return Timeout for long press event
3475 * @ingroup Longpress
3478 elm_longpress_timeout_get(void)
3480 return _elm_config->longpress_timeout;