/**
@mainpage Elementary
@image html elementary.png
-@version @PACKAGE_VERSION@
+@version 0.7.0
@date 2008-2011
@section intro What is Elementary?
It is meant to make the programmers work almost brainless but give them lots
of flexibility.
-License: LGPL v2 (see COPYING in the base of Elementary's source). This
-applies to all files in the source here.
+@li @ref Start - Go here to quickly get started with writing Apps
-Acknowledgements: There is a lot that goes into making a widget set, and
-they don't happen out of nothing. It's like trying to make everyone
-everywhere happy, regardless of age, gender, race or nationality - and
-that is really tough. So thanks to people and organisations behind this,
-as listed in the @ref authors page.
+@section organization Organization
+One can divide Elemementary into three main groups:
+@li @ref infralist - These are modules that deal with Elementary as a whole.
+@li @ref widgetslist - These are the widgets you'll compose your UI out of.
+@li @ref containerslist - These are the containers in which the widgets will be
+ layouted.
+
+@section license License
+
+LGPL v2 (see COPYING in the base of Elementary's source). This applies to
+all files in the source tree.
+
+@section ack Acknowledgements
+There is a lot that goes into making a widget set, and they don't happen out of
+nothing. It's like trying to make everyone everywhere happy, regardless of age,
+gender, race or nationality - and that is really tough. So thanks to people and
+organisations behind this, as listed in the @ref authors page.
+*/
+
+
+/**
+ * @defgroup Start Getting Started
+ *
+ * To write an Elementary app, you can get started with the following:
+ *
+@code
+#include <Elementary.h>
+EAPI_MAIN int
+elm_main(int argc, char **argv)
+{
+ // create window(s) here and do any application init
+ elm_run(); // run main loop
+ elm_shutdown(); // after mainloop finishes running, shutdown
+ return 0; // exit 0 for exit code
+}
+ELM_MAIN()
+@endcode
+ *
+ * To use autotools (which helps in many ways in the long run, like being able
+ * to immediately create releases of your software directly from your tree
+ * and ensure everything needed to build it is there) you will need a
+ * configure.ac, Makefile.am and autogen.sh file.
+ *
+ * configure.ac:
+ *
@verbatim
-Pants
+AC_INIT(myapp, 0.0.0, myname@mydomain.com)
+AC_PREREQ(2.52)
+AC_CONFIG_SRCDIR(configure.ac)
+AM_CONFIG_HEADER(config.h)
+AC_PROG_CC
+AM_INIT_AUTOMAKE(1.6 dist-bzip2)
+PKG_CHECK_MODULES([ELEMENTARY], elementary)
+AC_OUTPUT(Makefile)
@endverbatim
-*/
+ *
+ * Makefile.am:
+ *
+@verbatim
+AUTOMAKE_OPTIONS = 1.4 foreign
+MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.h.in configure depcomp install-sh missing
+
+INCLUDES = -I$(top_srcdir)
+
+bin_PROGRAMS = myapp
+
+myapp_SOURCES = main.c
+myapp_LDADD = @ELEMENTARY_LIBS@
+myapp_CFLAGS = @ELEMENTARY_CFLAGS@
+@endverbatim
+ *
+ * autogen.sh:
+ *
+@verbatim
+#!/bin/sh
+echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS || exit 1
+echo "Running autoheader..." ; autoheader || exit 1
+echo "Running autoconf..." ; autoconf || exit 1
+echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1
+./configure "$@"
+@endverbatim
+ *
+ * To generate all the things needed to bootstrap just run:
+ *
+@verbatim
+./autogen.sh
+@endverbatim
+ *
+ * This will generate Makefile.in's, the confgure script and everything else.
+ * After this it works like all normal autotools projects:
+@verbatim
+./configure
+make
+sudo make install
+@endverbatim
+ *
+ * Note sudo was assumed to get root permissions, as this would install in
+ * /usr/local which is system-owned. Use any way you like to gain root, or
+ * specify a different prefix with configure:
+ *
+@verbatim
+./confiugre --prefix=$HOME/mysoftware
+@endverbatim
+ *
+ * Also remember that autotools buys you some useful commands like:
+@verbatim
+make uninstall
+@endverbatim
+ *
+ * This uninstalls the software after it was installed with "make install".
+ * It is very useful to clear up what you built if you wish to clean the
+ * system.
+ *
+@verbatim
+make distcheck
+@endverbatim
+ *
+ * This firstly checks if your build tree is "clean" and ready for
+ * distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is
+ * ready to upload and distribute to the world, that contains the generated
+ * Makefile.in's and configure script. The users do not need to run
+ * autogen.sh - just configure and on. They don't need autotools installed.
+ * This tarball also builds cleanly, has all the sources it needs to build
+ * included (that is sources for your application, not libraries it depends
+ * on like Elementary). It builds cleanly in a buildroot and does not
+ * contain any files that are temporarily generated like binaries and other
+ * build-generated files, so the tarball is clean, and no need to worry
+ * about cleaning up your tree before packaging.
+ *
+@verbatim
+make clean
+@endverbatim
+ *
+ * This cleans up all build files (binaries, objects etc.) from the tree.
+ *
+@verbatim
+make distclean
+@endverbatim
+ *
+ * This cleans out all files from the build and from configure's output too.
+ *
+@verbatim
+make maintainer-clean
+@endverbatim
+ *
+ * This deletes all the files autogen.sh will produce so the tree is clean
+ * to be put into a revision-control system (like CVS, SVN or GIT for example).
+ *
+ * There is a more advanced way of making use of the quicklaunch infrastructure
+ * in Elementary (which will not be covered here due to its more advanced
+ * nature).
+ *
+ * Now let's actually create an interactive "Hello World" gui that you can
+ * click the ok button to exit. It's more code because this now does something
+ * much more significant, but it's still very simple:
+ *
+@code
+#include <Elementary.h>
+
+static void
+on_done(void *data, Evas_Object *obj, void *event_info)
+{
+ // quit the mainloop (elm_run function will return)
+ elm_exit();
+}
+
+EAPI_MAIN int
+elm_main(int argc, char **argv)
+{
+ Evas_Object *win, *bg, *box, *lab, *btn;
+
+ // new window - do the usual and give it a name, title and delete handler
+ win = elm_win_add(NULL, "hello", ELM_WIN_BASIC);
+ elm_win_title_set(win, "Hello");
+ // when the user clicks "close" on a window there is a request to delete
+ evas_object_smart_callback_add(win, "delete,request", on_done, NULL);
+
+ // add a standard bg
+ bg = elm_bg_add(win);
+ // add object as a resize object for the window (controls window minimum
+ // size as well as gets resized if window is resized)
+ elm_win_resize_object_add(win, bg);
+ evas_object_show(bg);
+
+ // add a box object - default is vertical. a box holds children in a row,
+ // either horizontally or vertically. nothing more.
+ box = elm_box_add(win);
+ // make the box hotizontal
+ elm_box_horizontal_set(box, EINA_TRUE);
+ // add object as a resize object for the window (controls window minimum
+ // size as well as gets resized if window is resized)
+ elm_win_resize_object_add(win, box);
+ evas_object_show(box);
+
+ // add a label widget, set the text and put it in the pad frame
+ lab = elm_label_add(win);
+ // set default text of the label
+ elm_object_text_set(lab, "Hello out there world!");
+ // pack the label at the end of the box
+ elm_box_pack_end(box, lab);
+ evas_object_show(lab);
+
+ // add an ok button
+ btn = elm_button_add(win);
+ // set default text of button to "OK"
+ elm_object_text_set(btn, "OK");
+ // pack the button at the end of the box
+ elm_box_pack_end(box, btn);
+ evas_object_show(btn);
+ // call on_done when button is clicked
+ evas_object_smart_callback_add(btn, "clicked", on_done, NULL);
+
+ // now we are done, show the window
+ evas_object_show(win);
+
+ // run the mainloop and process events and callbacks
+ elm_run();
+ return 0;
+}
+ELM_MAIN()
+@endcode
+ *
+ */
/**
@page authors Authors
@author Shinwoo Kim <kimcinoo@@gmail.com>
@author Govindaraju SM <govi.sm@@samsung.com> <govism@@gmail.com>
@author Prince Kumar Dubey <prince.dubey@@samsung.com> <prince.dubey@@gmail.com>
+@author Sung W. Park <sungwoo@gmail.com>
+@author Thierry el Borgi <thierry@substantiel.fr>
+@author Shilpa Singh <shilpa.singh@samsung.com> <shilpasingh.o@gmail.com>
+@author Chanwook Jung <joey.jung@samsung.com>
+@author Hyoyoung Chang <hyoyoung.chang@samsung.com>
+@author Guillaume "Kuri" Friloux <guillaume.friloux@asp64.com>
+@author Kim Yunhan <spbear@gmail.com>
Please contact <enlightenment-devel@lists.sourceforge.net> to get in
contact with the developers and maintainers.
@ELM_EDBUS_DEF@ ELM_EDBUS
@ELM_EFREET_DEF@ ELM_EFREET
@ELM_ETHUMB_DEF@ ELM_ETHUMB
+@ELM_WEB_DEF@ ELM_WEB
@ELM_EMAP_DEF@ ELM_EMAP
@ELM_DEBUG_DEF@ ELM_DEBUG
@ELM_ALLOCA_H_DEF@ ELM_ALLOCA_H
# endif
#endif /* ! _WIN32 */
+#ifdef _WIN32
+# define EAPI_MAIN
+#else
+# define EAPI_MAIN EAPI
+#endif
/* allow usage from c++ */
#ifdef __cplusplus
*/
typedef enum _Elm_Policy
{
- ELM_POLICY_QUIT, /**< under which circunstances the application
+ ELM_POLICY_QUIT, /**< under which circumstances the application
* should quit automatically. @see
* Elm_Policy_Quit.
*/
ELM_WRAP_LAST
} Elm_Wrap_Type;
+ typedef enum
+ {
+ ELM_INPUT_PANEL_LAYOUT_NORMAL, /**< Default layout */
+ ELM_INPUT_PANEL_LAYOUT_NUMBER, /**< Number layout */
+ ELM_INPUT_PANEL_LAYOUT_EMAIL, /**< Email layout */
+ ELM_INPUT_PANEL_LAYOUT_URL, /**< URL layout */
+ ELM_INPUT_PANEL_LAYOUT_PHONENUMBER, /**< Phone Number layout */
+ ELM_INPUT_PANEL_LAYOUT_IP, /**< IP layout */
+ ELM_INPUT_PANEL_LAYOUT_MONTH, /**< Month layout */
+ ELM_INPUT_PANEL_LAYOUT_NUMBERONLY, /**< Number Only layout */
+ ELM_INPUT_PANEL_LAYOUT_INVALID
+ } Elm_Input_Panel_Layout;
+
/**
* @typedef Elm_Object_Item
* An Elementary Object item handle.
* @ingroup General
*/
- typedef struct _Elm_Widget_Item Elm_Object_Item;
+ typedef struct _Elm_Object_Item Elm_Object_Item;
+
/**
* Called back when a widget's tooltip is activated and needs content.
*/
typedef Evas_Object *(*Elm_Tooltip_Item_Content_Cb) (void *data, Evas_Object *obj, Evas_Object *tooltip, void *item);
- typedef Eina_Bool (*Elm_Event_Cb) (void *data, Evas_Object *obj, Evas_Object *src, Evas_Callback_Type type, void *event_info);
+ typedef Eina_Bool (*Elm_Event_Cb) (void *data, Evas_Object *obj, Evas_Object *src, Evas_Callback_Type type, void *event_info); /**< Function prototype definition for callbacks on input events happening on Elementary widgets. @a data will receive the user data pointer passed to elm_object_event_callback_add(). @a src will be a pointer to the widget on which the input event took place. @a type will get the type of this event and @a event_info, the struct with details on this event. */
#ifndef ELM_LIB_QUICKLAUNCH
#define ELM_MAIN() int main(int argc, char **argv) {elm_init(argc, argv); return elm_main(argc, argv);} /**< macro to be used after the elm_main() function */
* @return The init counter value.
*
* This function initializes Elementary and increments a counter of
- * the number of calls to it. It returs the new counter's value.
+ * the number of calls to it. It returns the new counter's value.
*
* @warning This call is exported only for use by the @c ELM_MAIN()
* macro. There is no need to use this if you use this macro (which
EAPI Eina_Bool elm_need_efreet(void);
EAPI Eina_Bool elm_need_e_dbus(void);
+
+ /**
+ * This must be called before any other function that handle with
+ * elm_thumb objects or ethumb_client instances.
+ *
+ * @ingroup Thumb
+ */
EAPI Eina_Bool elm_need_ethumb(void);
/**
+ * This must be called before any other function that handle with
+ * elm_web objects or ewk_view instances.
+ *
+ * @ingroup Web
+ */
+ EAPI Eina_Bool elm_need_web(void);
+
+ /**
* Set a new policy's value (for a given policy group/identifier).
*
* @param policy policy identifier, as in @ref Elm_Policy.
* Set a content of an object item
*
* @param it The Elementary object item
- * @param part The content part name to unset (NULL for the default content)
+ * @param part The content part name to set (NULL for the default content)
* @param content The new content of the object item
*
* @note Elementary object items may have many contents
*
* @ingroup General
*/
- EAPI Evas_Object *elm_object_item_content_part_get(const Elm_Object_Item *it, const char *item);
+ EAPI Evas_Object *elm_object_item_content_part_get(const Elm_Object_Item *it, const char *part);
-#define elm_object_item_content_get(it, content) elm_object_item_content_part_get((it), NULL, (content))
+#define elm_object_item_content_get(it) elm_object_item_content_part_get((it), NULL)
/**
* Unset a content of an object item
*/
EAPI Evas_Object *elm_object_item_content_part_unset(Elm_Object_Item *it, const char *part);
-#define elm_object_item_content_unset(it, content) elm_object_item_content_part_unset((it), (content))
+#define elm_object_item_content_unset(it) elm_object_item_content_part_unset((it), NULL)
/**
* Set a label of an objec itemt
*/
EAPI const char *elm_object_item_text_part_get(const Elm_Object_Item *it, const char *part);
-#define elm_object_item_text_get(it) elm_object_item_part_text_get((it), NULL)
+ /**
+ * Set the text to read out when in accessibility mode
+ *
+ * @param obj The object which is to be described
+ * @param txt The text that describes the widget to people with poor or no vision
+ *
+ * @ingroup General
+ */
+ EAPI void elm_object_access_info_set(Evas_Object *obj, const char *txt);
/**
- * @}
+ * Set the text to read out when in accessibility mode
+ *
+ * @param it The object item which is to be described
+ * @param txt The text that describes the widget to people with poor or no vision
+ *
+ * @ingroup General
*/
+ EAPI void elm_object_item_access_info_set(Elm_Object_Item *it, const char *txt);
- EAPI void elm_all_flush(void);
- EAPI int elm_cache_flush_interval_get(void);
- EAPI void elm_cache_flush_interval_set(int size);
- EAPI void elm_cache_flush_interval_all_set(int size);
- EAPI Eina_Bool elm_cache_flush_enabled_get(void);
- EAPI void elm_cache_flush_enabled_set(Eina_Bool enabled);
- EAPI void elm_cache_flush_enabled_all_set(Eina_Bool enabled);
- EAPI int elm_font_cache_get(void);
- EAPI void elm_font_cache_set(int size);
- EAPI void elm_font_cache_all_set(int size);
- EAPI int elm_image_cache_get(void);
- EAPI void elm_image_cache_set(int size);
- EAPI void elm_image_cache_all_set(int size);
- EAPI int elm_edje_file_cache_get(void);
- EAPI void elm_edje_file_cache_set(int size);
- EAPI void elm_edje_file_cache_all_set(int size);
- EAPI int elm_edje_collection_cache_get(void);
- EAPI void elm_edje_collection_cache_set(int size);
- EAPI void elm_edje_collection_cache_all_set(int size);
+
+#define elm_object_item_text_get(it) elm_object_item_text_part_get((it), NULL)
/**
- * @defgroup Scaling Selective Widget Scaling
+ * Get the data associated with an object item
+ * @param it The object item
+ * @return The data associated with @p it
*
- * Different widgets can be scaled independently. These functions
- * allow you to manipulate this scaling on a per-widget basis. The
- * object and all its children get their scaling factors multiplied
- * by the scale factor set. This is multiplicative, in that if a
- * child also has a scale size set it is in turn multiplied by its
- * parent's scale size. @c 1.0 means “don't scale”, @c 2.0 is
- * double size, @c 0.5 is half, etc.
+ * @ingroup General
+ */
+ EAPI void *elm_object_item_data_get(const Elm_Object_Item *it);
+
+ /**
+ * Set the data associated with an object item
+ * @param it The object item
+ * @param data The data to be associated with @p it
*
- * @ref general_functions_example_page "This" example contemplates
- * some of these functions.
+ * @ingroup General
*/
+ EAPI void elm_object_item_data_set(Elm_Object_Item *it, void *data);
/**
- * Set the scaling factor for a given Elementary object
+ * Send a signal to the edje object of the widget item.
*
- * @param obj The Elementary to operate on
- * @param scale Scale factor (from @c 0.0 up, with @c 1.0 meaning
- * no scaling)
+ * This function sends a signal to the edje object of the obj item. An
+ * edje program can respond to a signal by specifying matching
+ * 'signal' and 'source' fields.
*
- * @ingroup Scaling
+ * @param it The Elementary object item
+ * @param emission The signal's name.
+ * @param source The signal's source.
+ * @ingroup General
*/
- EAPI void elm_object_scale_set(Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_item_signal_emit(Elm_Object_Item *it, const char *emission, const char *source) EINA_ARG_NONNULL(1);
/**
- * Get the scaling factor for a given Elementary object
+ * @}
+ */
+
+ /**
+ * @defgroup Caches Caches
*
- * @param obj The object
- * @return The scaling factor set by elm_object_scale_set()
+ * These are functions which let one fine-tune some cache values for
+ * Elementary applications, thus allowing for performance adjustments.
*
- * @ingroup Scaling
+ * @{
*/
- EAPI double elm_object_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_object_mirrored_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_object_mirrored_set(Evas_Object *obj, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_object_mirrored_automatic_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_object_mirrored_automatic_set(Evas_Object *obj, Eina_Bool automatic) EINA_ARG_NONNULL(1);
+
/**
- * Set the style to use by a widget
+ * @brief Flush all caches.
*
- * Sets the style name that will define the appearance of a widget. Styles
- * vary from widget to widget and may also be defined by other themes
- * by means of extensions and overlays.
+ * Frees all data that was in cache and is not currently being used to reduce
+ * memory usage. This frees Edje's, Evas' and Eet's cache. This is equivalent
+ * to calling all of the following functions:
+ * @li edje_file_cache_flush()
+ * @li edje_collection_cache_flush()
+ * @li eet_clearcache()
+ * @li evas_image_cache_flush()
+ * @li evas_font_cache_flush()
+ * @li evas_render_dump()
+ * @note Evas caches are flushed for every canvas associated with a window.
*
- * @param obj The Elementary widget to style
- * @param style The style name to use
+ * @ingroup Caches
+ */
+ EAPI void elm_all_flush(void);
+
+ /**
+ * Get the configured cache flush interval time
*
- * @see elm_theme_extension_add()
- * @see elm_theme_overlay_add()
+ * This gets the globally configured cache flush interval time, in
+ * ticks
+ *
+ * @return The cache flush interval time
+ * @ingroup Caches
*
- * @ingroup Theme
+ * @see elm_all_flush()
*/
- EAPI void elm_object_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
+ EAPI int elm_cache_flush_interval_get(void);
+
/**
- * Get the style used by the widget
- *
- * This gets the style being used for that widget. Note that the string
- * pointer is only valid as longas the object is valid and the style doesn't
- * change.
+ * Set the configured cache flush interval time
*
- * @param obj The Elementary widget to query for its style
- * @return The style name used
+ * This sets the globally configured cache flush interval time, in ticks
*
- * @see elm_object_style_set()
+ * @param size The cache flush interval time
+ * @ingroup Caches
*
- * @ingroup Theme
+ * @see elm_all_flush()
*/
- EAPI const char *elm_object_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_cache_flush_interval_set(int size);
/**
- * @defgroup Styles Styles
+ * Set the configured cache flush interval time for all applications on the
+ * display
*
- * Widgets can have different styles of look. These generic API's
- * set styles of widgets, if they support them (and if the theme(s)
- * do).
+ * This sets the globally configured cache flush interval time -- in ticks
+ * -- for all applications on the display.
*
- * @ref general_functions_example_page "This" example contemplates
- * some of these functions.
+ * @param size The cache flush interval time
+ * @ingroup Caches
*/
+ EAPI void elm_cache_flush_interval_all_set(int size);
/**
- * Set the disabled state of an Elementary object.
- *
- * @param obj The Elementary object to operate on
- * @param disabled The state to put in in: @c EINA_TRUE for
- * disabled, @c EINA_FALSE for enabled
+ * Get the configured cache flush enabled state
*
- * Elementary objects can be @b disabled, in which state they won't
- * receive input and, in general, will be themed differently from
- * their normal state, usually greyed out. Useful for contexts
- * where you don't want your users to interact with some of the
- * parts of you interface.
+ * This gets the globally configured cache flush state - if it is enabled
+ * or not. When cache flushing is enabled, elementary will regularly
+ * (see elm_cache_flush_interval_get() ) flush caches and dump data out of
+ * memory and allow usage to re-seed caches and data in memory where it
+ * can do so. An idle application will thus minimise its memory usage as
+ * data will be freed from memory and not be re-loaded as it is idle and
+ * not rendering or doing anything graphically right now.
*
- * This sets the state for the widget, either disabling it or
- * enabling it back.
+ * @return The cache flush state
+ * @ingroup Caches
*
- * @ingroup Styles
+ * @see elm_all_flush()
*/
- EAPI void elm_object_disabled_set(Evas_Object *obj, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_cache_flush_enabled_get(void);
/**
- * Get the disabled state of an Elementary object.
+ * Set the configured cache flush enabled state
*
- * @param obj The Elementary object to operate on
- * @return @c EINA_TRUE, if the widget is disabled, @c EINA_FALSE
- * if it's enabled (or on errors)
+ * This sets the globally configured cache flush enabled state
*
- * This gets the state of the widget, which might be enabled or disabled.
+ * @param size The cache flush enabled state
+ * @ingroup Caches
*
- * @ingroup Styles
+ * @see elm_all_flush()
*/
- EAPI Eina_Bool elm_object_disabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_cache_flush_enabled_set(Eina_Bool enabled);
/**
- * @defgroup WidgetNavigation Widget Tree Navigation.
+ * Set the configured cache flush enabled state for all applications on the
+ * display
*
- * How to check if an Evas Object is an Elementary widget? How to
- * get the first elementary widget that is parent of the given
- * object? These are all covered in widget tree navigation.
+ * This sets the globally configured cache flush enabled state for all
+ * applications on the display.
*
- * @ref general_functions_example_page "This" example contemplates
- * some of these functions.
+ * @param size The cache flush enabled state
+ * @ingroup Caches
*/
-
- EAPI Eina_Bool elm_object_widget_check(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_cache_flush_enabled_all_set(Eina_Bool enabled);
/**
- * Get the first parent of the given object that is an Elementary
- * widget.
+ * Get the configured font cache size
*
- * @param obj the Elementary object to query parent from.
- * @return the parent object that is an Elementary widget, or @c
- * NULL, if it was not found.
+ * This gets the globally configured font cache size, in bytes
*
- * Use this to query for an object's parent widget.
+ * @return The font cache size
+ * @ingroup Caches
+ */
+ EAPI int elm_font_cache_get(void);
+
+ /**
+ * Set the configured font cache size
*
- * @note Most of Elementary users wouldn't be mixing non-Elementary
- * smart objects in the objects tree of an application, as this is
- * an advanced usage of Elementary with Evas. So, except for the
- * application's window, which is the root of that tree, all other
- * objects would have valid Elementary widget parents.
+ * This sets the globally configured font cache size, in bytes
*
- * @ingroup WidgetNavigation
+ * @param size The font cache size
+ * @ingroup Caches
*/
- EAPI Evas_Object *elm_object_parent_widget_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Evas_Object *elm_object_top_widget_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI const char *elm_object_widget_type_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_font_cache_set(int size);
- EAPI double elm_scale_get(void);
- EAPI void elm_scale_set(double scale);
- EAPI void elm_scale_all_set(double scale);
+ /**
+ * Set the configured font cache size for all applications on the
+ * display
+ *
+ * This sets the globally configured font cache size -- in bytes
+ * -- for all applications on the display.
+ *
+ * @param size The font cache size
+ * @ingroup Caches
+ */
+ EAPI void elm_font_cache_all_set(int size);
- EAPI Eina_Bool elm_mirrored_get(void);
- EAPI void elm_mirrored_set(Eina_Bool mirrored);
+ /**
+ * Get the configured image cache size
+ *
+ * This gets the globally configured image cache size, in bytes
+ *
+ * @return The image cache size
+ * @ingroup Caches
+ */
+ EAPI int elm_image_cache_get(void);
- EAPI Eina_Bool elm_config_save(void);
- EAPI void elm_config_reload(void);
+ /**
+ * Set the configured image cache size
+ *
+ * This sets the globally configured image cache size, in bytes
+ *
+ * @param size The image cache size
+ * @ingroup Caches
+ */
+ EAPI void elm_image_cache_set(int size);
- EAPI const char *elm_profile_current_get(void);
- EAPI const char *elm_profile_dir_get(const char *profile, Eina_Bool is_user);
- EAPI void elm_profile_dir_free(const char *p_dir);
- EAPI Eina_List *elm_profile_list_get(void);
- EAPI void elm_profile_list_free(Eina_List *l);
- EAPI void elm_profile_set(const char *profile);
- EAPI void elm_profile_all_set(const char *profile);
-
- EAPI const char *elm_engine_current_get(void);
- EAPI void elm_engine_set(const char *engine);
-
- typedef struct _Elm_Text_Class
- {
- const char *name;
- const char *desc;
- } Elm_Text_Class;
-
- typedef struct _Elm_Font_Overlay
- {
- const char *text_class;
- const char *font;
- Evas_Font_Size size;
- } Elm_Font_Overlay;
-
- typedef struct _Elm_Font_Properties
- {
- const char *name;
- Eina_List *styles;
- } Elm_Font_Properties;
-
- EAPI const Eina_List *elm_text_classes_list_get(void);
- EAPI void elm_text_classes_list_free(const Eina_List *list);
-
- EAPI const Eina_List *elm_font_overlay_list_get(void);
- EAPI void elm_font_overlay_set(const char *text_class, const char *font, Evas_Font_Size size);
- EAPI void elm_font_overlay_unset(const char *text_class);
- EAPI void elm_font_overlay_apply(void);
- EAPI void elm_font_overlay_all_apply(void);
-
- EAPI Elm_Font_Properties *elm_font_properties_get(const char *font) EINA_ARG_NONNULL(1);
- EAPI void elm_font_properties_free(Elm_Font_Properties *efp) EINA_ARG_NONNULL(1);
- EAPI const char *elm_font_fontconfig_name_get(const char *name, const char *style) EINA_ARG_NONNULL(1);
- EAPI void elm_font_fontconfig_name_free(const char *name) EINA_ARG_NONNULL(1);
- EAPI Eina_Hash *elm_font_available_hash_add(Eina_List *list);
- EAPI void elm_font_available_hash_del(Eina_Hash *hash);
+ /**
+ * Set the configured image cache size for all applications on the
+ * display
+ *
+ * This sets the globally configured image cache size -- in bytes
+ * -- for all applications on the display.
+ *
+ * @param size The image cache size
+ * @ingroup Caches
+ */
+ EAPI void elm_image_cache_all_set(int size);
/**
- * @defgroup Fingers Fingers
+ * Get the configured edje file cache size.
*
- * Elementary is designed to be finger-friendly for touchscreens,
- * and so in addition to scaling for display resolution, it can
- * also scale based on finger "resolution" (or size). You can then
- * customize the granularity of the areas meant to receive clicks
- * on touchscreens.
+ * This gets the globally configured edje file cache size, in number
+ * of files.
*
- * Different profiles may have pre-set values for finger sizes.
+ * @return The edje file cache size
+ * @ingroup Caches
+ */
+ EAPI int elm_edje_file_cache_get(void);
+
+ /**
+ * Set the configured edje file cache size
*
- * @ref general_functions_example_page "This" example contemplates
- * some of these functions.
+ * This sets the globally configured edje file cache size, in number
+ * of files.
+ *
+ * @param size The edje file cache size
+ * @ingroup Caches
*/
+ EAPI void elm_edje_file_cache_set(int size);
/**
- * Get the configured "finger size"
+ * Set the configured edje file cache size for all applications on the
+ * display
*
- * @return The finger size
+ * This sets the globally configured edje file cache size -- in number
+ * of files -- for all applications on the display.
*
- * This gets the globally configured finger size, <b>in pixels</b>
+ * @param size The edje file cache size
+ * @ingroup Caches
+ */
+ EAPI void elm_edje_file_cache_all_set(int size);
+
+ /**
+ * Get the configured edje collections (groups) cache size.
*
- * @ingroup Fingers
+ * This gets the globally configured edje collections cache size, in
+ * number of collections.
+ *
+ * @return The edje collections cache size
+ * @ingroup Caches
*/
- EAPI Evas_Coord elm_finger_size_get(void);
- EAPI void elm_finger_size_set(Evas_Coord size);
- EAPI void elm_finger_size_all_set(Evas_Coord size);
+ EAPI int elm_edje_collection_cache_get(void);
/**
- * @defgroup Focus Focus
+ * Set the configured edje collections (groups) cache size
*
- * An Elementary application has, at all times, one (and only one)
- * @b focused object. This is what determines where the input
- * events go to within the application's window. Also, focused
- * objects can be decorated differently, in order to signal to the
- * user where the input is, at a given moment.
+ * This sets the globally configured edje collections cache size, in
+ * number of collections.
*
- * Elementary applications also have the concept of <b>focus
- * chain</b>: one can cycle through all the windows' focusable
- * objects by input (tab key) or programmatically. The default
- * focus chain for an application is the one define by the order in
- * which the widgets where added in code. One will cycle through
- * top level widgets, and, for each one containg sub-objects, cycle
- * through them all, before returning to the level
- * above. Elementary also allows one to set @b custom focus chains
- * for their applications.
+ * @param size The edje collections cache size
+ * @ingroup Caches
+ */
+ EAPI void elm_edje_collection_cache_set(int size);
+
+ /**
+ * Set the configured edje collections (groups) cache size for all
+ * applications on the display
*
- * Besides the focused decoration a widget may exhibit, when it
- * gets focus, Elementary has a @b global focus highlight object
- * that can be enabled for a window. If one chooses to do so, this
- * extra highlight effect will surround the current focused object,
- * too.
+ * This sets the globally configured edje collections cache size -- in
+ * number of collections -- for all applications on the display.
*
- * @note Some Elementary widgets are @b unfocusable, after
- * creation, by their very nature: they are not meant to be
- * interacted with input events, but are there just for visual
- * purposes.
+ * @param size The edje collections cache size
+ * @ingroup Caches
+ */
+ EAPI void elm_edje_collection_cache_all_set(int size);
+
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Scaling Widget Scaling
+ *
+ * Different widgets can be scaled independently. These functions
+ * allow you to manipulate this scaling on a per-widget basis. The
+ * object and all its children get their scaling factors multiplied
+ * by the scale factor set. This is multiplicative, in that if a
+ * child also has a scale size set it is in turn multiplied by its
+ * parent's scale size. @c 1.0 means “don't scale”, @c 2.0 is
+ * double size, @c 0.5 is half, etc.
*
* @ref general_functions_example_page "This" example contemplates
* some of these functions.
*/
- EAPI Eina_Bool elm_focus_highlight_enabled_get(void);
- EAPI void elm_focus_highlight_enabled_set(Eina_Bool enable);
- EAPI Eina_Bool elm_focus_highlight_animate_get(void);
- EAPI void elm_focus_highlight_animate_set(Eina_Bool animate);
-
/**
- * Get the whether an Elementary object has the focus or not.
+ * Get the global scaling factor
*
- * @param obj The Elementary object to get the information from
- * @return @c EINA_TRUE, if the object is focused, @c EINA_FALSE if
- * not (and on errors).
- *
- * @see elm_object_focus()
+ * This gets the globally configured scaling factor that is applied to all
+ * objects.
*
- * @ingroup Focus
+ * @return The scaling factor
+ * @ingroup Scaling
*/
- EAPI Eina_Bool elm_object_focus_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI double elm_scale_get(void);
/**
- * Set/unset focus to a given Elementary object.
- *
- * @param obj The Elementary object to operate on.
- * @param enable @c EINA_TRUE Set focus to a given object,
- * @c EINA_FALSE Unset focus to a given object.
+ * Set the global scaling factor
*
- * @note When you set focus to this object, if it can handle focus, will
- * take the focus away from the one who had it previously and will, for
- * now on, be the one receiving input events. Unsetting focus will remove
- * the focus from @p obj, passing it back to the previous element in the
- * focus chain list.
+ * This sets the globally configured scaling factor that is applied to all
+ * objects.
*
- * @see elm_object_focus_get(), elm_object_focus_custom_chain_get()
+ * @param scale The scaling factor to set
+ * @ingroup Scaling
+ */
+ EAPI void elm_scale_set(double scale);
+
+ /**
+ * Set the global scaling factor for all applications on the display
*
- * @ingroup Focus
+ * This sets the globally configured scaling factor that is applied to all
+ * objects for all applications.
+ * @param scale The scaling factor to set
+ * @ingroup Scaling
*/
- EAPI void elm_object_focus_set(Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
+ EAPI void elm_scale_all_set(double scale);
/**
- * Make a given Elementary object the focused one.
+ * Set the scaling factor for a given Elementary object
*
- * @param obj The Elementary object to make focused.
+ * @param obj The Elementary to operate on
+ * @param scale Scale factor (from @c 0.0 up, with @c 1.0 meaning
+ * no scaling)
*
- * @note This object, if it can handle focus, will take the focus
- * away from the one who had it previously and will, for now on, be
- * the one receiving input events.
+ * @ingroup Scaling
+ */
+ EAPI void elm_object_scale_set(Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the scaling factor for a given Elementary object
*
- * @see elm_object_focus_get()
- * @deprecated use elm_object_focus_set() instead.
+ * @param obj The object
+ * @return The scaling factor set by elm_object_scale_set()
*
- * @ingroup Focus
+ * @ingroup Scaling
*/
- EINA_DEPRECATED EAPI void elm_object_focus(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI double elm_object_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Remove the focus from an Elementary object
+ * @defgroup Password_last_show Password last input show
*
- * @param obj The Elementary to take focus from
+ * Last show feature of password mode enables user to view
+ * the last input entered for few seconds before masking it.
+ * These functions allow to set this feature in password mode
+ * of entry widget and also allow to manipulate the duration
+ * for which the input has to be visible.
*
- * This removes the focus from @p obj, passing it back to the
- * previous element in the focus chain list.
+ * @{
+ */
+
+ /**
+ * Get show last setting of password mode.
*
- * @see elm_object_focus() and elm_object_focus_custom_chain_get()
- * @deprecated use elm_object_focus_set() instead.
+ * This gets the show last input setting of password mode which might be
+ * enabled or disabled.
*
- * @ingroup Focus
+ * @return @c EINA_TRUE, if the last input show setting is enabled, @c EINA_FALSE
+ * if it's disabled.
+ * @ingroup Password_last_show
*/
- EINA_DEPRECATED EAPI void elm_object_unfocus(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_password_show_last_get(void);
/**
- * Set the ability for an Element object to be focused
- *
- * @param obj The Elementary object to operate on
- * @param enable @c EINA_TRUE if the object can be focused, @c
- * EINA_FALSE if not (and on errors)
+ * Set show last setting in password mode.
*
- * This sets whether the object @p obj is able to take focus or
- * not. Unfocusable objects do nothing when programmatically
- * focused, being the nearest focusable parent object the one
- * really getting focus. Also, when they receive mouse input, they
- * will get the event, but not take away the focus from where it
- * was previously.
+ * This enables or disables show last setting of password mode.
*
- * @ingroup Focus
+ * @param password_show_last If EINA_TRUE enable's last input show in password mode.
+ * @see elm_password_show_last_timeout_set()
+ * @ingroup Password_last_show
*/
- EAPI void elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
+ EAPI void elm_password_show_last_set(Eina_Bool password_show_last);
/**
- * Get whether an Elementary object is focusable or not
+ * Get's the timeout value in last show password mode.
*
- * @param obj The Elementary object to operate on
- * @return @c EINA_TRUE if the object is allowed to be focused, @c
- * EINA_FALSE if not (and on errors)
+ * This gets the time out value for which the last input entered in password
+ * mode will be visible.
*
- * @note Objects which are meant to be interacted with by input
- * events are created able to be focused, by default. All the
- * others are not.
+ * @return The timeout value of last show password mode.
+ * @ingroup Password_last_show
+ */
+ EAPI double elm_password_show_last_timeout_get(void);
+
+ /**
+ * Set's the timeout value in last show password mode.
*
- * @ingroup Focus
+ * This sets the time out value for which the last input entered in password
+ * mode will be visible.
+ *
+ * @param password_show_last_timeout The timeout value.
+ * @see elm_password_show_last_set()
+ * @ingroup Password_last_show
*/
- EAPI Eina_Bool elm_object_focus_allow_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_password_show_last_timeout_set(double password_show_last_timeout);
- EAPI void elm_object_focus_custom_chain_set(Evas_Object *obj, Eina_List *objs) EINA_ARG_NONNULL(1);
- EAPI void elm_object_focus_custom_chain_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI const Eina_List *elm_object_focus_custom_chain_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_object_focus_custom_chain_append(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child) EINA_ARG_NONNULL(1, 2);
- EAPI void elm_object_focus_custom_chain_prepend(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child) EINA_ARG_NONNULL(1, 2);
- EAPI void elm_object_focus_cycle(Evas_Object *obj, Elm_Focus_Direction dir) EINA_ARG_NONNULL(1);
- EAPI void elm_object_focus_direction_go(Evas_Object *obj, int x, int y) EINA_ARG_NONNULL(1);
+ /**
+ * @}
+ */
/**
- * Make the elementary object and its children to be unfocusable (or focusable).
+ * @defgroup UI-Mirroring Selective Widget mirroring
*
- * @param obj The Elementary object to operate on
- * @param tree_unfocusable @c EINA_TRUE for unfocusable,
- * @c EINA_FALSE for focusable.
+ * These functions allow you to set ui-mirroring on specific
+ * widgets or the whole interface. Widgets can be in one of two
+ * modes, automatic and manual. Automatic means they'll be changed
+ * according to the system mirroring mode and manual means only
+ * explicit changes will matter. You are not supposed to change
+ * mirroring state of a widget set to automatic, will mostly work,
+ * but the behavior is not really defined.
*
- * This sets whether the object @p obj and its children objects
- * are able to take focus or not. If the tree is set as unfocusable,
- * newest focused object which is not in this tree will get focus.
- * This API can be helpful for an object to be deleted.
- * When an object will be deleted soon, it and its children may not
- * want to get focus (by focus reverting or by other focus controls).
- * Then, just use this API before deleting.
+ * @{
+ */
+
+ EAPI Eina_Bool elm_mirrored_get(void);
+ EAPI void elm_mirrored_set(Eina_Bool mirrored);
+
+ /**
+ * Get the system mirrored mode. This determines the default mirrored mode
+ * of widgets.
*
- * @see elm_object_tree_unfocusable_get()
+ * @return EINA_TRUE if mirrored is set, EINA_FALSE otherwise
+ */
+ EAPI Eina_Bool elm_object_mirrored_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the system mirrored mode. This determines the default mirrored mode
+ * of widgets.
*
- * @ingroup Focus
+ * @param mirrored EINA_TRUE to set mirrored mode, EINA_FALSE to unset it.
*/
- EAPI void elm_object_tree_unfocusable_set(Evas_Object *obj, Eina_Bool tree_unfocusable); EINA_ARG_NONNULL(1);
+ EAPI void elm_object_mirrored_set(Evas_Object *obj, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
/**
- * Get whether an Elementary object and its children are unfocusable or not.
+ * Returns the widget's mirrored mode setting.
*
- * @param obj The Elementary object to get the information from
- * @return @c EINA_TRUE, if the tree is unfocussable,
- * @c EINA_FALSE if not (and on errors).
- *
- * @see elm_object_tree_unfocusable_set()
+ * @param obj The widget.
+ * @return mirrored mode setting of the object.
*
- * @ingroup Focus
- */
- EAPI Eina_Bool elm_object_tree_unfocusable_get(const Evas_Object *obj); EINA_ARG_NONNULL(1);
-
- EAPI Eina_Bool elm_scroll_bounce_enabled_get(void);
- EAPI void elm_scroll_bounce_enabled_set(Eina_Bool enabled);
- EAPI void elm_scroll_bounce_enabled_all_set(Eina_Bool enabled);
- EAPI double elm_scroll_bounce_friction_get(void);
- EAPI void elm_scroll_bounce_friction_set(double friction);
- EAPI void elm_scroll_bounce_friction_all_set(double friction);
- EAPI double elm_scroll_page_scroll_friction_get(void);
- EAPI void elm_scroll_page_scroll_friction_set(double friction);
- EAPI void elm_scroll_page_scroll_friction_all_set(double friction);
- EAPI double elm_scroll_bring_in_scroll_friction_get(void);
- EAPI void elm_scroll_bring_in_scroll_friction_set(double friction);
- EAPI void elm_scroll_bring_in_scroll_friction_all_set(double friction);
- EAPI double elm_scroll_zoom_friction_get(void);
- EAPI void elm_scroll_zoom_friction_set(double friction);
- EAPI void elm_scroll_zoom_friction_all_set(double friction);
- EAPI Eina_Bool elm_scroll_thumbscroll_enabled_get(void);
- EAPI void elm_scroll_thumbscroll_enabled_set(Eina_Bool enabled);
- EAPI void elm_scroll_thumbscroll_enabled_all_set(Eina_Bool enabled);
- EAPI unsigned int elm_scroll_thumbscroll_threshold_get(void);
- EAPI void elm_scroll_thumbscroll_threshold_set(unsigned int threshold);
- EAPI void elm_scroll_thumbscroll_threshold_all_set(unsigned int threshold);
- EAPI double elm_scroll_thumbscroll_momentum_threshold_get(void);
- EAPI void elm_scroll_thumbscroll_momentum_threshold_set(double threshold);
- EAPI void elm_scroll_thumbscroll_momentum_threshold_all_set(double threshold);
- EAPI double elm_scroll_thumbscroll_friction_get(void);
- EAPI void elm_scroll_thumbscroll_friction_set(double friction);
- EAPI void elm_scroll_thumbscroll_friction_all_set(double friction);
- EAPI double elm_scroll_thumbscroll_border_friction_get(void);
- EAPI void elm_scroll_thumbscroll_border_friction_set(double friction);
- EAPI void elm_scroll_thumbscroll_border_friction_all_set(double friction);
-
- EAPI void elm_object_scroll_hold_push(Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_object_scroll_hold_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_object_scroll_freeze_push(Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_object_scroll_freeze_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_object_scroll_lock_x_set(Evas_Object *obj, Eina_Bool lock) EINA_ARG_NONNULL(1);
- EAPI void elm_object_scroll_lock_y_set(Evas_Object *obj, Eina_Bool lock) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_object_scroll_lock_x_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_object_scroll_lock_y_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- EAPI void elm_object_signal_emit(Evas_Object *obj, const char *emission, const char *source) EINA_ARG_NONNULL(1);
- EAPI void elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data) EINA_ARG_NONNULL(1, 4);
- EAPI void *elm_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func) EINA_ARG_NONNULL(1, 4);
-
- EAPI void elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
- EAPI void *elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+ **/
+ EAPI Eina_Bool elm_object_mirrored_automatic_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Adjust size of an element for finger usage.
- *
- * @param times_w How many fingers should fit horizontally
- * @param w Pointer to the width size to adjust
- * @param times_h How many fingers should fit vertically
- * @param h Pointer to the height size to adjust
- *
- * This takes width and height sizes (in pixels) as input and a
- * size multiple (which is how many fingers you want to place
- * within the area, being "finger" the size set by
- * elm_finger_size_set()), and adjusts the size to be large enough
- * to accommodate the resulting size -- if it doesn't already
- * accommodate it. On return the @p w and @p h sizes pointed to by
- * these parameters will be modified, on those conditions.
- *
- * @note This is kind of a low level Elementary call, most useful
- * on size evaluation times for widgets. An external user wouldn't
- * be calling, most of the time.
- *
- * @ingroup Fingers
+ * Sets the widget's mirrored mode setting.
+ * When widget in automatic mode, it follows the system mirrored mode set by
+ * elm_mirrored_set().
+ * @param obj The widget.
+ * @param automatic EINA_TRUE for auto mirrored mode. EINA_FALSE for manual.
*/
- EAPI void elm_coords_finger_size_adjust(int times_w, Evas_Coord *w, int times_h, Evas_Coord *h);
-
- EAPI double elm_longpress_timeout_get(void);
- EAPI void elm_longpress_timeout_set(double longpress_timeout);
+ EAPI void elm_object_mirrored_automatic_set(Evas_Object *obj, Eina_Bool automatic) EINA_ARG_NONNULL(1);
- /* debug
- * don't use it unless you are sure
+ /**
+ * @}
*/
- EAPI void elm_object_tree_dump(const Evas_Object *top);
- EAPI void elm_object_tree_dot_dump(const Evas_Object *top, const char *file);
-
- /* theme */
/**
- * @defgroup Theme Theme
- *
- * Elementary uses Edje to theme its widgets, naturally. But for the most
- * part this is hidden behind a simpler interface that lets the user set
- * extensions and choose the style of widgets in a much easier way.
- *
- * Instead of thinking in terms of paths to Edje files and their groups
- * each time you want to change the appearance of a widget, Elementary
- * works so you can add any theme file with extensions or replace the
- * main theme at one point in the application, and then just set the style
- * of widgets with elm_object_style_set() and related functions. Elementary
- * will then look in its list of themes for a matching group and apply it,
- * and when the theme changes midway through the application, all widgets
- * will be updated accordingly.
+ * Set the style to use by a widget
*
- * There are three concepts you need to know to understand how Elementary
- * theming works: default theme, extensions and overlays.
+ * Sets the style name that will define the appearance of a widget. Styles
+ * vary from widget to widget and may also be defined by other themes
+ * by means of extensions and overlays.
*
- * Default theme, obviously enough, is the one that provides the default
- * look of all widgets. End users can change the theme used by Elementary
- * by setting the @c ELM_THEME environment variable before running an
- * application, or globally for all programs using the @c elementary_config
- * utility. Applications can change the default theme using elm_theme_set(),
- * but this can go against the user wishes, so it's not an adviced practice.
+ * @param obj The Elementary widget to style
+ * @param style The style name to use
*
- * Ideally, applications should find everything they need in the already
- * provided theme, but there may be occasions when that's not enough and
- * custom styles are required to correctly express the idea. For this
- * cases, Elementary has extensions.
+ * @see elm_theme_extension_add()
+ * @see elm_theme_extension_del()
+ * @see elm_theme_overlay_add()
+ * @see elm_theme_overlay_del()
*
- * Extensions allow the application developer to write styles of its own
- * to apply to some widgets. This requires knowledge of how each widget
- * is themed, as extensions will always replace the entire group used by
- * the widget, so important signals and parts need to be there for the
- * object to behave properly (see documentation of Edje for details).
- * Once the theme for the extension is done, the application needs to add
- * it to the list of themes Elementary will look into, using
- * elm_theme_extension_add(), and set the style of the desired widgets as
- * he would normally with elm_object_style_set().
+ * @ingroup Styles
+ */
+ EAPI void elm_object_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
+ /**
+ * Get the style used by the widget
*
- * Overlays, on the other hand, can replace the look of all widgets by
- * overriding the default style. Like extensions, it's up to the application
- * developer to write the theme for the widgets it wants, the difference
- * being that when looking for the theme, Elementary will check first the
- * list of overlays, then the set theme and lastly the list of extensions,
- * so with overlays it's possible to replace the default view and every
- * widget will be affected. This is very much alike to setting the whole
- * theme for the application and will probably clash with the end user
- * options, not to mention the risk of ending up with not matching styles
- * across the program. Unless there's a very special reason to use them,
- * overlays should be avoided for the resons exposed before.
+ * This gets the style being used for that widget. Note that the string
+ * pointer is only valid as longas the object is valid and the style doesn't
+ * change.
*
- * All these theme lists are handled by ::Elm_Theme instances. Elementary
- * keeps one default internally and every function that receives one of
- * these can be called with NULL to refer to this default (except for
- * elm_theme_free()). It's possible to create a new instance of a
- * ::Elm_Theme to set other theme for a specific widget (and all of its
- * children), but this is as discouraged, if not even more so, than using
- * overlays. Don't use this unless you really know what you are doing.
+ * @param obj The Elementary widget to query for its style
+ * @return The style name used
*
- * But to be less negative about things, you can look at the following
- * examples:
- * @li @ref theme_example_01 "Using extensions"
- * @li @ref theme_example_02 "Using overlays"
+ * @see elm_object_style_set()
*
- * @{
+ * @ingroup Styles
*/
+ EAPI const char *elm_object_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * @typedef Elm_Theme
+ * @defgroup Styles Styles
*
- * Opaque handler for the list of themes Elementary looks for when
- * rendering widgets.
+ * Widgets can have different styles of look. These generic API's
+ * set styles of widgets, if they support them (and if the theme(s)
+ * do).
*
- * Stay out of this unless you really know what you are doing. For most
- * cases, sticking to the default is all a developer needs.
+ * @ref general_functions_example_page "This" example contemplates
+ * some of these functions.
*/
- typedef struct _Elm_Theme Elm_Theme;
/**
- * Create a new specific theme
+ * Set the disabled state of an Elementary object.
*
- * This creates an empty specific theme that only uses the default theme. A
- * specific theme has its own private set of extensions and overlays too
- * (which are empty by default). Specific themes do not fall back to themes
- * of parent objects. They are not intended for this use. Use styles, overlays
- * and extensions when needed, but avoid specific themes unless there is no
- * other way (example: you want to have a preview of a new theme you are
- * selecting in a "theme selector" window. The preview is inside a scroller
- * and should display what the theme you selected will look like, but not
- * actually apply it yet. The child of the scroller will have a specific
- * theme set to show this preview before the user decides to apply it to all
- * applications).
- */
- EAPI Elm_Theme *elm_theme_new(void);
- /**
- * Free a specific theme
+ * @param obj The Elementary object to operate on
+ * @param disabled The state to put in in: @c EINA_TRUE for
+ * disabled, @c EINA_FALSE for enabled
*
- * @param th The theme to free
+ * Elementary objects can be @b disabled, in which state they won't
+ * receive input and, in general, will be themed differently from
+ * their normal state, usually greyed out. Useful for contexts
+ * where you don't want your users to interact with some of the
+ * parts of you interface.
*
- * This frees a theme created with elm_theme_new().
+ * This sets the state for the widget, either disabling it or
+ * enabling it back.
+ *
+ * @ingroup Styles
*/
- EAPI void elm_theme_free(Elm_Theme *th);
+ EAPI void elm_object_disabled_set(Evas_Object *obj, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+
/**
- * Copy the theme fom the source to the destination theme
+ * Get the disabled state of an Elementary object.
*
- * @param th The source theme to copy from
- * @param thdst The destination theme to copy data to
+ * @param obj The Elementary object to operate on
+ * @return @c EINA_TRUE, if the widget is disabled, @c EINA_FALSE
+ * if it's enabled (or on errors)
*
- * This makes a one-time static copy of all the theme config, extensions
- * and overlays from @p th to @p thdst. If @p th references a theme, then
- * @p thdst is also set to reference it, with all the theme settings,
- * overlays and extensions that @p th had.
+ * This gets the state of the widget, which might be enabled or disabled.
+ *
+ * @ingroup Styles
*/
- EAPI void elm_theme_copy(Elm_Theme *th, Elm_Theme *thdst);
+ EAPI Eina_Bool elm_object_disabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Tell the source theme to reference the ref theme
+ * @defgroup WidgetNavigation Widget Tree Navigation.
*
- * @param th The theme that will do the referencing
- * @param thref The theme that is the reference source
+ * How to check if an Evas Object is an Elementary widget? How to
+ * get the first elementary widget that is parent of the given
+ * object? These are all covered in widget tree navigation.
*
- * This clears @p th to be empty and then sets it to refer to @p thref
- * so @p th acts as an override to @p thref, but where its overrides
- * don't apply, it will fall through to @p thref for configuration.
+ * @ref general_functions_example_page "This" example contemplates
+ * some of these functions.
*/
- EAPI void elm_theme_ref_set(Elm_Theme *th, Elm_Theme *thref);
+
/**
- * Return the theme referred to
+ * Check if the given Evas Object is an Elementary widget.
*
- * @param th The theme to get the reference from
- * @return The referenced theme handle
- *
- * This gets the theme set as the reference theme by elm_theme_ref_set().
- * If no theme is set as a reference, NULL is returned.
+ * @param obj the object to query.
+ * @return @c EINA_TRUE if it is an elementary widget variant,
+ * @c EINA_FALSE otherwise
+ * @ingroup WidgetNavigation
*/
- EAPI Elm_Theme *elm_theme_ref_get(Elm_Theme *th);
+ EAPI Eina_Bool elm_object_widget_check(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Return the default theme
+ * Get the first parent of the given object that is an Elementary
+ * widget.
*
- * @return The default theme handle
+ * @param obj the Elementary object to query parent from.
+ * @return the parent object that is an Elementary widget, or @c
+ * NULL, if it was not found.
*
- * This returns the internal default theme setup handle that all widgets
- * use implicitly unless a specific theme is set. This is also often use
- * as a shorthand of NULL.
+ * Use this to query for an object's parent widget.
+ *
+ * @note Most of Elementary users wouldn't be mixing non-Elementary
+ * smart objects in the objects tree of an application, as this is
+ * an advanced usage of Elementary with Evas. So, except for the
+ * application's window, which is the root of that tree, all other
+ * objects would have valid Elementary widget parents.
+ *
+ * @ingroup WidgetNavigation
*/
- EAPI Elm_Theme *elm_theme_default_get(void);
+ EAPI Evas_Object *elm_object_parent_widget_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Prepends a theme overlay to the list of overlays
+ * Get the top level parent of an Elementary widget.
*
- * @param th The theme to add to, or if NULL, the default theme
- * @param item The Edje file path to be used
+ * @param obj The object to query.
+ * @return The top level Elementary widget, or @c NULL if parent cannot be
+ * found.
+ * @ingroup WidgetNavigation
+ */
+ EAPI Evas_Object *elm_object_top_widget_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the string that represents this Elementary widget.
*
- * Use this if your application needs to provide some custom overlay theme
- * (An Edje file that replaces some default styles of widgets) where adding
- * new styles, or changing system theme configuration is not possible. Do
- * NOT use this instead of a proper system theme configuration. Use proper
- * configuration files, profiles, environment variables etc. to set a theme
- * so that the theme can be altered by simple confiugration by a user. Using
- * this call to achieve that effect is abusing the API and will create lots
- * of trouble.
+ * @note Elementary is weird and exposes itself as a single
+ * Evas_Object_Smart_Class of type "elm_widget", so
+ * evas_object_type_get() always return that, making debug and
+ * language bindings hard. This function tries to mitigate this
+ * problem, but the solution is to change Elementary to use
+ * proper inheritance.
*
- * @see elm_theme_extension_add()
+ * @param obj the object to query.
+ * @return Elementary widget name, or @c NULL if not a valid widget.
+ * @ingroup WidgetNavigation
*/
- EAPI void elm_theme_overlay_add(Elm_Theme *th, const char *item);
+ EAPI const char *elm_object_widget_type_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Delete a theme overlay from the list of overlays
+ * @defgroup Config Elementary Config
*
- * @param th The theme to delete from, or if NULL, the default theme
- * @param item The name of the theme overlay
+ * Elementary configuration is formed by a set options bounded to a
+ * given @ref Profile profile, like @ref Theme theme, @ref Fingers
+ * "finger size", etc. These are functions with which one syncronizes
+ * changes made to those values to the configuration storing files, de
+ * facto. You most probably don't want to use the functions in this
+ * group unlees you're writing an elementary configuration manager.
*
- * @see elm_theme_overlay_add()
+ * @{
*/
- EAPI void elm_theme_overlay_del(Elm_Theme *th, const char *item);
+
/**
- * Appends a theme extension to the list of extensions.
+ * Save back Elementary's configuration, so that it will persist on
+ * future sessions.
*
- * @param th The theme to add to, or if NULL, the default theme
- * @param item The Edje file path to be used
+ * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
+ * @ingroup Config
*
- * This is intended when an application needs more styles of widgets or new
- * widget themes that the default does not provide (or may not provide). The
- * application has "extended" usage by coming up with new custom style names
- * for widgets for specific uses, but as these are not "standard", they are
- * not guaranteed to be provided by a default theme. This means the
- * application is required to provide these extra elements itself in specific
- * Edje files. This call adds one of those Edje files to the theme search
- * path to be search after the default theme. The use of this call is
- * encouraged when default styles do not meet the needs of the application.
- * Use this call instead of elm_theme_overlay_add() for almost all cases.
+ * This function will take effect -- thus, do I/O -- immediately. Use
+ * it when you want to apply all configuration changes at once. The
+ * current configuration set will get saved onto the current profile
+ * configuration file.
*
- * @see elm_object_style_set()
*/
- EAPI void elm_theme_extension_add(Elm_Theme *th, const char *item);
+ EAPI Eina_Bool elm_config_save(void);
+
/**
- * Deletes a theme extension from the list of extensions.
+ * Reload Elementary's configuration, bounded to current selected
+ * profile.
*
- * @param th The theme to delete from, or if NULL, the default theme
- * @param item The name of the theme extension
+ * @return @c EINA_TRUE, when sucessful. @c EINA_FALSE, otherwise.
+ * @ingroup Config
+ *
+ * Useful when you want to force reloading of configuration values for
+ * a profile. If one removes user custom configuration directories,
+ * for example, it will force a reload with system values insted.
*
- * @see elm_theme_extension_add()
*/
- EAPI void elm_theme_extension_del(Elm_Theme *th, const char *item);
+ EAPI void elm_config_reload(void);
+
/**
- * Set the theme search order for the given theme
- *
- * @param th The theme to set the search order, or if NULL, the default theme
- * @param theme Theme search string
+ * @}
+ */
+
+ /**
+ * @defgroup Profile Elementary Profile
*
- * This sets the search string for the theme in path-notation from first
- * theme to search, to last, delimited by the : character. Example:
+ * Profiles are pre-set options that affect the whole look-and-feel of
+ * Elementary-based applications. There are, for example, profiles
+ * aimed at desktop computer applications and others aimed at mobile,
+ * touchscreen-based ones. You most probably don't want to use the
+ * functions in this group unlees you're writing an elementary
+ * configuration manager.
*
- * "shiny:/path/to/file.edj:default"
+ * @{
+ */
+
+ /**
+ * Get Elementary's profile in use.
*
- * See the ELM_THEME environment variable for more information.
+ * This gets the global profile that is applied to all Elementary
+ * applications.
*
- * @see elm_theme_get()
- * @see elm_theme_list_get()
+ * @return The profile's name
+ * @ingroup Profile
*/
- EAPI void elm_theme_set(Elm_Theme *th, const char *theme);
+ EAPI const char *elm_profile_current_get(void);
+
/**
- * Return the theme search order
+ * Get an Elementary's profile directory path in the filesystem. One
+ * may want to fetch a system profile's dir or an user one (fetched
+ * inside $HOME).
*
- * @param th The theme to get the search order, or if NULL, the default theme
- * @return The internal search order path
+ * @param profile The profile's name
+ * @param is_user Whether to lookup for an user profile (@c EINA_TRUE)
+ * or a system one (@c EINA_FALSE)
+ * @return The profile's directory path.
+ * @ingroup Profile
*
- * This function returns a colon separated string of theme elements as
- * returned by elm_theme_list_get().
+ * @note You must free it with elm_profile_dir_free().
+ */
+ EAPI const char *elm_profile_dir_get(const char *profile, Eina_Bool is_user);
+
+ /**
+ * Free an Elementary's profile directory path, as returned by
+ * elm_profile_dir_get().
+ *
+ * @param p_dir The profile's path
+ * @ingroup Profile
*
- * @see elm_theme_set()
- * @see elm_theme_list_get()
*/
- EAPI const char *elm_theme_get(Elm_Theme *th);
+ EAPI void elm_profile_dir_free(const char *p_dir);
+
/**
- * Return a list of theme elements to be used in a theme.
+ * Get Elementary's list of available profiles.
*
- * @param th Theme to get the list of theme elements from.
- * @return The internal list of theme elements
+ * @return The profiles list. List node data are the profile name
+ * strings.
+ * @ingroup Profile
*
- * This returns the internal list of theme elements (will only be valid as
- * long as the theme is not modified by elm_theme_set() or theme is not
- * freed by elm_theme_free(). This is a list of strings which must not be
- * altered as they are also internal. If @p th is NULL, then the default
- * theme element list is returned.
+ * @note One must free this list, after usage, with the function
+ * elm_profile_list_free().
+ */
+ EAPI Eina_List *elm_profile_list_get(void);
+
+ /**
+ * Free Elementary's list of available profiles.
*
- * A theme element can consist of a full or relative path to a .edj file,
- * or a name, without extension, for a theme to be searched in the known
- * theme paths for Elemementary.
+ * @param l The profiles list, as returned by elm_profile_list_get().
+ * @ingroup Profile
*
- * @see elm_theme_set()
- * @see elm_theme_get()
*/
- EAPI const Eina_List *elm_theme_list_get(const Elm_Theme *th);
+ EAPI void elm_profile_list_free(Eina_List *l);
+
/**
- * Return the full patrh for a theme element
+ * Set Elementary's profile.
*
- * @param f The theme element name
- * @param in_search_path Pointer to a boolean to indicate if item is in the search path or not
- * @return The full path to the file found.
+ * This sets the global profile that is applied to Elementary
+ * applications. Just the process the call comes from will be
+ * affected.
+ *
+ * @param profile The profile's name
+ * @ingroup Profile
*
- * This returns a string you should free with free() on success, NULL on
- * failure. This will search for the given theme element, and if it is a
- * full or relative path element or a simple searchable name. The returned
- * path is the full path to the file, if searched, and the file exists, or it
- * is simply the full path given in the element or a resolved path if
- * relative to home. The @p in_search_path boolean pointed to is set to
- * EINA_TRUE if the file was a searchable file andis in the search path,
- * and EINA_FALSE otherwise.
*/
- EAPI char *elm_theme_list_item_path_get(const char *f, Eina_Bool *in_search_path);
+ EAPI void elm_profile_set(const char *profile);
+
/**
- * Flush the current theme.
+ * Set Elementary's profile.
*
- * @param th Theme to flush
+ * This sets the global profile that is applied to all Elementary
+ * applications. All running Elementary windows will be affected.
+ *
+ * @param profile The profile's name
+ * @ingroup Profile
*
- * This flushes caches that let elementary know where to find theme elements
- * in the given theme. If @p th is NULL, then the default theme is flushed.
- * Call this function if source theme data has changed in such a way as to
- * make any caches Elementary kept invalid.
*/
- EAPI void elm_theme_flush(Elm_Theme *th);
+ EAPI void elm_profile_all_set(const char *profile);
+
/**
- * This flushes all themes (default and specific ones).
+ * @}
+ */
+
+ /**
+ * @defgroup Engine Elementary Engine
*
- * This will flush all themes in the current application context, by calling
- * elm_theme_flush() on each of them.
+ * These are functions setting and querying which rendering engine
+ * Elementary will use for drawing its windows' pixels.
+ *
+ * The following are the available engines:
+ * @li "software_x11"
+ * @li "fb"
+ * @li "directfb"
+ * @li "software_16_x11"
+ * @li "software_8_x11"
+ * @li "xrender_x11"
+ * @li "opengl_x11"
+ * @li "software_gdi"
+ * @li "software_16_wince_gdi"
+ * @li "sdl"
+ * @li "software_16_sdl"
+ * @li "opengl_sdl"
+ * @li "buffer"
+ *
+ * @{
*/
- EAPI void elm_theme_full_flush(void);
+
/**
- * Set the theme for all elementary using applications on the current display
+ * @brief Get Elementary's rendering engine in use.
*
- * @param theme The name of the theme to use. Format same as the ELM_THEME
- * environment variable.
+ * @return The rendering engine's name
+ * @note there's no need to free the returned string, here.
+ *
+ * This gets the global rendering engine that is applied to all Elementary
+ * applications.
+ *
+ * @see elm_engine_set()
*/
- EAPI void elm_theme_all_set(const char *theme);
+ EAPI const char *elm_engine_current_get(void);
+
/**
- * Return a list of theme elements in the theme search path
+ * @brief Set Elementary's rendering engine for use.
*
- * @return A list of strings that are the theme element names.
+ * @param engine The rendering engine's name
*
- * This lists all available theme files in the standard Elementary search path
- * for theme elements, and returns them in alphabetical order as theme
- * element names in a list of strings. Free this with
- * elm_theme_name_available_list_free() when you are done with the list.
+ * This sets global rendering engine that is applied to all Elementary
+ * applications. Note that it will take effect only to Elementary windows
+ * created after this is called.
+ *
+ * @see elm_win_add()
*/
- EAPI Eina_List *elm_theme_name_available_list_new(void);
+ EAPI void elm_engine_set(const char *engine);
+
/**
- * Free the list returned by elm_theme_name_available_list_new()
+ * @}
+ */
+
+ /**
+ * @defgroup Fonts Elementary Fonts
*
- * This frees the list of themes returned by
- * elm_theme_name_available_list_new(). Once freed the list should no longer
- * be used. a new list mys be created.
+ * These are functions dealing with font rendering, selection and the
+ * like for Elementary applications. One might fetch which system
+ * fonts are there to use and set custom fonts for individual classes
+ * of UI items containing text (text classes).
+ *
+ * @{
*/
- EAPI void elm_theme_name_available_list_free(Eina_List *list);
+
+ typedef struct _Elm_Text_Class
+ {
+ const char *name;
+ const char *desc;
+ } Elm_Text_Class;
+
+ typedef struct _Elm_Font_Overlay
+ {
+ const char *text_class;
+ const char *font;
+ Evas_Font_Size size;
+ } Elm_Font_Overlay;
+
+ typedef struct _Elm_Font_Properties
+ {
+ const char *name;
+ Eina_List *styles;
+ } Elm_Font_Properties;
+
/**
- * Set a specific theme to be used for this object and its children
+ * Get Elementary's list of supported text classes.
*
- * @param obj The object to set the theme on
- * @param th The theme to set
+ * @return The text classes list, with @c Elm_Text_Class blobs as data.
+ * @ingroup Fonts
*
- * This sets a specific theme that will be used for the given object and any
- * child objects it has. If @p th is NULL then the theme to be used is
- * cleared and the object will inherit its theme from its parent (which
- * ultimately will use the default theme if no specific themes are set).
+ * Release the list with elm_text_classes_list_free().
+ */
+ EAPI const Eina_List *elm_text_classes_list_get(void);
+
+ /**
+ * Free Elementary's list of supported text classes.
*
- * Use special themes with great care as this will annoy users and make
- * configuration difficult. Avoid any custom themes at all if it can be
- * helped.
+ * @ingroup Fonts
+ *
+ * @see elm_text_classes_list_get().
*/
- EAPI void elm_object_theme_set(Evas_Object *obj, Elm_Theme *th) EINA_ARG_NONNULL(1);
+ EAPI void elm_text_classes_list_free(const Eina_List *list);
+
/**
- * Get the specific theme to be used
+ * Get Elementary's list of font overlays, set with
+ * elm_font_overlay_set().
*
- * @param obj The object to get the specific theme from
- * @return The specifc theme set.
+ * @return The font overlays list, with @c Elm_Font_Overlay blobs as
+ * data.
*
- * This will return a specific theme set, or NULL if no specific theme is
- * set on that object. It will not return inherited themes from parents, only
- * the specific theme set for that specific object. See elm_object_theme_set()
- * for more information.
+ * @ingroup Fonts
+ *
+ * For each text class, one can set a <b>font overlay</b> for it,
+ * overriding the default font properties for that class coming from
+ * the theme in use. There is no need to free this list.
+ *
+ * @see elm_font_overlay_set() and elm_font_overlay_unset().
*/
- EAPI Elm_Theme *elm_object_theme_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const Eina_List *elm_font_overlay_list_get(void);
+
/**
- * @}
+ * Set a font overlay for a given Elementary text class.
+ *
+ * @param text_class Text class name
+ * @param font Font name and style string
+ * @param size Font size
+ *
+ * @ingroup Fonts
+ *
+ * @p font has to be in the format returned by
+ * elm_font_fontconfig_name_get(). @see elm_font_overlay_list_get()
+ * and elm_font_overlay_unset().
*/
+ EAPI void elm_font_overlay_set(const char *text_class, const char *font, Evas_Font_Size size);
- /* win */
- /** @defgroup Win Win
+ /**
+ * Unset a font overlay for a given Elementary text class.
*
- * @image html img/widget/win/preview-00.png
- * @image latex img/widget/win/preview-00.eps
+ * @param text_class Text class name
*
- * The window class of Elementary. Contains functions to manipulate
- * windows. The Evas engine used to render the window contents is specified
- * in the system or user elementary config files (whichever is found last),
- * and can be overridden with the ELM_ENGINE environment variable for
- * testing. Engines that may be supported (depending on Evas and Ecore-Evas
- * compilation setup and modules actually installed at runtime) are (listed
- * in order of best supported and most likely to be complete and work to
- * lowest quality).
- *
- * @li "x11", "x", "software-x11", "software_x11" (Software rendering in X11)
- * @li "gl", "opengl", "opengl-x11", "opengl_x11" (OpenGL or OpenGL-ES2
- * rendering in X11)
- * @li "shot:..." (Virtual screenshot renderer - renders to output file and
- * exits)
- * @li "fb", "software-fb", "software_fb" (Linux framebuffer direct software
- * rendering)
- * @li "sdl", "software-sdl", "software_sdl" (SDL software rendering to SDL
- * buffer)
- * @li "gl-sdl", "gl_sdl", "opengl-sdl", "opengl_sdl" (OpenGL or OpenGL-ES2
- * rendering using SDL as the buffer)
- * @li "gdi", "software-gdi", "software_gdi" (Windows WIN32 rendering via
- * GDI with software)
- * @li "dfb", "directfb" (Rendering to a DirectFB window)
- * @li "x11-8", "x8", "software-8-x11", "software_8_x11" (Rendering in
- * grayscale using dedicated 8bit software engine in X11)
- * @li "x11-16", "x16", "software-16-x11", "software_16_x11" (Rendering in
- * X11 using 16bit software engine)
- * @li "wince-gdi", "software-16-wince-gdi", "software_16_wince_gdi"
- * (Windows CE rendering via GDI with 16bit software renderer)
- * @li "sdl-16", "software-16-sdl", "software_16_sdl" (Rendering to SDL
- * buffer with 16bit software renderer)
+ * @ingroup Fonts
*
- * All engines use a simple string to select the engine to render, EXCEPT
- * the "shot" engine. This actually encodes the output of the virtual
- * screenshot and how long to delay in the engine string. The engine string
- * is encoded in the following way:
+ * This will bring back text elements belonging to text class
+ * @p text_class back to their default font settings.
+ */
+ EAPI void elm_font_overlay_unset(const char *text_class);
+
+ /**
+ * Apply the changes made with elm_font_overlay_set() and
+ * elm_font_overlay_unset() on the current Elementary window.
*
- * "shot:[delay=XX][:][repeat=DDD][:][file=XX]"
+ * @ingroup Fonts
*
- * Where options are separated by a ":" char if more than one option is
- * given, with delay, if provided being the first option and file the last
- * (order is important). The delay specifies how long to wait after the
- * window is shown before doing the virtual "in memory" rendering and then
- * save the output to the file specified by the file option (and then exit).
- * If no delay is given, the default is 0.5 seconds. If no file is given the
- * default output file is "out.png". Repeat option is for continous
- * capturing screenshots. Repeat range is from 1 to 999 and filename is
- * fixed to "out001.png" Some examples of using the shot engine:
+ * This applies all font overlays set to all objects in the UI.
+ */
+ EAPI void elm_font_overlay_apply(void);
+
+ /**
+ * Apply the changes made with elm_font_overlay_set() and
+ * elm_font_overlay_unset() on all Elementary application windows.
*
- * ELM_ENGINE="shot:delay=1.0:repeat=5:file=elm_test.png" elementary_test
- * ELM_ENGINE="shot:delay=1.0:file=elm_test.png" elementary_test
- * ELM_ENGINE="shot:file=elm_test2.png" elementary_test
- * ELM_ENGINE="shot:delay=2.0" elementary_test
- * ELM_ENGINE="shot:" elementary_test
+ * @ingroup Fonts
*
- * Signals that you can add callbacks for are:
+ * This applies all font overlays set to all objects in the UI.
+ */
+ EAPI void elm_font_overlay_all_apply(void);
+
+ /**
+ * Translate a font (family) name string in fontconfig's font names
+ * syntax into an @c Elm_Font_Properties struct.
*
- * @li "delete,request": the user requested to close the window. See
- * elm_win_autodel_set().
- * @li "focus,in": window got focus
- * @li "focus,out": window lost focus
- * @li "moved": window that holds the canvas was moved
+ * @param font The font name and styles string
+ * @return the font properties struct
*
- * Examples:
- * @li @ref win_example_01
+ * @ingroup Fonts
*
- * @{
+ * @note The reverse translation can be achived with
+ * elm_font_fontconfig_name_get(), for one style only (single font
+ * instance, not family).
*/
+ EAPI Elm_Font_Properties *elm_font_properties_get(const char *font) EINA_ARG_NONNULL(1);
+
/**
- * Defines the types of window that can be created
+ * Free font properties return by elm_font_properties_get().
*
- * These are hints set on the window so that a running Window Manager knows
- * how the window should be handled and/or what kind of decorations it
- * should have.
+ * @param efp the font properties struct
*
- * Currently, only the X11 backed engines use them.
+ * @ingroup Fonts
*/
- typedef enum _Elm_Win_Type
- {
- ELM_WIN_BASIC, /**< A normal window. Indicates a normal, top-level
- window. Almost every window will be created with this
- type. */
- ELM_WIN_DIALOG_BASIC, /**< Used for simple dialog windows/ */
- ELM_WIN_DESKTOP, /**< For special desktop windows, like a background
- window holding desktop icons. */
- ELM_WIN_DOCK, /**< The window is used as a dock or panel. Usually would
- be kept on top of any other window by the Window
- Manager. */
- ELM_WIN_TOOLBAR, /**< The window is used to hold a floating toolbar, or
- similar. */
- ELM_WIN_MENU, /**< Similar to #ELM_WIN_TOOLBAR. */
- ELM_WIN_UTILITY, /**< A persistent utility window, like a toolbox or
- pallete. */
- ELM_WIN_SPLASH, /**< Splash window for a starting up application. */
- ELM_WIN_DROPDOWN_MENU, /**< The window is a dropdown menu, as when an
- entry in a menubar is clicked. Typically used
- with elm_win_override_set(). This hint exists
- for completion only, as the EFL way of
- implementing a menu would not normally use a
- separate window for its contents. */
- ELM_WIN_POPUP_MENU, /**< Like #ELM_WIN_DROPDOWN_MENU, but for the menu
- triggered by right-clicking an object. */
- ELM_WIN_TOOLTIP, /**< The window is a tooltip. A short piece of
- explanatory text that typically appear after the
- mouse cursor hovers over an object for a while.
- Typically used with elm_win_override_set() and also
- not very commonly used in the EFL. */
- ELM_WIN_NOTIFICATION, /**< A notification window, like a warning about
- battery life or a new E-Mail received. */
- ELM_WIN_COMBO, /**< A window holding the contents of a combo box. Not
- usually used in the EFL. */
- ELM_WIN_DND, /**< Used to indicate the window is a representation of an
- object being dragged across different windows, or even
- applications. Typically used with
- elm_win_override_set(). */
- ELM_WIN_INLINED_IMAGE, /**< The window is rendered onto an image
- buffer. No actual window is created for this
- type, instead the window and all of its
- contents will be rendered to an image buffer.
- This allows to have children window inside a
- parent one just like any other object would
- be, and do other things like applying @c
- Evas_Map effects to it. This is the only type
- of window that requires the @c parent
- parameter of elm_win_add() to be a valid @c
- Evas_Object. */
- } Elm_Win_Type;
+ EAPI void elm_font_properties_free(Elm_Font_Properties *efp) EINA_ARG_NONNULL(1);
/**
- * The differents layouts that can be requested for the virtual keyboard.
+ * Translate a font name, bound to a style, into fontconfig's font names
+ * syntax.
*
- * When the application window is being managed by Illume, it may request
- * any of the following layouts for the virtual keyboard.
+ * @param name The font (family) name
+ * @param style The given style (may be @c NULL)
+ *
+ * @return the font name and style string
+ *
+ * @ingroup Fonts
+ *
+ * @note The reverse translation can be achived with
+ * elm_font_properties_get(), for one style only (single font
+ * instance, not family).
*/
- typedef enum _Elm_Win_Keyboard_Mode
- {
- ELM_WIN_KEYBOARD_UNKNOWN, /**< Unknown keyboard state */
- ELM_WIN_KEYBOARD_OFF, /**< Request to deactivate the keyboard */
- ELM_WIN_KEYBOARD_ON, /**< Enable keyboard with default layout */
- ELM_WIN_KEYBOARD_ALPHA, /**< Alpha (a-z) keyboard layout */
- ELM_WIN_KEYBOARD_NUMERIC, /**< Numeric keyboard layout */
- ELM_WIN_KEYBOARD_PIN, /**< PIN keyboard layout */
- ELM_WIN_KEYBOARD_PHONE_NUMBER, /**< Phone keyboard layout */
- ELM_WIN_KEYBOARD_HEX, /**< Hexadecimal numeric keyboard layout */
- ELM_WIN_KEYBOARD_TERMINAL, /**< Full (QUERTY) keyboard layout */
- ELM_WIN_KEYBOARD_PASSWORD, /**< Password keyboard layout */
- ELM_WIN_KEYBOARD_IP, /**< IP keyboard layout */
- ELM_WIN_KEYBOARD_HOST, /**< Host keyboard layout */
- ELM_WIN_KEYBOARD_FILE, /**< File keyboard layout */
- ELM_WIN_KEYBOARD_URL, /**< URL keyboard layout */
- ELM_WIN_KEYBOARD_KEYPAD, /**< Keypad layout */
- ELM_WIN_KEYBOARD_J2ME /**< J2ME keyboard layout */
- } Elm_Win_Keyboard_Mode;
+ EAPI const char *elm_font_fontconfig_name_get(const char *name, const char *style) EINA_ARG_NONNULL(1);
/**
- * Available commands that can be sent to the Illume manager.
+ * Free the font string return by elm_font_fontconfig_name_get().
*
- * When running under an Illume session, a window may send commands to the
- * Illume manager to perform different actions.
+ * @param efp the font properties struct
+ *
+ * @ingroup Fonts
*/
- typedef enum _Elm_Illume_Command
- {
- ELM_ILLUME_COMMAND_FOCUS_BACK, /**< Reverts focus to the previous
- window */
- ELM_ILLUME_COMMAND_FOCUS_FORWARD, /**< Sends focus to the next window\
- in the list */
- ELM_ILLUME_COMMAND_FOCUS_HOME, /**< Hides all windows to show the Home
- screen */
- ELM_ILLUME_COMMAND_CLOSE /**< Closes the currently active window */
- } Elm_Illume_Command;
+ EAPI void elm_font_fontconfig_name_free(const char *name) EINA_ARG_NONNULL(1);
/**
- * Adds a window object. If this is the first window created, pass NULL as
- * @p parent.
+ * Create a font hash table of available system fonts.
*
- * @param parent Parent object to add the window to, or NULL
- * @param name The name of the window
- * @param type The window type, one of #Elm_Win_Type.
+ * One must call it with @p list being the return value of
+ * evas_font_available_list(). The hash will be indexed by font
+ * (family) names, being its values @c Elm_Font_Properties blobs.
*
- * The @p parent paramter can be @c NULL for every window @p type except
- * #ELM_WIN_INLINED_IMAGE, which needs a parent to retrieve the canvas on
- * which the image object will be created.
+ * @param list The list of available system fonts, as returned by
+ * evas_font_available_list().
+ * @return the font hash.
*
- * @return The created object, or NULL on failure
+ * @ingroup Fonts
+ *
+ * @note The user is supposed to get it populated at least with 3
+ * default font families (Sans, Serif, Monospace), which should be
+ * present on most systems.
*/
- EAPI Evas_Object *elm_win_add(Evas_Object *parent, const char *name, Elm_Win_Type type);
+ EAPI Eina_Hash *elm_font_available_hash_add(Eina_List *list);
+
/**
- * Add @p subobj as a resize object of window @p obj.
+ * Free the hash return by elm_font_available_hash_add().
*
+ * @param hash the hash to be freed.
*
- * Setting an object as a resize object of the window means that the
- * @p subobj child's size and position will be controlled by the window
- * directly. That is, the object will be resized to match the window size
- * and should never be moved or resized manually by the developer.
+ * @ingroup Fonts
+ */
+ EAPI void elm_font_available_hash_del(Eina_Hash *hash);
+
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Fingers Fingers
*
- * In addition, resize objects of the window control what the minimum size
- * of it will be, as well as whether it can or not be resized by the user.
+ * Elementary is designed to be finger-friendly for touchscreens,
+ * and so in addition to scaling for display resolution, it can
+ * also scale based on finger "resolution" (or size). You can then
+ * customize the granularity of the areas meant to receive clicks
+ * on touchscreens.
*
- * For the end user to be able to resize a window by dragging the handles
- * or borders provided by the Window Manager, or using any other similar
- * mechanism, all of the resize objects in the window should have their
- * evas_object_size_hint_weight_set() set to EVAS_HINT_EXPAND.
+ * Different profiles may have pre-set values for finger sizes.
*
- * @param obj The window object
- * @param subobj The resize object to add
+ * @ref general_functions_example_page "This" example contemplates
+ * some of these functions.
+ *
+ * @{
*/
- EAPI void elm_win_resize_object_add(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
+
/**
- * Delete @p subobj as a resize object of window @p obj.
+ * Get the configured "finger size"
*
- * This function removes the object @p subobj from the resize objects of
- * the window @p obj. It will not delete the object itself, which will be
- * left unmanaged and should be deleted by the developer, manually handled
- * or set as child of some other container.
+ * @return The finger size
*
- * @param obj The window object
- * @param subobj The resize object to add
+ * This gets the globally configured finger size, <b>in pixels</b>
+ *
+ * @ingroup Fingers
*/
- EAPI void elm_win_resize_object_del(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Coord elm_finger_size_get(void);
+
/**
- * Set the title of the window
+ * Set the configured finger size
*
- * @param obj The window object
- * @param title The title to set
+ * This sets the globally configured finger size in pixels
+ *
+ * @param size The finger size
+ * @ingroup Fingers
*/
- EAPI void elm_win_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
+ EAPI void elm_finger_size_set(Evas_Coord size);
+
/**
- * Get the title of the window
+ * Set the configured finger size for all applications on the display
*
- * The returned string is an internal one and should not be freed or
- * modified. It will also be rendered invalid if a new title is set or if
- * the window is destroyed.
+ * This sets the globally configured finger size in pixels for all
+ * applications on the display
*
- * @param obj The window object
- * @return The title
+ * @param size The finger size
+ * @ingroup Fingers
*/
- EAPI const char *elm_win_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_finger_size_all_set(Evas_Coord size);
+
/**
- * Set the window's autodel state.
+ * @}
+ */
+
+ /**
+ * @defgroup Focus Focus
*
- * When closing the window in any way outside of the program control, like
- * pressing the X button in the titlebar or using a command from the
- * Window Manager, a "delete,request" signal is emitted to indicate that
- * this event occurred and the developer can take any action, which may
- * include, or not, destroying the window object.
+ * An Elementary application has, at all times, one (and only one)
+ * @b focused object. This is what determines where the input
+ * events go to within the application's window. Also, focused
+ * objects can be decorated differently, in order to signal to the
+ * user where the input is, at a given moment.
*
- * When the @p autodel parameter is set, the window will be automatically
- * destroyed when this event occurs, after the signal is emitted.
- * If @p autodel is @c EINA_FALSE, then the window will not be destroyed
- * and is up to the program to do so when it's required.
+ * Elementary applications also have the concept of <b>focus
+ * chain</b>: one can cycle through all the windows' focusable
+ * objects by input (tab key) or programmatically. The default
+ * focus chain for an application is the one define by the order in
+ * which the widgets where added in code. One will cycle through
+ * top level widgets, and, for each one containg sub-objects, cycle
+ * through them all, before returning to the level
+ * above. Elementary also allows one to set @b custom focus chains
+ * for their applications.
*
- * @param obj The window object
- * @param autodel If true, the window will automatically delete itself when
- * closed
+ * Besides the focused decoration a widget may exhibit, when it
+ * gets focus, Elementary has a @b global focus highlight object
+ * that can be enabled for a window. If one chooses to do so, this
+ * extra highlight effect will surround the current focused object,
+ * too.
+ *
+ * @note Some Elementary widgets are @b unfocusable, after
+ * creation, by their very nature: they are not meant to be
+ * interacted with input events, but are there just for visual
+ * purposes.
+ *
+ * @ref general_functions_example_page "This" example contemplates
+ * some of these functions.
*/
- EAPI void elm_win_autodel_set(Evas_Object *obj, Eina_Bool autodel) EINA_ARG_NONNULL(1);
+
/**
- * Get the window's autodel state.
- *
- * @param obj The window object
- * @return If the window will automatically delete itself when closed
+ * Get the enable status of the focus highlight
*
- * @see elm_win_autodel_set()
+ * This gets whether the highlight on focused objects is enabled or not
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_autodel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_focus_highlight_enabled_get(void);
+
/**
- * Activate a window object.
+ * Set the enable status of the focus highlight
*
- * This function sends a request to the Window Manager to activate the
- * window pointed by @p obj. If honored by the WM, the window will receive
- * the keyboard focus.
+ * Set whether to show or not the highlight on focused objects
+ * @param enable Enable highlight if EINA_TRUE, disable otherwise
+ * @ingroup Focus
+ */
+ EAPI void elm_focus_highlight_enabled_set(Eina_Bool enable);
+
+ /**
+ * Get the enable status of the highlight animation
*
- * @note This is just a request that a Window Manager may ignore, so calling
- * this function does not ensure in any way that the window will be the
- * active one after it.
+ * Get whether the focus highlight, if enabled, will animate its switch from
+ * one object to the next
+ * @ingroup Focus
+ */
+ EAPI Eina_Bool elm_focus_highlight_animate_get(void);
+
+ /**
+ * Set the enable status of the highlight animation
*
- * @param obj The window object
+ * Set whether the focus highlight, if enabled, will animate its switch from
+ * one object to the next
+ * @param animate Enable animation if EINA_TRUE, disable otherwise
+ * @ingroup Focus
*/
- EAPI void elm_win_activate(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_focus_highlight_animate_set(Eina_Bool animate);
+
/**
- * Lower a window object.
+ * Get the whether an Elementary object has the focus or not.
*
- * Places the window pointed by @p obj at the bottom of the stack, so that
- * no other window is covered by it.
+ * @param obj The Elementary object to get the information from
+ * @return @c EINA_TRUE, if the object is focused, @c EINA_FALSE if
+ * not (and on errors).
*
- * If elm_win_override_set() is not set, the Window Manager may ignore this
- * request.
+ * @see elm_object_focus_set()
*
- * @param obj The window object
+ * @ingroup Focus
*/
- EAPI void elm_win_lower(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_object_focus_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Raise a window object.
+ * Set/unset focus to a given Elementary object.
*
- * Places the window pointed by @p obj at the top of the stack, so that it's
- * not covered by any other window.
+ * @param obj The Elementary object to operate on.
+ * @param enable @c EINA_TRUE Set focus to a given object,
+ * @c EINA_FALSE Unset focus to a given object.
*
- * If elm_win_override_set() is not set, the Window Manager may ignore this
- * request.
+ * @note When you set focus to this object, if it can handle focus, will
+ * take the focus away from the one who had it previously and will, for
+ * now on, be the one receiving input events. Unsetting focus will remove
+ * the focus from @p obj, passing it back to the previous element in the
+ * focus chain list.
*
- * @param obj The window object
+ * @see elm_object_focus_get(), elm_object_focus_custom_chain_get()
+ *
+ * @ingroup Focus
*/
- EAPI void elm_win_raise(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_set(Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
+
/**
- * Set the borderless state of a window.
+ * Make a given Elementary object the focused one.
*
- * This function requests the Window Manager to not draw any decoration
- * around the window.
+ * @param obj The Elementary object to make focused.
*
- * @param obj The window object
- * @param borderless If true, the window is borderless
- */
- EAPI void elm_win_borderless_set(Evas_Object *obj, Eina_Bool borderless) EINA_ARG_NONNULL(1);
- /**
- * Get the borderless state of a window.
+ * @note This object, if it can handle focus, will take the focus
+ * away from the one who had it previously and will, for now on, be
+ * the one receiving input events.
*
- * @param obj The window object
- * @return If true, the window is borderless
+ * @see elm_object_focus_get()
+ * @deprecated use elm_object_focus_set() instead.
+ *
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_borderless_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI void elm_object_focus(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Set the shaped state of a window.
+ * Remove the focus from an Elementary object
*
- * Shaped windows, when supported, will render the parts of the window that
- * has no content, transparent.
+ * @param obj The Elementary to take focus from
*
- * If @p shaped is EINA_FALSE, then it is strongly adviced to have some
- * background object or cover the entire window in any other way, or the
- * parts of the canvas that have no data will show framebuffer artifacts.
+ * This removes the focus from @p obj, passing it back to the
+ * previous element in the focus chain list.
*
- * @param obj The window object
- * @param shaped If true, the window is shaped
+ * @see elm_object_focus() and elm_object_focus_custom_chain_get()
+ * @deprecated use elm_object_focus_set() instead.
*
- * @see elm_win_alpha_set()
+ * @ingroup Focus
*/
- EAPI void elm_win_shaped_set(Evas_Object *obj, Eina_Bool shaped) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI void elm_object_unfocus(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Get the shaped state of a window.
+ * Set the ability for an Element object to be focused
*
- * @param obj The window object
- * @return If true, the window is shaped
+ * @param obj The Elementary object to operate on
+ * @param enable @c EINA_TRUE if the object can be focused, @c
+ * EINA_FALSE if not (and on errors)
*
- * @see elm_win_shaped_set()
+ * This sets whether the object @p obj is able to take focus or
+ * not. Unfocusable objects do nothing when programmatically
+ * focused, being the nearest focusable parent object the one
+ * really getting focus. Also, when they receive mouse input, they
+ * will get the event, but not take away the focus from where it
+ * was previously.
+ *
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_shaped_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
+
/**
- * Set the alpha channel state of a window.
+ * Get whether an Elementary object is focusable or not
*
- * If @p alpha is EINA_TRUE, the alpha channel of the canvas will be enabled
- * possibly making parts of the window completely or partially transparent.
- * This is also subject to the underlying system supporting it, like for
- * example, running under a compositing manager. If no compositing is
- * available, enabling this option will instead fallback to using shaped
- * windows, with elm_win_shaped_set().
+ * @param obj The Elementary object to operate on
+ * @return @c EINA_TRUE if the object is allowed to be focused, @c
+ * EINA_FALSE if not (and on errors)
*
- * @param obj The window object
- * @param alpha If true, the window has an alpha channel
+ * @note Objects which are meant to be interacted with by input
+ * events are created able to be focused, by default. All the
+ * others are not.
*
- * @see elm_win_alpha_set()
+ * @ingroup Focus
*/
- EAPI void elm_win_alpha_set(Evas_Object *obj, Eina_Bool alpha) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_object_focus_allow_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Get the transparency state of a window.
+ * Set custom focus chain.
*
- * @param obj The window object
- * @return If true, the window is transparent
+ * This function overwrites any previous custom focus chain within
+ * the list of objects. The previous list will be deleted and this list
+ * will be managed by elementary. After it is set, don't modify it.
*
- * @see elm_win_transparent_set()
+ * @note On focus cycle, only will be evaluated children of this container.
+ *
+ * @param obj The container object
+ * @param objs Chain of objects to pass focus
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_transparent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_custom_chain_set(Evas_Object *obj, Eina_List *objs) EINA_ARG_NONNULL(1);
+
/**
- * Set the transparency state of a window.
+ * Unset a custom focus chain on a given Elementary widget
*
- * Use elm_win_alpha_set() instead.
+ * @param obj The container object to remove focus chain from
*
- * @param obj The window object
- * @param transparent If true, the window is transparent
+ * Any focus chain previously set on @p obj (for its child objects)
+ * is removed entirely after this call.
*
- * @see elm_win_alpha_set()
+ * @ingroup Focus
*/
- EAPI void elm_win_transparent_set(Evas_Object *obj, Eina_Bool transparent) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_custom_chain_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Get the alpha channel state of a window.
+ * Get custom focus chain
*
- * @param obj The window object
- * @return If true, the window has an alpha channel
+ * @param obj The container object
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_alpha_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const Eina_List *elm_object_focus_custom_chain_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Set the override state of a window.
+ * Append object to custom focus chain.
*
- * A window with @p override set to EINA_TRUE will not be managed by the
- * Window Manager. This means that no decorations of any kind will be shown
- * for it, moving and resizing must be handled by the application, as well
- * as the window visibility.
+ * @note If relative_child equal to NULL or not in custom chain, the object
+ * will be added in end.
*
- * This should not be used for normal windows, and even for not so normal
- * ones, it should only be used when there's a good reason and with a lot
- * of care. Mishandling override windows may result situations that
- * disrupt the normal workflow of the end user.
+ * @note On focus cycle, only will be evaluated children of this container.
*
- * @param obj The window object
- * @param override If true, the window is overridden
+ * @param obj The container object
+ * @param child The child to be added in custom chain
+ * @param relative_child The relative object to position the child
+ * @ingroup Focus
*/
- EAPI void elm_win_override_set(Evas_Object *obj, Eina_Bool override) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_custom_chain_append(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child) EINA_ARG_NONNULL(1, 2);
+
/**
- * Get the override state of a window.
+ * Prepend object to custom focus chain.
*
- * @param obj The window object
- * @return If true, the window is overridden
+ * @note If relative_child equal to NULL or not in custom chain, the object
+ * will be added in begin.
*
- * @see elm_win_override_set()
+ * @note On focus cycle, only will be evaluated children of this container.
+ *
+ * @param obj The container object
+ * @param child The child to be added in custom chain
+ * @param relative_child The relative object to position the child
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_override_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_custom_chain_prepend(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child) EINA_ARG_NONNULL(1, 2);
+
/**
- * Set the fullscreen state of a window.
+ * Give focus to next object in object tree.
*
- * @param obj The window object
- * @param fullscreen If true, the window is fullscreen
+ * Give focus to next object in focus chain of one object sub-tree.
+ * If the last object of chain already have focus, the focus will go to the
+ * first object of chain.
+ *
+ * @param obj The object root of sub-tree
+ * @param dir Direction to cycle the focus
+ *
+ * @ingroup Focus
*/
- EAPI void elm_win_fullscreen_set(Evas_Object *obj, Eina_Bool fullscreen) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_cycle(Evas_Object *obj, Elm_Focus_Direction dir) EINA_ARG_NONNULL(1);
+
/**
- * Get the fullscreen state of a window.
+ * Give focus to near object in one direction.
*
- * @param obj The window object
- * @return If true, the window is fullscreen
+ * Give focus to near object in direction of one object.
+ * If none focusable object in given direction, the focus will not change.
+ *
+ * @param obj The reference object
+ * @param x Horizontal component of direction to focus
+ * @param y Vertical component of direction to focus
+ *
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_fullscreen_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_focus_direction_go(Evas_Object *obj, int x, int y) EINA_ARG_NONNULL(1);
+
/**
- * Set the maximized state of a window.
+ * Make the elementary object and its children to be unfocusable
+ * (or focusable).
*
- * @param obj The window object
- * @param maximized If true, the window is maximized
+ * @param obj The Elementary object to operate on
+ * @param tree_unfocusable @c EINA_TRUE for unfocusable,
+ * @c EINA_FALSE for focusable.
+ *
+ * This sets whether the object @p obj and its children objects
+ * are able to take focus or not. If the tree is set as unfocusable,
+ * newest focused object which is not in this tree will get focus.
+ * This API can be helpful for an object to be deleted.
+ * When an object will be deleted soon, it and its children may not
+ * want to get focus (by focus reverting or by other focus controls).
+ * Then, just use this API before deleting.
+ *
+ * @see elm_object_tree_unfocusable_get()
+ *
+ * @ingroup Focus
*/
- EAPI void elm_win_maximized_set(Evas_Object *obj, Eina_Bool maximized) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_tree_unfocusable_set(Evas_Object *obj, Eina_Bool tree_unfocusable); EINA_ARG_NONNULL(1);
+
/**
- * Get the maximized state of a window.
+ * Get whether an Elementary object and its children are unfocusable or not.
*
- * @param obj The window object
- * @return If true, the window is maximized
+ * @param obj The Elementary object to get the information from
+ * @return @c EINA_TRUE, if the tree is unfocussable,
+ * @c EINA_FALSE if not (and on errors).
+ *
+ * @see elm_object_tree_unfocusable_set()
+ *
+ * @ingroup Focus
*/
- EAPI Eina_Bool elm_win_maximized_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_object_tree_unfocusable_get(const Evas_Object *obj); EINA_ARG_NONNULL(1);
+
/**
- * Set the iconified state of a window.
+ * @defgroup Scrolling Scrolling
*
- * @param obj The window object
- * @param iconified If true, the window is iconified
+ * These are functions setting how scrollable views in Elementary
+ * widgets should behave on user interaction.
+ *
+ * @{
*/
- EAPI void elm_win_iconified_set(Evas_Object *obj, Eina_Bool iconified) EINA_ARG_NONNULL(1);
+
/**
- * Get the iconified state of a window.
+ * Get whether scrollers should bounce when they reach their
+ * viewport's edge during a scroll.
*
- * @param obj The window object
- * @return If true, the window is iconified
+ * @return the thumb scroll bouncing state
+ *
+ * This is the default behavior for touch screens, in general.
+ * @ingroup Scrolling
*/
- EAPI Eina_Bool elm_win_iconified_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_scroll_bounce_enabled_get(void);
+
/**
- * Set the layer of the window.
- *
- * What this means exactly will depend on the underlying engine used.
+ * Set whether scrollers should bounce when they reach their
+ * viewport's edge during a scroll.
*
- * In the case of X11 backed engines, the value in @p layer has the
- * following meanings:
- * @li < 3: The window will be placed below all others.
- * @li > 5: The window will be placed above all others.
- * @li other: The window will be placed in the default layer.
+ * @param enabled the thumb scroll bouncing state
*
- * @param obj The window object
- * @param layer The layer of the window
+ * @see elm_thumbscroll_bounce_enabled_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_layer_set(Evas_Object *obj, int layer) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_bounce_enabled_set(Eina_Bool enabled);
+
/**
- * Get the layer of the window.
+ * Set whether scrollers should bounce when they reach their
+ * viewport's edge during a scroll, for all Elementary application
+ * windows.
*
- * @param obj The window object
- * @return The layer of the window
+ * @param enabled the thumb scroll bouncing state
*
- * @see elm_win_layer_set()
+ * @see elm_thumbscroll_bounce_enabled_get()
+ * @ingroup Scrolling
*/
- EAPI int elm_win_layer_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_bounce_enabled_all_set(Eina_Bool enabled);
+
/**
- * Set the rotation of the window.
- *
- * Most engines only work with multiples of 90.
+ * Get the amount of inertia a scroller will impose at bounce
+ * animations.
*
- * This function is used to set the orientation of the window @p obj to
- * match that of the screen. The window itself will be resized to adjust
- * to the new geometry of its contents. If you want to keep the window size,
- * see elm_win_rotation_with_resize_set().
+ * @return the thumb scroll bounce friction
*
- * @param obj The window object
- * @param rotation The rotation of the window, in degrees (0-360),
- * counter-clockwise.
+ * @ingroup Scrolling
*/
- EAPI void elm_win_rotation_set(Evas_Object *obj, int rotation) EINA_ARG_NONNULL(1);
+ EAPI double elm_scroll_bounce_friction_get(void);
+
/**
- * Rotates the window and resizes it.
+ * Set the amount of inertia a scroller will impose at bounce
+ * animations.
*
- * Like elm_win_rotation_set(), but it also resizes the window's contents so
- * that they fit inside the current window geometry.
+ * @param friction the thumb scroll bounce friction
*
- * @param obj The window object
- * @param layer The rotation of the window in degrees (0-360),
- * counter-clockwise.
+ * @see elm_thumbscroll_bounce_friction_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_rotation_with_resize_set(Evas_Object *obj, int rotation) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_bounce_friction_set(double friction);
+
/**
- * Get the rotation of the window.
+ * Set the amount of inertia a scroller will impose at bounce
+ * animations, for all Elementary application windows.
*
- * @param obj The window object
- * @return The rotation of the window in degrees (0-360)
+ * @param friction the thumb scroll bounce friction
*
- * @see elm_win_rotation_set()
- * @see elm_win_rotation_with_resize_set()
+ * @see elm_thumbscroll_bounce_friction_get()
+ * @ingroup Scrolling
*/
- EAPI int elm_win_rotation_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_bounce_friction_all_set(double friction);
+
/**
- * Set the sticky state of the window.
+ * Get the amount of inertia a <b>paged</b> scroller will impose at
+ * page fitting animations.
*
- * Hints the Window Manager that the window in @p obj should be left fixed
- * at its position even when the virtual desktop it's on moves or changes.
+ * @return the page scroll friction
*
- * @param obj The window object
- * @param sticky If true, the window's sticky state is enabled
+ * @ingroup Scrolling
*/
- EAPI void elm_win_sticky_set(Evas_Object *obj, Eina_Bool sticky) EINA_ARG_NONNULL(1);
+ EAPI double elm_scroll_page_scroll_friction_get(void);
+
/**
- * Get the sticky state of the window.
+ * Set the amount of inertia a <b>paged</b> scroller will impose at
+ * page fitting animations.
*
- * @param obj The window object
- * @return If true, the window's sticky state is enabled
+ * @param friction the page scroll friction
*
- * @see elm_win_sticky_set()
+ * @see elm_thumbscroll_page_scroll_friction_get()
+ * @ingroup Scrolling
*/
- EAPI Eina_Bool elm_win_sticky_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_page_scroll_friction_set(double friction);
+
/**
- * Set if this window is an illume conformant window
+ * Set the amount of inertia a <b>paged</b> scroller will impose at
+ * page fitting animations, for all Elementary application windows.
*
- * @param obj The window object
- * @param conformant The conformant flag (1 = conformant, 0 = non-conformant)
+ * @param friction the page scroll friction
+ *
+ * @see elm_thumbscroll_page_scroll_friction_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_conformant_set(Evas_Object *obj, Eina_Bool conformant) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_page_scroll_friction_all_set(double friction);
+
/**
- * Get if this window is an illume conformant window
+ * Get the amount of inertia a scroller will impose at region bring
+ * animations.
*
- * @param obj The window object
- * @return A boolean if this window is illume conformant or not
+ * @return the bring in scroll friction
+ *
+ * @ingroup Scrolling
*/
- EAPI Eina_Bool elm_win_conformant_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI double elm_scroll_bring_in_scroll_friction_get(void);
+
/**
- * Set a window to be an illume quickpanel window
+ * Set the amount of inertia a scroller will impose at region bring
+ * animations.
*
- * By default window objects are not quickpanel windows.
+ * @param friction the bring in scroll friction
*
- * @param obj The window object
- * @param quickpanel The quickpanel flag (1 = quickpanel, 0 = normal window)
+ * @see elm_thumbscroll_bring_in_scroll_friction_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_quickpanel_set(Evas_Object *obj, Eina_Bool quickpanel) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_bring_in_scroll_friction_set(double friction);
+
/**
- * Get if this window is a quickpanel or not
+ * Set the amount of inertia a scroller will impose at region bring
+ * animations, for all Elementary application windows.
*
- * @param obj The window object
- * @return A boolean if this window is a quickpanel or not
+ * @param friction the bring in scroll friction
+ *
+ * @see elm_thumbscroll_bring_in_scroll_friction_get()
+ * @ingroup Scrolling
*/
- EAPI Eina_Bool elm_win_quickpanel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_bring_in_scroll_friction_all_set(double friction);
+
/**
- * Set the major priority of a quickpanel window
+ * Get the amount of inertia scrollers will impose at animations
+ * triggered by Elementary widgets' zooming API.
*
- * @param obj The window object
- * @param priority The major priority for this quickpanel
+ * @return the zoom friction
+ *
+ * @ingroup Scrolling
*/
- EAPI void elm_win_quickpanel_priority_major_set(Evas_Object *obj, int priority) EINA_ARG_NONNULL(1);
+ EAPI double elm_scroll_zoom_friction_get(void);
+
/**
- * Get the major priority of a quickpanel window
+ * Set the amount of inertia scrollers will impose at animations
+ * triggered by Elementary widgets' zooming API.
*
- * @param obj The window object
- * @return The major priority of this quickpanel
+ * @param friction the zoom friction
+ *
+ * @see elm_thumbscroll_zoom_friction_get()
+ * @ingroup Scrolling
*/
- EAPI int elm_win_quickpanel_priority_major_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_zoom_friction_set(double friction);
+
/**
- * Set the minor priority of a quickpanel window
+ * Set the amount of inertia scrollers will impose at animations
+ * triggered by Elementary widgets' zooming API, for all Elementary
+ * application windows.
*
- * @param obj The window object
- * @param priority The minor priority for this quickpanel
+ * @param friction the zoom friction
+ *
+ * @see elm_thumbscroll_zoom_friction_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_quickpanel_priority_minor_set(Evas_Object *obj, int priority) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_zoom_friction_all_set(double friction);
+
/**
- * Get the minor priority of a quickpanel window
+ * Get whether scrollers should be draggable from any point in their
+ * views.
*
- * @param obj The window object
- * @return The minor priority of this quickpanel
+ * @return the thumb scroll state
+ *
+ * @note This is the default behavior for touch screens, in general.
+ * @note All other functions namespaced with "thumbscroll" will only
+ * have effect if this mode is enabled.
+ *
+ * @ingroup Scrolling
*/
- EAPI int elm_win_quickpanel_priority_minor_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_scroll_thumbscroll_enabled_get(void);
+
/**
- * Set which zone this quickpanel should appear in
+ * Set whether scrollers should be draggable from any point in their
+ * views.
*
- * @param obj The window object
- * @param zone The requested zone for this quickpanel
+ * @param enabled the thumb scroll state
+ *
+ * @see elm_thumbscroll_enabled_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_quickpanel_zone_set(Evas_Object *obj, int zone) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_enabled_set(Eina_Bool enabled);
+
/**
- * Get which zone this quickpanel should appear in
+ * Set whether scrollers should be draggable from any point in their
+ * views, for all Elementary application windows.
*
- * @param obj The window object
- * @return The requested zone for this quickpanel
+ * @param enabled the thumb scroll state
+ *
+ * @see elm_thumbscroll_enabled_get()
+ * @ingroup Scrolling
*/
- EAPI int elm_win_quickpanel_zone_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_enabled_all_set(Eina_Bool enabled);
+
/**
- * Set the window to be skipped by keyboard focus
+ * Get the number of pixels one should travel while dragging a
+ * scroller's view to actually trigger scrolling.
*
- * This sets the window to be skipped by normal keyboard input. This means
- * a window manager will be asked to not focus this window as well as omit
- * it from things like the taskbar, pager, "alt-tab" list etc. etc.
+ * @return the thumb scroll threshould
*
- * Call this and enable it on a window BEFORE you show it for the first time,
- * otherwise it may have no effect.
+ * One would use higher values for touch screens, in general, because
+ * of their inherent imprecision.
+ * @ingroup Scrolling
+ */
+ EAPI unsigned int elm_scroll_thumbscroll_threshold_get(void);
+
+ /**
+ * Set the number of pixels one should travel while dragging a
+ * scroller's view to actually trigger scrolling.
*
- * Use this for windows that have only output information or might only be
- * interacted with by the mouse or fingers, and never for typing input.
- * Be careful that this may have side-effects like making the window
- * non-accessible in some cases unless the window is specially handled. Use
- * this with care.
+ * @param threshold the thumb scroll threshould
*
- * @param obj The window object
- * @param skip The skip flag state (EINA_TRUE if it is to be skipped)
+ * @see elm_thumbscroll_threshould_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_prop_focus_skip_set(Evas_Object *obj, Eina_Bool skip) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_threshold_set(unsigned int threshold);
+
/**
- * Send a command to the windowing environment
+ * Set the number of pixels one should travel while dragging a
+ * scroller's view to actually trigger scrolling, for all Elementary
+ * application windows.
*
- * This is intended to work in touchscreen or small screen device
- * environments where there is a more simplistic window management policy in
- * place. This uses the window object indicated to select which part of the
- * environment to control (the part that this window lives in), and provides
- * a command and an optional parameter structure (use NULL for this if not
- * needed).
+ * @param threshold the thumb scroll threshould
*
- * @param obj The window object that lives in the environment to control
- * @param command The command to send
- * @param params Optional parameters for the command
+ * @see elm_thumbscroll_threshould_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_illume_command_send(Evas_Object *obj, Elm_Illume_Command command, void *params) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_threshold_all_set(unsigned int threshold);
+
/**
- * Get the inlined image object handle
+ * Get the minimum speed of mouse cursor movement which will trigger
+ * list self scrolling animation after a mouse up event
+ * (pixels/second).
*
- * When you create a window with elm_win_add() of type ELM_WIN_INLINED_IMAGE,
- * then the window is in fact an evas image object inlined in the parent
- * canvas. You can get this object (be careful to not manipulate it as it
- * is under control of elementary), and use it to do things like get pixel
- * data, save the image to a file, etc.
+ * @return the thumb scroll momentum threshould
*
- * @param obj The window object to get the inlined image from
- * @return The inlined image object, or NULL if none exists
+ * @ingroup Scrolling
*/
- EAPI Evas_Object *elm_win_inlined_image_object_get(Evas_Object *obj);
+ EAPI double elm_scroll_thumbscroll_momentum_threshold_get(void);
+
/**
- * Set the enabled status for the focus highlight in a window
+ * Set the minimum speed of mouse cursor movement which will trigger
+ * list self scrolling animation after a mouse up event
+ * (pixels/second).
*
- * This function will enable or disable the focus highlight only for the
- * given window, regardless of the global setting for it
+ * @param threshold the thumb scroll momentum threshould
*
- * @param obj The window where to enable the highlight
- * @param enabled The enabled value for the highlight
+ * @see elm_thumbscroll_momentum_threshould_get()
+ * @ingroup Scrolling
*/
- EAPI void elm_win_focus_highlight_enabled_set(Evas_Object *obj, Eina_Bool enabled) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_momentum_threshold_set(double threshold);
+
/**
- * Get the enabled value of the focus highlight for this window
+ * Set the minimum speed of mouse cursor movement which will trigger
+ * list self scrolling animation after a mouse up event
+ * (pixels/second), for all Elementary application windows.
*
- * @param obj The window in which to check if the focus highlight is enabled
+ * @param threshold the thumb scroll momentum threshould
*
- * @return EINA_TRUE if enabled, EINA_FALSE otherwise
+ * @see elm_thumbscroll_momentum_threshould_get()
+ * @ingroup Scrolling
*/
- EAPI Eina_Bool elm_win_focus_highlight_enabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_momentum_threshold_all_set(double threshold);
+
/**
- * Set the style for the focus highlight on this window
+ * Get the amount of inertia a scroller will impose at self scrolling
+ * animations.
*
- * Sets the style to use for theming the highlight of focused objects on
- * the given window. If @p style is NULL, the default will be used.
+ * @return the thumb scroll friction
*
- * @param obj The window where to set the style
- * @param style The style to set
+ * @ingroup Scrolling
*/
- EAPI void elm_win_focus_highlight_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
+ EAPI double elm_scroll_thumbscroll_friction_get(void);
+
/**
- * Get the style set for the focus highlight object
- *
- * Gets the style set for this windows highilght object, or NULL if none
- * is set.
+ * Set the amount of inertia a scroller will impose at self scrolling
+ * animations.
*
- * @param obj The window to retrieve the highlights style from
+ * @param friction the thumb scroll friction
*
- * @return The style set or NULL if none was. Default is used in that case.
+ * @see elm_thumbscroll_friction_get()
+ * @ingroup Scrolling
*/
- EAPI const char *elm_win_focus_highlight_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /*...
- * ecore_x_icccm_hints_set -> accepts_focus (add to ecore_evas)
- * ecore_x_icccm_hints_set -> window_group (add to ecore_evas)
- * ecore_x_icccm_size_pos_hints_set -> request_pos (add to ecore_evas)
- * ecore_x_icccm_client_leader_set -> l (add to ecore_evas)
- * ecore_x_icccm_window_role_set -> role (add to ecore_evas)
- * ecore_x_icccm_transient_for_set -> forwin (add to ecore_evas)
- * ecore_x_netwm_window_type_set -> type (add to ecore_evas)
+ EAPI void elm_scroll_thumbscroll_friction_set(double friction);
+
+ /**
+ * Set the amount of inertia a scroller will impose at self scrolling
+ * animations, for all Elementary application windows.
*
- * (add to ecore_x) set netwm argb icon! (add to ecore_evas)
- * (blank mouse, private mouse obj, defaultmouse)
+ * @param friction the thumb scroll friction
*
+ * @see elm_thumbscroll_friction_get()
+ * @ingroup Scrolling
*/
+ EAPI void elm_scroll_thumbscroll_friction_all_set(double friction);
+
/**
- * Sets the keyboard mode of the window.
+ * Get the amount of lag between your actual mouse cursor dragging
+ * movement and a scroller's view movement itself, while pushing it
+ * into bounce state manually.
*
- * @param obj The window object
- * @param mode The mode to set, one of #Elm_Win_Keyboard_Mode
- */
- EAPI void elm_win_keyboard_mode_set(Evas_Object *obj, Elm_Win_Keyboard_Mode mode) EINA_ARG_NONNULL(1);
- /**
- * Gets the keyboard mode of the window.
+ * @return the thumb scroll border friction
*
- * @param obj The window object
- * @return The mode, one of #Elm_Win_Keyboard_Mode
+ * @ingroup Scrolling
*/
- EAPI Elm_Win_Keyboard_Mode elm_win_keyboard_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI double elm_scroll_thumbscroll_border_friction_get(void);
+
/**
- * Sets whether the window is a keyboard.
+ * Set the amount of lag between your actual mouse cursor dragging
+ * movement and a scroller's view movement itself, while pushing it
+ * into bounce state manually.
*
- * @param obj The window object
- * @param is_keyboard If true, the window is a virtual keyboard
- */
- EAPI void elm_win_keyboard_win_set(Evas_Object *obj, Eina_Bool is_keyboard) EINA_ARG_NONNULL(1);
- /**
- * Gets whether the window is a keyboard.
+ * @param friction the thumb scroll border friction. @c 0.0 for
+ * perfect synchrony between two movements, @c 1.0 for maximum
+ * lag.
*
- * @param obj The window object
- * @return If the window is a virtual keyboard
+ * @see elm_thumbscroll_border_friction_get()
+ * @note parameter value will get bound to 0.0 - 1.0 interval, always
+ *
+ * @ingroup Scrolling
*/
- EAPI Eina_Bool elm_win_keyboard_win_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_border_friction_set(double friction);
/**
- * Get the screen position of a window.
+ * Set the amount of lag between your actual mouse cursor dragging
+ * movement and a scroller's view movement itself, while pushing it
+ * into bounce state manually, for all Elementary application windows.
*
- * @param obj The window object
- * @param x The int to store the x coordinate to
- * @param y The int to store the y coordinate to
+ * @param friction the thumb scroll border friction. @c 0.0 for
+ * perfect synchrony between two movements, @c 1.0 for maximum
+ * lag.
+ *
+ * @see elm_thumbscroll_border_friction_get()
+ * @note parameter value will get bound to 0.0 - 1.0 interval, always
+ *
+ * @ingroup Scrolling
*/
- EAPI void elm_win_screen_position_get(const Evas_Object *obj, int *x, int *y) EINA_ARG_NONNULL(1);
+ EAPI void elm_scroll_thumbscroll_border_friction_all_set(double friction);
+
/**
* @}
*/
/**
- * @defgroup Inwin Inwin
- *
- * @image html img/widget/inwin/preview-00.png
- * @image latex img/widget/inwin/preview-00.eps
- * @image html img/widget/inwin/preview-01.png
- * @image latex img/widget/inwin/preview-01.eps
- * @image html img/widget/inwin/preview-02.png
- * @image latex img/widget/inwin/preview-02.eps
- *
- * An inwin is a window inside a window that is useful for a quick popup.
- * It does not hover.
+ * @defgroup Scrollhints Scrollhints
*
- * It works by creating an object that will occupy the entire window, so it
- * must be created using an @ref Win "elm_win" as parent only. The inwin
- * object can be hidden or restacked below every other object if it's
- * needed to show what's behind it without destroying it. If this is done,
- * the elm_win_inwin_activate() function can be used to bring it back to
- * full visibility again.
+ * Objects when inside a scroller can scroll, but this may not always be
+ * desirable in certain situations. This allows an object to hint to itself
+ * and parents to "not scroll" in one of 2 ways. If any child object of a
+ * scroller has pushed a scroll freeze or hold then it affects all parent
+ * scrollers until all children have released them.
*
- * There are three styles available in the default theme. These are:
- * @li default: The inwin is sized to take over most of the window it's
- * placed in.
- * @li minimal: The size of the inwin will be the minimum necessary to show
- * its contents.
- * @li minimal_vertical: Horizontally, the inwin takes as much space as
- * possible, but it's sized vertically the most it needs to fit its\
- * contents.
+ * 1. To hold on scrolling. This means just flicking and dragging may no
+ * longer scroll, but pressing/dragging near an edge of the scroller will
+ * still scroll. This is automatically used by the entry object when
+ * selecting text.
*
- * Some examples of Inwin can be found in the following:
- * @li @ref inwin_example_01
+ * 2. To totally freeze scrolling. This means it stops. until
+ * popped/released.
*
* @{
*/
+
/**
- * Adds an inwin to the current window
- *
- * The @p obj used as parent @b MUST be an @ref Win "Elementary Window".
- * Never call this function with anything other than the top-most window
- * as its parameter, unless you are fond of undefined behavior.
+ * Push the scroll hold by 1
*
- * After creating the object, the widget will set itself as resize object
- * for the window with elm_win_resize_object_add(), so when shown it will
- * appear to cover almost the entire window (how much of it depends on its
- * content and the style used). It must not be added into other container
- * objects and it needs not be moved or resized manually.
+ * This increments the scroll hold count by one. If it is more than 0 it will
+ * take effect on the parents of the indicated object.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * @param obj The object
+ * @ingroup Scrollhints
*/
- EAPI Evas_Object *elm_win_inwin_add(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_scroll_hold_push(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Activates an inwin object, ensuring its visibility
- *
- * This function will make sure that the inwin @p obj is completely visible
- * by calling evas_object_show() and evas_object_raise() on it, to bring it
- * to the front. It also sets the keyboard focus to it, which will be passed
- * onto its content.
+ * Pop the scroll hold by 1
*
- * The object's theme will also receive the signal "elm,action,show" with
- * source "elm".
+ * This decrements the scroll hold count by one. If it is more than 0 it will
+ * take effect on the parents of the indicated object.
*
- * @param obj The inwin to activate
+ * @param obj The object
+ * @ingroup Scrollhints
*/
- EAPI void elm_win_inwin_activate(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_scroll_hold_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Set the content of an inwin object.
+ * Push the scroll freeze by 1
*
- * Once the content object is set, a previously set one will be deleted.
- * If you want to keep that old content object, use the
- * elm_win_inwin_content_unset() function.
+ * This increments the scroll freeze count by one. If it is more
+ * than 0 it will take effect on the parents of the indicated
+ * object.
*
- * @param obj The inwin object
- * @param content The object to set as content
+ * @param obj The object
+ * @ingroup Scrollhints
*/
- EAPI void elm_win_inwin_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_scroll_freeze_push(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Get the content of an inwin object.
- *
- * Return the content object which is set for this widget.
+ * Pop the scroll freeze by 1
*
- * The returned object is valid as long as the inwin is still alive and no
- * other content is set on it. Deleting the object will notify the inwin
- * about it and this one will be left empty.
- *
- * If you need to remove an inwin's content to be reused somewhere else,
- * see elm_win_inwin_content_unset().
+ * This decrements the scroll freeze count by one. If it is more
+ * than 0 it will take effect on the parents of the indicated
+ * object.
*
- * @param obj The inwin object
- * @return The content that is being used
+ * @param obj The object
+ * @ingroup Scrollhints
*/
- EAPI Evas_Object *elm_win_inwin_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_scroll_freeze_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Unset the content of an inwin object.
+ * Lock the scrolling of the given widget (and thus all parents)
*
- * Unparent and return the content object which was set for this widget.
+ * This locks the given object from scrolling in the X axis (and implicitly
+ * also locks all parent scrollers too from doing the same).
*
- * @param obj The inwin object
- * @return The content that was being used
- */
- EAPI Evas_Object *elm_win_inwin_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * @}
- */
- /* X specific calls - won't work on non-x engines (return 0) */
- EAPI Ecore_X_Window elm_win_xwindow_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "delete,request" - the user requested to delete the window
- * "focus,in" - window got focus
- * "focus,out" - window lost focus
- * "moved" - window that holds the canvas was moved
+ * @param obj The object
+ * @param lock The lock state (1 == locked, 0 == unlocked)
+ * @ingroup Scrollhints
*/
+ EAPI void elm_object_scroll_lock_x_set(Evas_Object *obj, Eina_Bool lock) EINA_ARG_NONNULL(1);
/**
- * @defgroup Bg Bg
+ * Lock the scrolling of the given widget (and thus all parents)
*
- * @image html img/widget/bg/preview-00.png
- * @image latex img/widget/bg/preview-00.eps
- *
- * @brief Background object, used for setting a solid color, image or Edje
- * group as background to a window or any container object.
- *
- * The bg object is used for setting a solid background to a window or
- * packing into any container object. It works just like an image, but has
- * some properties useful to a background, like setting it to tiled,
- * centered, scaled or stretched.
+ * This locks the given object from scrolling in the Y axis (and implicitly
+ * also locks all parent scrollers too from doing the same).
*
- * Here is some sample code using it:
- * @li @ref bg_01_example_page
- * @li @ref bg_02_example_page
- * @li @ref bg_03_example_page
+ * @param obj The object
+ * @param lock The lock state (1 == locked, 0 == unlocked)
+ * @ingroup Scrollhints
*/
-
- /* bg */
- typedef enum _Elm_Bg_Option
- {
- ELM_BG_OPTION_CENTER, /**< center the background */
- ELM_BG_OPTION_SCALE, /**< scale the background retaining aspect ratio */
- ELM_BG_OPTION_STRETCH, /**< stretch the background to fill */
- ELM_BG_OPTION_TILE /**< tile background at its original size */
- } Elm_Bg_Option;
+ EAPI void elm_object_scroll_lock_y_set(Evas_Object *obj, Eina_Bool lock) EINA_ARG_NONNULL(1);
/**
- * Add a new background to the parent
+ * Get the scrolling lock of the given widget
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * This gets the lock for X axis scrolling.
*
- * @ingroup Bg
+ * @param obj The object
+ * @ingroup Scrollhints
*/
- EAPI Evas_Object *elm_bg_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_object_scroll_lock_x_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the file (image or edje) used for the background
- *
- * @param obj The bg object
- * @param file The file path
- * @param group Optional key (group in Edje) within the file
- *
- * This sets the image file used in the background object. The image (or edje)
- * will be stretched (retaining aspect if its an image file) to completely fill
- * the bg object. This may mean some parts are not visible.
+ * Get the scrolling lock of the given widget
*
- * @note Once the image of @p obj is set, a previously set one will be deleted,
- * even if @p file is NULL.
+ * This gets the lock for X axis scrolling.
*
- * @ingroup Bg
+ * @param obj The object
+ * @ingroup Scrollhints
*/
- EAPI void elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_object_scroll_lock_y_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the file (image or edje) used for the background
+ * @}
+ */
+
+ /**
+ * Send a signal to the widget edje object.
*
- * @param obj The bg object
- * @param file The file path
- * @param group Optional key (group in Edje) within the file
+ * This function sends a signal to the edje object of the obj. An
+ * edje program can respond to a signal by specifying matching
+ * 'signal' and 'source' fields.
*
- * @ingroup Bg
+ * @param obj The object
+ * @param emission The signal's name.
+ * @param source The signal's source.
+ * @ingroup General
*/
- EAPI void elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_signal_emit(Evas_Object *obj, const char *emission, const char *source) EINA_ARG_NONNULL(1);
/**
- * Set the option used for the background image
- *
- * @param obj The bg object
- * @param option The desired background option (TILE, SCALE)
+ * Add a callback for a signal emitted by widget edje object.
*
- * This sets the option used for manipulating the display of the background
- * image. The image can be tiled or scaled.
+ * This function connects a callback function to a signal emitted by the
+ * edje object of the obj.
+ * Globs can occur in either the emission or source name.
*
- * @ingroup Bg
+ * @param obj The object
+ * @param emission The signal's name.
+ * @param source The signal's source.
+ * @param func The callback function to be executed when the signal is
+ * emitted.
+ * @param data A pointer to data to pass in to the callback function.
+ * @ingroup General
*/
- EAPI void elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data) EINA_ARG_NONNULL(1, 4);
/**
- * Get the option used for the background image
+ * Remove a signal-triggered callback from a widget edje object.
*
- * @param obj The bg object
- * @return The desired background option (CENTER, SCALE, STRETCH or TILE)
+ * This function removes a callback, previoulsy attached to a
+ * signal emitted by the edje object of the obj. The parameters
+ * emission, source and func must match exactly those passed to a
+ * previous call to elm_object_signal_callback_add(). The data
+ * pointer that was passed to this call will be returned.
*
- * @ingroup Bg
+ * @param obj The object
+ * @param emission The signal's name.
+ * @param source The signal's source.
+ * @param func The callback function to be executed when the signal is
+ * emitted.
+ * @return The data pointer
+ * @ingroup General
*/
- EAPI Elm_Bg_Option elm_bg_option_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void *elm_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func) EINA_ARG_NONNULL(1, 4);
+
/**
- * Set the option used for the background color
+ * Add a callback for input events (key up, key down, mouse wheel)
+ * on a given Elementary widget
+ *
+ * @param obj The widget to add an event callback on
+ * @param func The callback function to be executed when the event
+ * happens
+ * @param data Data to pass in to @p func
+ *
+ * Every widget in an Elementary interface set to receive focus,
+ * with elm_object_focus_allow_set(), will propagate @b all of its
+ * key up, key down and mouse wheel input events up to its parent
+ * object, and so on. All of the focusable ones in this chain which
+ * had an event callback set, with this call, will be able to treat
+ * those events. There are two ways of making the propagation of
+ * these event upwards in the tree of widgets to @b cease:
+ * - Just return @c EINA_TRUE on @p func. @c EINA_FALSE will mean
+ * the event was @b not processed, so the propagation will go on.
+ * - The @c event_info pointer passed to @p func will contain the
+ * event's structure and, if you OR its @c event_flags inner
+ * value to @c EVAS_EVENT_FLAG_ON_HOLD, you're telling Elementary
+ * one has already handled it, thus killing the event's
+ * propagation, too.
+ *
+ * @note Your event callback will be issued on those events taking
+ * place only if no other child widget of @obj has consumed the
+ * event already.
+ *
+ * @note Not to be confused with @c
+ * evas_object_event_callback_add(), which will add event callbacks
+ * per type on general Evas objects (no event propagation
+ * infrastructure taken in account).
+ *
+ * @note Not to be confused with @c
+ * elm_object_signal_callback_add(), which will add callbacks to @b
+ * signals coming from a widget's theme, not input events.
+ *
+ * @note Not to be confused with @c
+ * edje_object_signal_callback_add(), which does the same as
+ * elm_object_signal_callback_add(), but directly on an Edje
+ * object.
*
- * @param obj The bg object
- * @param r
- * @param g
- * @param b
+ * @note Not to be confused with @c
+ * evas_object_smart_callback_add(), which adds callbacks to smart
+ * objects' <b>smart events</b>, and not input events.
*
- * This sets the color used for the background rectangle. Its range goes
- * from 0 to 255.
+ * @see elm_object_event_callback_del()
*
- * @ingroup Bg
+ * @ingroup General
*/
- EAPI void elm_bg_color_set(Evas_Object *obj, int r, int g, int b) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+
/**
- * Get the option used for the background color
+ * Remove an event callback from a widget.
*
- * @param obj The bg object
- * @param r
- * @param g
- * @param b
+ * This function removes a callback, previoulsy attached to event emission
+ * by the @p obj.
+ * The parameters func and data must match exactly those passed to
+ * a previous call to elm_object_event_callback_add(). The data pointer that
+ * was passed to this call will be returned.
*
- * @ingroup Bg
+ * @param obj The object
+ * @param func The callback function to be executed when the event is
+ * emitted.
+ * @param data Data to pass in to the callback function.
+ * @return The data pointer
+ * @ingroup General
*/
- EAPI void elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b) EINA_ARG_NONNULL(1);
+ EAPI void *elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
/**
- * Set the overlay object used for the background object.
+ * Adjust size of an element for finger usage.
*
- * @param obj The bg object
- * @param overlay The overlay object
+ * @param times_w How many fingers should fit horizontally
+ * @param w Pointer to the width size to adjust
+ * @param times_h How many fingers should fit vertically
+ * @param h Pointer to the height size to adjust
*
- * This provides a way for elm_bg to have an 'overlay' that will be on top
- * of the bg. Once the over object is set, a previously set one will be
- * deleted, even if you set the new one to NULL. If you want to keep that
- * old content object, use the elm_bg_overlay_unset() function.
+ * This takes width and height sizes (in pixels) as input and a
+ * size multiple (which is how many fingers you want to place
+ * within the area, being "finger" the size set by
+ * elm_finger_size_set()), and adjusts the size to be large enough
+ * to accommodate the resulting size -- if it doesn't already
+ * accommodate it. On return the @p w and @p h sizes pointed to by
+ * these parameters will be modified, on those conditions.
*
- * @ingroup Bg
+ * @note This is kind of a low level Elementary call, most useful
+ * on size evaluation times for widgets. An external user wouldn't
+ * be calling, most of the time.
+ *
+ * @ingroup Fingers
*/
-
- EAPI void elm_bg_overlay_set(Evas_Object *obj, Evas_Object *overlay) EINA_ARG_NONNULL(1);
+ EAPI void elm_coords_finger_size_adjust(int times_w, Evas_Coord *w, int times_h, Evas_Coord *h);
/**
- * Get the overlay object used for the background object.
- *
- * @param obj The bg object
- * @return The content that is being used
- *
- * Return the content object which is set for this widget
+ * Get the duration for occuring long press event.
*
- * @ingroup Bg
+ * @return Timeout for long press event
+ * @ingroup Longpress
*/
- EAPI Evas_Object *elm_bg_overlay_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI double elm_longpress_timeout_get(void);
/**
- * Get the overlay object used for the background object.
- *
- * @param obj The bg object
- * @return The content that was being used
+ * Set the duration for occuring long press event.
*
- * Unparent and return the overlay object which was set for this widget
- *
- * @ingroup Bg
+ * @param lonpress_timeout Timeout for long press event
+ * @ingroup Longpress
*/
- EAPI Evas_Object *elm_bg_overlay_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_longpress_timeout_set(double longpress_timeout);
/**
- * Set the size of the pixmap representation of the image.
- *
- * This option just makes sense if an image is going to be set in the bg.
- *
- * @param obj The bg object
- * @param w The new width of the image pixmap representation.
- * @param h The new height of the image pixmap representation.
+ * @defgroup Debug Debug
+ * don't use it unless you are sure
*
- * This function sets a new size for pixmap representation of the given bg
- * image. It allows the image to be loaded already in the specified size,
- * reducing the memory usage and load time when loading a big image with load
- * size set to a smaller size.
+ * @{
+ */
+
+ /**
+ * Print Tree object hierarchy in stdout
*
- * NOTE: this is just a hint, the real size of the pixmap may differ
- * depending on the type of image being loaded, being bigger than requested.
+ * @param obj The root object
+ * @ingroup Debug
+ */
+ EAPI void elm_object_tree_dump(const Evas_Object *top);
+
+ /**
+ * Print Elm Objects tree hierarchy in file as dot(graphviz) syntax.
*
- * @ingroup Bg
+ * @param obj The root object
+ * @param file The path of output file
+ * @ingroup Debug
*/
- EAPI void elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
+ EAPI void elm_object_tree_dot_dump(const Evas_Object *top, const char *file);
+
+ /**
+ * @}
*/
/**
- * @defgroup Icon Icon
- *
- * @image html img/widget/icon/preview-00.png
- * @image latex img/widget/icon/preview-00.eps
+ * @defgroup Theme Theme
*
- * An object that provides standard icon images (delete, edit, arrows, etc.)
- * or a custom file (PNG, JPG, EDJE, etc.) used for an icon.
+ * Elementary uses Edje to theme its widgets, naturally. But for the most
+ * part this is hidden behind a simpler interface that lets the user set
+ * extensions and choose the style of widgets in a much easier way.
*
- * The icon image requested can be in the elementary theme, or in the
- * freedesktop.org paths. It's possible to set the order of preference from
- * where the image will be used.
+ * Instead of thinking in terms of paths to Edje files and their groups
+ * each time you want to change the appearance of a widget, Elementary
+ * works so you can add any theme file with extensions or replace the
+ * main theme at one point in the application, and then just set the style
+ * of widgets with elm_object_style_set() and related functions. Elementary
+ * will then look in its list of themes for a matching group and apply it,
+ * and when the theme changes midway through the application, all widgets
+ * will be updated accordingly.
*
- * This API is very similar to @ref Image, but with ready to use images.
+ * There are three concepts you need to know to understand how Elementary
+ * theming works: default theme, extensions and overlays.
*
- * Default images provided by the theme are described below.
+ * Default theme, obviously enough, is the one that provides the default
+ * look of all widgets. End users can change the theme used by Elementary
+ * by setting the @c ELM_THEME environment variable before running an
+ * application, or globally for all programs using the @c elementary_config
+ * utility. Applications can change the default theme using elm_theme_set(),
+ * but this can go against the user wishes, so it's not an adviced practice.
*
- * The first list contains icons that were first intended to be used in
- * toolbars, but can be used in many other places too:
- * @li home
- * @li close
- * @li apps
- * @li arrow_up
- * @li arrow_down
- * @li arrow_left
- * @li arrow_right
- * @li chat
- * @li clock
- * @li delete
- * @li edit
- * @li refresh
- * @li folder
- * @li file
+ * Ideally, applications should find everything they need in the already
+ * provided theme, but there may be occasions when that's not enough and
+ * custom styles are required to correctly express the idea. For this
+ * cases, Elementary has extensions.
*
- * Now some icons that were designed to be used in menus (but again, you can
- * use them anywhere else):
- * @li menu/home
- * @li menu/close
- * @li menu/apps
- * @li menu/arrow_up
- * @li menu/arrow_down
- * @li menu/arrow_left
- * @li menu/arrow_right
- * @li menu/chat
- * @li menu/clock
- * @li menu/delete
- * @li menu/edit
- * @li menu/refresh
- * @li menu/folder
- * @li menu/file
+ * Extensions allow the application developer to write styles of its own
+ * to apply to some widgets. This requires knowledge of how each widget
+ * is themed, as extensions will always replace the entire group used by
+ * the widget, so important signals and parts need to be there for the
+ * object to behave properly (see documentation of Edje for details).
+ * Once the theme for the extension is done, the application needs to add
+ * it to the list of themes Elementary will look into, using
+ * elm_theme_extension_add(), and set the style of the desired widgets as
+ * he would normally with elm_object_style_set().
*
- * And here we have some media player specific icons:
- * @li media_player/forward
- * @li media_player/info
- * @li media_player/next
- * @li media_player/pause
- * @li media_player/play
- * @li media_player/prev
- * @li media_player/rewind
- * @li media_player/stop
+ * Overlays, on the other hand, can replace the look of all widgets by
+ * overriding the default style. Like extensions, it's up to the application
+ * developer to write the theme for the widgets it wants, the difference
+ * being that when looking for the theme, Elementary will check first the
+ * list of overlays, then the set theme and lastly the list of extensions,
+ * so with overlays it's possible to replace the default view and every
+ * widget will be affected. This is very much alike to setting the whole
+ * theme for the application and will probably clash with the end user
+ * options, not to mention the risk of ending up with not matching styles
+ * across the program. Unless there's a very special reason to use them,
+ * overlays should be avoided for the resons exposed before.
*
- * Signals that you can add callbacks for are:
+ * All these theme lists are handled by ::Elm_Theme instances. Elementary
+ * keeps one default internally and every function that receives one of
+ * these can be called with NULL to refer to this default (except for
+ * elm_theme_free()). It's possible to create a new instance of a
+ * ::Elm_Theme to set other theme for a specific widget (and all of its
+ * children), but this is as discouraged, if not even more so, than using
+ * overlays. Don't use this unless you really know what you are doing.
*
- * "clicked" - This is called when a user has clicked the icon
+ * But to be less negative about things, you can look at the following
+ * examples:
+ * @li @ref theme_example_01 "Using extensions"
+ * @li @ref theme_example_02 "Using overlays"
*
- * An example of usage for this API follows:
- * @li @ref tutorial_icon
- */
-
- /**
- * @addtogroup Icon
* @{
*/
-
- typedef enum _Elm_Icon_Type
- {
- ELM_ICON_NONE,
- ELM_ICON_FILE,
- ELM_ICON_STANDARD
- } Elm_Icon_Type;
/**
- * @enum _Elm_Icon_Lookup_Order
- * @typedef Elm_Icon_Lookup_Order
+ * @typedef Elm_Theme
*
- * Lookup order used by elm_icon_standard_set(). Should look for icons in the
- * theme, FDO paths, or both?
+ * Opaque handler for the list of themes Elementary looks for when
+ * rendering widgets.
*
- * @ingroup Icon
+ * Stay out of this unless you really know what you are doing. For most
+ * cases, sticking to the default is all a developer needs.
*/
- typedef enum _Elm_Icon_Lookup_Order
- {
- ELM_ICON_LOOKUP_FDO_THEME, /**< icon look up order: freedesktop, theme */
- ELM_ICON_LOOKUP_THEME_FDO, /**< icon look up order: theme, freedesktop */
- ELM_ICON_LOOKUP_FDO, /**< icon look up order: freedesktop */
- ELM_ICON_LOOKUP_THEME /**< icon look up order: theme */
- } Elm_Icon_Lookup_Order;
+ typedef struct _Elm_Theme Elm_Theme;
/**
- * Add a new icon object to the parent.
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @see elm_icon_file_set()
+ * Create a new specific theme
*
- * @ingroup Icon
+ * This creates an empty specific theme that only uses the default theme. A
+ * specific theme has its own private set of extensions and overlays too
+ * (which are empty by default). Specific themes do not fall back to themes
+ * of parent objects. They are not intended for this use. Use styles, overlays
+ * and extensions when needed, but avoid specific themes unless there is no
+ * other way (example: you want to have a preview of a new theme you are
+ * selecting in a "theme selector" window. The preview is inside a scroller
+ * and should display what the theme you selected will look like, but not
+ * actually apply it yet. The child of the scroller will have a specific
+ * theme set to show this preview before the user decides to apply it to all
+ * applications).
*/
- EAPI Evas_Object *elm_icon_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI Elm_Theme *elm_theme_new(void);
/**
- * Set the file that will be used as icon.
- *
- * @param obj The icon object
- * @param file The path to file that will be used as icon image
- * @param group The group that the icon belongs to in edje file
- *
- * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
- *
- * @note The icon image set by this function can be changed by
- * elm_icon_standard_set().
+ * Free a specific theme
*
- * @see elm_icon_file_get()
+ * @param th The theme to free
*
- * @ingroup Icon
+ * This frees a theme created with elm_theme_new().
*/
- EAPI Eina_Bool elm_icon_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
+ EAPI void elm_theme_free(Elm_Theme *th);
/**
- * Set a location in memory to be used as an icon
+ * Copy the theme fom the source to the destination theme
*
- * @param obj The icon object
- * @param img The binary data that will be used as an image
- * @param size The size of binary data @p img
- * @param format Optional format of @p img to pass to the image loader
- * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
+ * @param th The source theme to copy from
+ * @param thdst The destination theme to copy data to
*
- * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
+ * This makes a one-time static copy of all the theme config, extensions
+ * and overlays from @p th to @p thdst. If @p th references a theme, then
+ * @p thdst is also set to reference it, with all the theme settings,
+ * overlays and extensions that @p th had.
+ */
+ EAPI void elm_theme_copy(Elm_Theme *th, Elm_Theme *thdst);
+ /**
+ * Tell the source theme to reference the ref theme
*
- * @note The icon image set by this function can be changed by
- * elm_icon_standard_set().
+ * @param th The theme that will do the referencing
+ * @param thref The theme that is the reference source
*
- * @ingroup Icon
+ * This clears @p th to be empty and then sets it to refer to @p thref
+ * so @p th acts as an override to @p thref, but where its overrides
+ * don't apply, it will fall through to @p thref for configuration.
*/
- EAPI Eina_Bool elm_icon_memfile_set(Evas_Object *obj, const void *img, size_t size, const char *format, const char *key); EINA_ARG_NONNULL(1, 2);
+ EAPI void elm_theme_ref_set(Elm_Theme *th, Elm_Theme *thref);
/**
- * Get the file that will be used as icon.
- *
- * @param obj The icon object
- * @param file The path to file that will be used as icon icon image
- * @param group The group that the icon belongs to in edje file
+ * Return the theme referred to
*
- * @see elm_icon_file_set()
+ * @param th The theme to get the reference from
+ * @return The referenced theme handle
*
- * @ingroup Icon
+ * This gets the theme set as the reference theme by elm_theme_ref_set().
+ * If no theme is set as a reference, NULL is returned.
*/
- EAPI void elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
- EAPI void elm_icon_thumb_set(const Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
+ EAPI Elm_Theme *elm_theme_ref_get(Elm_Theme *th);
/**
- * Set the icon by icon standards names.
+ * Return the default theme
*
- * @param obj The icon object
- * @param name The icon name
+ * @return The default theme handle
*
- * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
+ * This returns the internal default theme setup handle that all widgets
+ * use implicitly unless a specific theme is set. This is also often use
+ * as a shorthand of NULL.
+ */
+ EAPI Elm_Theme *elm_theme_default_get(void);
+ /**
+ * Prepends a theme overlay to the list of overlays
*
- * For example, freedesktop.org defines standard icon names such as "home",
- * "network", etc. There can be different icon sets to match those icon
- * keys. The @p name given as parameter is one of these "keys", and will be
- * used to look in the freedesktop.org paths and elementary theme. One can
- * change the lookup order with elm_icon_order_lookup_set().
+ * @param th The theme to add to, or if NULL, the default theme
+ * @param item The Edje file path to be used
*
- * If name is not found in any of the expected locations and it is the
- * absolute path of an image file, this image will be used.
+ * Use this if your application needs to provide some custom overlay theme
+ * (An Edje file that replaces some default styles of widgets) where adding
+ * new styles, or changing system theme configuration is not possible. Do
+ * NOT use this instead of a proper system theme configuration. Use proper
+ * configuration files, profiles, environment variables etc. to set a theme
+ * so that the theme can be altered by simple confiugration by a user. Using
+ * this call to achieve that effect is abusing the API and will create lots
+ * of trouble.
*
- * @note The icon image set by this function can be changed by
- * elm_icon_file_set().
+ * @see elm_theme_extension_add()
+ */
+ EAPI void elm_theme_overlay_add(Elm_Theme *th, const char *item);
+ /**
+ * Delete a theme overlay from the list of overlays
*
- * @see elm_icon_standard_get()
- * @see elm_icon_file_set()
+ * @param th The theme to delete from, or if NULL, the default theme
+ * @param item The name of the theme overlay
*
- * @ingroup Icon
+ * @see elm_theme_overlay_add()
*/
- EAPI Eina_Bool elm_icon_standard_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
+ EAPI void elm_theme_overlay_del(Elm_Theme *th, const char *item);
/**
- * Get the icon name set by icon standard names.
+ * Appends a theme extension to the list of extensions.
*
- * @param obj The icon object
- * @return The icon name
+ * @param th The theme to add to, or if NULL, the default theme
+ * @param item The Edje file path to be used
*
- * If the icon image was set using elm_icon_file_set() instead of
- * elm_icon_standard_set(), then this function will return @c NULL.
+ * This is intended when an application needs more styles of widgets or new
+ * widget themes that the default does not provide (or may not provide). The
+ * application has "extended" usage by coming up with new custom style names
+ * for widgets for specific uses, but as these are not "standard", they are
+ * not guaranteed to be provided by a default theme. This means the
+ * application is required to provide these extra elements itself in specific
+ * Edje files. This call adds one of those Edje files to the theme search
+ * path to be search after the default theme. The use of this call is
+ * encouraged when default styles do not meet the needs of the application.
+ * Use this call instead of elm_theme_overlay_add() for almost all cases.
*
- * @see elm_icon_standard_set()
+ * @see elm_object_style_set()
+ */
+ EAPI void elm_theme_extension_add(Elm_Theme *th, const char *item);
+ /**
+ * Deletes a theme extension from the list of extensions.
*
- * @ingroup Icon
+ * @param th The theme to delete from, or if NULL, the default theme
+ * @param item The name of the theme extension
+ *
+ * @see elm_theme_extension_add()
*/
- EAPI const char *elm_icon_standard_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_theme_extension_del(Elm_Theme *th, const char *item);
/**
- * Set the smooth effect for an icon object.
+ * Set the theme search order for the given theme
*
- * @param obj The icon object
- * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
- * otherwise. Default is @c EINA_TRUE.
+ * @param th The theme to set the search order, or if NULL, the default theme
+ * @param theme Theme search string
*
- * Set the scaling algorithm to be used when scaling the icon image. Smooth
- * scaling provides a better resulting image, but is slower.
+ * This sets the search string for the theme in path-notation from first
+ * theme to search, to last, delimited by the : character. Example:
*
- * The smooth scaling should be disabled when making animations that change
- * the icon size, since they will be faster. Animations that don't require
- * resizing of the icon can keep the smooth scaling enabled (even if the icon
- * is already scaled, since the scaled icon image will be cached).
+ * "shiny:/path/to/file.edj:default"
*
- * @see elm_icon_smooth_get()
+ * See the ELM_THEME environment variable for more information.
*
- * @ingroup Icon
+ * @see elm_theme_get()
+ * @see elm_theme_list_get()
*/
- EAPI void elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1);
+ EAPI void elm_theme_set(Elm_Theme *th, const char *theme);
/**
- * Get the smooth effect for an icon object.
+ * Return the theme search order
*
- * @param obj The icon object
- * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
+ * @param th The theme to get the search order, or if NULL, the default theme
+ * @return The internal search order path
*
- * @see elm_icon_smooth_set()
+ * This function returns a colon separated string of theme elements as
+ * returned by elm_theme_list_get().
*
- * @ingroup Icon
+ * @see elm_theme_set()
+ * @see elm_theme_list_get()
*/
- EAPI Eina_Bool elm_icon_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_theme_get(Elm_Theme *th);
/**
- * Disable scaling of this object.
+ * Return a list of theme elements to be used in a theme.
*
- * @param obj The icon object.
- * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
- * otherwise. Default is @c EINA_FALSE.
+ * @param th Theme to get the list of theme elements from.
+ * @return The internal list of theme elements
*
- * This function disables scaling of the icon object through the function
- * elm_object_scale_set(). However, this does not affect the object
- * size/resize in any way. For that effect, take a look at
- * elm_icon_scale_set().
+ * This returns the internal list of theme elements (will only be valid as
+ * long as the theme is not modified by elm_theme_set() or theme is not
+ * freed by elm_theme_free(). This is a list of strings which must not be
+ * altered as they are also internal. If @p th is NULL, then the default
+ * theme element list is returned.
*
- * @see elm_icon_no_scale_get()
- * @see elm_icon_scale_set()
- * @see elm_object_scale_set()
+ * A theme element can consist of a full or relative path to a .edj file,
+ * or a name, without extension, for a theme to be searched in the known
+ * theme paths for Elemementary.
*
- * @ingroup Icon
+ * @see elm_theme_set()
+ * @see elm_theme_get()
*/
- EAPI void elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1);
+ EAPI const Eina_List *elm_theme_list_get(const Elm_Theme *th);
/**
- * Get whether scaling is disabled on the object.
- *
- * @param obj The icon object
- * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
+ * Return the full patrh for a theme element
*
- * @see elm_icon_no_scale_set()
+ * @param f The theme element name
+ * @param in_search_path Pointer to a boolean to indicate if item is in the search path or not
+ * @return The full path to the file found.
*
- * @ingroup Icon
+ * This returns a string you should free with free() on success, NULL on
+ * failure. This will search for the given theme element, and if it is a
+ * full or relative path element or a simple searchable name. The returned
+ * path is the full path to the file, if searched, and the file exists, or it
+ * is simply the full path given in the element or a resolved path if
+ * relative to home. The @p in_search_path boolean pointed to is set to
+ * EINA_TRUE if the file was a searchable file andis in the search path,
+ * and EINA_FALSE otherwise.
*/
- EAPI Eina_Bool elm_icon_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI char *elm_theme_list_item_path_get(const char *f, Eina_Bool *in_search_path);
/**
- * Set if the object is (up/down) resizeable.
- *
- * @param obj The icon object
- * @param scale_up A bool to set if the object is resizeable up. Default is
- * @c EINA_TRUE.
- * @param scale_down A bool to set if the object is resizeable down. Default
- * is @c EINA_TRUE.
- *
- * This function limits the icon object resize ability. If @p scale_up is set to
- * @c EINA_FALSE, the object can't have its height or width resized to a value
- * higher than the original icon size. Same is valid for @p scale_down.
+ * Flush the current theme.
*
- * @see elm_icon_scale_get()
+ * @param th Theme to flush
*
- * @ingroup Icon
+ * This flushes caches that let elementary know where to find theme elements
+ * in the given theme. If @p th is NULL, then the default theme is flushed.
+ * Call this function if source theme data has changed in such a way as to
+ * make any caches Elementary kept invalid.
*/
- EAPI void elm_icon_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1);
+ EAPI void elm_theme_flush(Elm_Theme *th);
/**
- * Get if the object is (up/down) resizeable.
- *
- * @param obj The icon object
- * @param scale_up A bool to set if the object is resizeable up
- * @param scale_down A bool to set if the object is resizeable down
+ * This flushes all themes (default and specific ones).
*
- * @see elm_icon_scale_set()
+ * This will flush all themes in the current application context, by calling
+ * elm_theme_flush() on each of them.
+ */
+ EAPI void elm_theme_full_flush(void);
+ /**
+ * Set the theme for all elementary using applications on the current display
*
- * @ingroup Icon
+ * @param theme The name of the theme to use. Format same as the ELM_THEME
+ * environment variable.
*/
- EAPI void elm_icon_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1);
+ EAPI void elm_theme_all_set(const char *theme);
/**
- * Get the object's image size
+ * Return a list of theme elements in the theme search path
*
- * @param obj The icon object
- * @param w A pointer to store the width in
- * @param h A pointer to store the height in
+ * @return A list of strings that are the theme element names.
*
- * @ingroup Icon
+ * This lists all available theme files in the standard Elementary search path
+ * for theme elements, and returns them in alphabetical order as theme
+ * element names in a list of strings. Free this with
+ * elm_theme_name_available_list_free() when you are done with the list.
*/
- EAPI void elm_icon_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
+ EAPI Eina_List *elm_theme_name_available_list_new(void);
/**
- * Set if the icon fill the entire object area.
+ * Free the list returned by elm_theme_name_available_list_new()
*
- * @param obj The icon object
- * @param fill_outside @c EINA_TRUE if the object is filled outside,
- * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
+ * This frees the list of themes returned by
+ * elm_theme_name_available_list_new(). Once freed the list should no longer
+ * be used. a new list mys be created.
+ */
+ EAPI void elm_theme_name_available_list_free(Eina_List *list);
+ /**
+ * Set a specific theme to be used for this object and its children
*
- * When the icon object is resized to a different aspect ratio from the
- * original icon image, the icon image will still keep its aspect. This flag
- * tells how the image should fill the object's area. They are: keep the
- * entire icon inside the limits of height and width of the object (@p
- * fill_outside is @c EINA_FALSE) or let the extra width or height go outside
- * of the object, and the icon will fill the entire object (@p fill_outside
- * is @c EINA_TRUE).
- *
- * @note Unlike @ref Image, there's no option in icon to set the aspect ratio
- * retain property to false. Thus, the icon image will always keep its
- * original aspect ratio.
- *
- * @see elm_icon_fill_outside_get()
- * @see elm_image_fill_outside_set()
- *
- * @ingroup Icon
- */
- EAPI void elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1);
- /**
- * Get if the object is filled outside.
- *
- * @param obj The icon object
- * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
+ * @param obj The object to set the theme on
+ * @param th The theme to set
*
- * @see elm_icon_fill_outside_set()
+ * This sets a specific theme that will be used for the given object and any
+ * child objects it has. If @p th is NULL then the theme to be used is
+ * cleared and the object will inherit its theme from its parent (which
+ * ultimately will use the default theme if no specific themes are set).
*
- * @ingroup Icon
+ * Use special themes with great care as this will annoy users and make
+ * configuration difficult. Avoid any custom themes at all if it can be
+ * helped.
*/
- EAPI Eina_Bool elm_icon_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_object_theme_set(Evas_Object *obj, Elm_Theme *th) EINA_ARG_NONNULL(1);
/**
- * Set the prescale size for the icon.
- *
- * @param obj The icon object
- * @param size The prescale size. This value is used for both width and
- * height.
- *
- * This function sets a new size for pixmap representation of the given
- * icon. It allows the icon to be loaded already in the specified size,
- * reducing the memory usage and load time when loading a big icon with load
- * size set to a smaller size.
- *
- * It's equivalent to the elm_bg_load_size_set() function for bg.
- *
- * @note this is just a hint, the real size of the pixmap may differ
- * depending on the type of icon being loaded, being bigger than requested.
+ * Get the specific theme to be used
*
- * @see elm_icon_prescale_get()
- * @see elm_bg_load_size_set()
+ * @param obj The object to get the specific theme from
+ * @return The specifc theme set.
*
- * @ingroup Icon
+ * This will return a specific theme set, or NULL if no specific theme is
+ * set on that object. It will not return inherited themes from parents, only
+ * the specific theme set for that specific object. See elm_object_theme_set()
+ * for more information.
*/
- EAPI void elm_icon_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
+ EAPI Elm_Theme *elm_object_theme_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Get the prescale size for the icon.
- *
- * @param obj The icon object
- * @return The prescale size
+ * Get a data item from a theme
*
- * @see elm_icon_prescale_set()
+ * @param th The theme, or NULL for default theme
+ * @param key The data key to search with
+ * @return The data value, or NULL on failure
*
- * @ingroup Icon
+ * This function is used to return data items from edc in @p th, an overlay, or an extension.
+ * It works the same way as edje_file_data_get() except that the return is stringshared.
*/
- EAPI int elm_icon_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_theme_data_get(Elm_Theme *th, const char *key) EINA_ARG_NONNULL(2);
/**
- * Sets the icon lookup order used by elm_icon_standard_set().
- *
- * @param obj The icon object
- * @param order The icon lookup order (can be one of
- * ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO
- * or ELM_ICON_LOOKUP_THEME)
- *
- * @see elm_icon_order_lookup_get()
- * @see Elm_Icon_Lookup_Order
- *
- * @ingroup Icon
+ * @}
*/
- EAPI void elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) EINA_ARG_NONNULL(1);
- /**
- * Gets the icon lookup order.
+
+ /* win */
+ /** @defgroup Win Win
*
- * @param obj The icon object
- * @return The icon lookup order
+ * @image html img/widget/win/preview-00.png
+ * @image latex img/widget/win/preview-00.eps
*
- * @see elm_icon_order_lookup_set()
- * @see Elm_Icon_Lookup_Order
+ * The window class of Elementary. Contains functions to manipulate
+ * windows. The Evas engine used to render the window contents is specified
+ * in the system or user elementary config files (whichever is found last),
+ * and can be overridden with the ELM_ENGINE environment variable for
+ * testing. Engines that may be supported (depending on Evas and Ecore-Evas
+ * compilation setup and modules actually installed at runtime) are (listed
+ * in order of best supported and most likely to be complete and work to
+ * lowest quality).
*
- * @ingroup Icon
- */
- EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * @}
- */
-
- /**
- * @defgroup Image Image
+ * @li "x11", "x", "software-x11", "software_x11" (Software rendering in X11)
+ * @li "gl", "opengl", "opengl-x11", "opengl_x11" (OpenGL or OpenGL-ES2
+ * rendering in X11)
+ * @li "shot:..." (Virtual screenshot renderer - renders to output file and
+ * exits)
+ * @li "fb", "software-fb", "software_fb" (Linux framebuffer direct software
+ * rendering)
+ * @li "sdl", "software-sdl", "software_sdl" (SDL software rendering to SDL
+ * buffer)
+ * @li "gl-sdl", "gl_sdl", "opengl-sdl", "opengl_sdl" (OpenGL or OpenGL-ES2
+ * rendering using SDL as the buffer)
+ * @li "gdi", "software-gdi", "software_gdi" (Windows WIN32 rendering via
+ * GDI with software)
+ * @li "dfb", "directfb" (Rendering to a DirectFB window)
+ * @li "x11-8", "x8", "software-8-x11", "software_8_x11" (Rendering in
+ * grayscale using dedicated 8bit software engine in X11)
+ * @li "x11-16", "x16", "software-16-x11", "software_16_x11" (Rendering in
+ * X11 using 16bit software engine)
+ * @li "wince-gdi", "software-16-wince-gdi", "software_16_wince_gdi"
+ * (Windows CE rendering via GDI with 16bit software renderer)
+ * @li "sdl-16", "software-16-sdl", "software_16_sdl" (Rendering to SDL
+ * buffer with 16bit software renderer)
*
- * @image html img/widget/image/preview-00.png
- * @image latex img/widget/image/preview-00.eps
+ * All engines use a simple string to select the engine to render, EXCEPT
+ * the "shot" engine. This actually encodes the output of the virtual
+ * screenshot and how long to delay in the engine string. The engine string
+ * is encoded in the following way:
*
- * An object that allows one to load an image file to it. It can be used
- * anywhere like any other elementary widget.
+ * "shot:[delay=XX][:][repeat=DDD][:][file=XX]"
*
- * This widget provides most of the functionality provided from @ref Bg or @ref
- * Icon, but with a slightly different API (use the one that fits better your
- * needs).
+ * Where options are separated by a ":" char if more than one option is
+ * given, with delay, if provided being the first option and file the last
+ * (order is important). The delay specifies how long to wait after the
+ * window is shown before doing the virtual "in memory" rendering and then
+ * save the output to the file specified by the file option (and then exit).
+ * If no delay is given, the default is 0.5 seconds. If no file is given the
+ * default output file is "out.png". Repeat option is for continous
+ * capturing screenshots. Repeat range is from 1 to 999 and filename is
+ * fixed to "out001.png" Some examples of using the shot engine:
*
- * The features not provided by those two other image widgets are:
- * @li allowing to get the basic @c Evas_Object with elm_image_object_get();
- * @li change the object orientation with elm_image_orient_set();
- * @li and turning the image editable with elm_image_editable_set().
+ * ELM_ENGINE="shot:delay=1.0:repeat=5:file=elm_test.png" elementary_test
+ * ELM_ENGINE="shot:delay=1.0:file=elm_test.png" elementary_test
+ * ELM_ENGINE="shot:file=elm_test2.png" elementary_test
+ * ELM_ENGINE="shot:delay=2.0" elementary_test
+ * ELM_ENGINE="shot:" elementary_test
*
* Signals that you can add callbacks for are:
*
- * @li @c "clicked" - This is called when a user has clicked the image
+ * @li "delete,request": the user requested to close the window. See
+ * elm_win_autodel_set().
+ * @li "focus,in": window got focus
+ * @li "focus,out": window lost focus
+ * @li "moved": window that holds the canvas was moved
+ *
+ * Examples:
+ * @li @ref win_example_01
*
- * An example of usage for this API follows:
- * @li @ref tutorial_image
- */
-
- /**
- * @addtogroup Image
* @{
*/
-
/**
- * @enum _Elm_Image_Orient
- * @typedef Elm_Image_Orient
- *
- * Possible orientation options for elm_image_orient_set().
+ * Defines the types of window that can be created
*
- * @image html elm_image_orient_set.png
- * @image latex elm_image_orient_set.eps width=\textwidth
+ * These are hints set on the window so that a running Window Manager knows
+ * how the window should be handled and/or what kind of decorations it
+ * should have.
*
- * @ingroup Image
+ * Currently, only the X11 backed engines use them.
*/
- typedef enum _Elm_Image_Orient
+ typedef enum _Elm_Win_Type
{
- ELM_IMAGE_ORIENT_NONE, /**< no orientation change */
- ELM_IMAGE_ROTATE_90_CW, /**< rotate 90 degrees clockwise */
- ELM_IMAGE_ROTATE_180_CW, /**< rotate 180 degrees clockwise */
- ELM_IMAGE_ROTATE_90_CCW, /**< rotate 90 degrees counter-clockwise (i.e. 270 degrees clockwise) */
- ELM_IMAGE_FLIP_HORIZONTAL, /**< flip image horizontally */
- ELM_IMAGE_FLIP_VERTICAL, /**< flip image vertically */
- ELM_IMAGE_FLIP_TRANSPOSE, /**< flip the image along the y = (side - x) line*/
- ELM_IMAGE_FLIP_TRANSVERSE /**< flip the image along the y = x line */
- } Elm_Image_Orient;
+ ELM_WIN_BASIC, /**< A normal window. Indicates a normal, top-level
+ window. Almost every window will be created with this
+ type. */
+ ELM_WIN_DIALOG_BASIC, /**< Used for simple dialog windows/ */
+ ELM_WIN_DESKTOP, /**< For special desktop windows, like a background
+ window holding desktop icons. */
+ ELM_WIN_DOCK, /**< The window is used as a dock or panel. Usually would
+ be kept on top of any other window by the Window
+ Manager. */
+ ELM_WIN_TOOLBAR, /**< The window is used to hold a floating toolbar, or
+ similar. */
+ ELM_WIN_MENU, /**< Similar to #ELM_WIN_TOOLBAR. */
+ ELM_WIN_UTILITY, /**< A persistent utility window, like a toolbox or
+ pallete. */
+ ELM_WIN_SPLASH, /**< Splash window for a starting up application. */
+ ELM_WIN_DROPDOWN_MENU, /**< The window is a dropdown menu, as when an
+ entry in a menubar is clicked. Typically used
+ with elm_win_override_set(). This hint exists
+ for completion only, as the EFL way of
+ implementing a menu would not normally use a
+ separate window for its contents. */
+ ELM_WIN_POPUP_MENU, /**< Like #ELM_WIN_DROPDOWN_MENU, but for the menu
+ triggered by right-clicking an object. */
+ ELM_WIN_TOOLTIP, /**< The window is a tooltip. A short piece of
+ explanatory text that typically appear after the
+ mouse cursor hovers over an object for a while.
+ Typically used with elm_win_override_set() and also
+ not very commonly used in the EFL. */
+ ELM_WIN_NOTIFICATION, /**< A notification window, like a warning about
+ battery life or a new E-Mail received. */
+ ELM_WIN_COMBO, /**< A window holding the contents of a combo box. Not
+ usually used in the EFL. */
+ ELM_WIN_DND, /**< Used to indicate the window is a representation of an
+ object being dragged across different windows, or even
+ applications. Typically used with
+ elm_win_override_set(). */
+ ELM_WIN_INLINED_IMAGE, /**< The window is rendered onto an image
+ buffer. No actual window is created for this
+ type, instead the window and all of its
+ contents will be rendered to an image buffer.
+ This allows to have children window inside a
+ parent one just like any other object would
+ be, and do other things like applying @c
+ Evas_Map effects to it. This is the only type
+ of window that requires the @c parent
+ parameter of elm_win_add() to be a valid @c
+ Evas_Object. */
+ } Elm_Win_Type;
/**
- * Add a new image to the parent.
+ * The differents layouts that can be requested for the virtual keyboard.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @see elm_image_file_set()
- *
- * @ingroup Image
+ * When the application window is being managed by Illume, it may request
+ * any of the following layouts for the virtual keyboard.
*/
- EAPI Evas_Object *elm_image_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ typedef enum _Elm_Win_Keyboard_Mode
+ {
+ ELM_WIN_KEYBOARD_UNKNOWN, /**< Unknown keyboard state */
+ ELM_WIN_KEYBOARD_OFF, /**< Request to deactivate the keyboard */
+ ELM_WIN_KEYBOARD_ON, /**< Enable keyboard with default layout */
+ ELM_WIN_KEYBOARD_ALPHA, /**< Alpha (a-z) keyboard layout */
+ ELM_WIN_KEYBOARD_NUMERIC, /**< Numeric keyboard layout */
+ ELM_WIN_KEYBOARD_PIN, /**< PIN keyboard layout */
+ ELM_WIN_KEYBOARD_PHONE_NUMBER, /**< Phone keyboard layout */
+ ELM_WIN_KEYBOARD_HEX, /**< Hexadecimal numeric keyboard layout */
+ ELM_WIN_KEYBOARD_TERMINAL, /**< Full (QUERTY) keyboard layout */
+ ELM_WIN_KEYBOARD_PASSWORD, /**< Password keyboard layout */
+ ELM_WIN_KEYBOARD_IP, /**< IP keyboard layout */
+ ELM_WIN_KEYBOARD_HOST, /**< Host keyboard layout */
+ ELM_WIN_KEYBOARD_FILE, /**< File keyboard layout */
+ ELM_WIN_KEYBOARD_URL, /**< URL keyboard layout */
+ ELM_WIN_KEYBOARD_KEYPAD, /**< Keypad layout */
+ ELM_WIN_KEYBOARD_J2ME /**< J2ME keyboard layout */
+ } Elm_Win_Keyboard_Mode;
+
/**
- * Set the file that will be used as image.
- *
- * @param obj The image object
- * @param file The path to file that will be used as image
- * @param group The group that the image belongs in edje file (if it's an
- * edje image)
- *
- * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
- *
- * @see elm_image_file_get()
+ * Available commands that can be sent to the Illume manager.
*
- * @ingroup Image
+ * When running under an Illume session, a window may send commands to the
+ * Illume manager to perform different actions.
*/
- EAPI Eina_Bool elm_image_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
+ typedef enum _Elm_Illume_Command
+ {
+ ELM_ILLUME_COMMAND_FOCUS_BACK, /**< Reverts focus to the previous
+ window */
+ ELM_ILLUME_COMMAND_FOCUS_FORWARD, /**< Sends focus to the next window\
+ in the list */
+ ELM_ILLUME_COMMAND_FOCUS_HOME, /**< Hides all windows to show the Home
+ screen */
+ ELM_ILLUME_COMMAND_CLOSE /**< Closes the currently active window */
+ } Elm_Illume_Command;
+
/**
- * Get the file that will be used as image.
+ * Adds a window object. If this is the first window created, pass NULL as
+ * @p parent.
*
- * @param obj The image object
- * @param file The path to file
- * @param group The group that the image belongs in edje file
+ * @param parent Parent object to add the window to, or NULL
+ * @param name The name of the window
+ * @param type The window type, one of #Elm_Win_Type.
*
- * @see elm_image_file_set()
+ * The @p parent paramter can be @c NULL for every window @p type except
+ * #ELM_WIN_INLINED_IMAGE, which needs a parent to retrieve the canvas on
+ * which the image object will be created.
*
- * @ingroup Image
+ * @return The created object, or NULL on failure
*/
- EAPI void elm_image_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_win_add(Evas_Object *parent, const char *name, Elm_Win_Type type);
/**
- * Set the smooth effect for an image.
+ * Add @p subobj as a resize object of window @p obj.
*
- * @param obj The image object
- * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
- * otherwise. Default is @c EINA_TRUE.
*
- * Set the scaling algorithm to be used when scaling the image. Smooth
- * scaling provides a better resulting image, but is slower.
+ * Setting an object as a resize object of the window means that the
+ * @p subobj child's size and position will be controlled by the window
+ * directly. That is, the object will be resized to match the window size
+ * and should never be moved or resized manually by the developer.
*
- * The smooth scaling should be disabled when making animations that change
- * the image size, since it will be faster. Animations that don't require
- * resizing of the image can keep the smooth scaling enabled (even if the
- * image is already scaled, since the scaled image will be cached).
+ * In addition, resize objects of the window control what the minimum size
+ * of it will be, as well as whether it can or not be resized by the user.
*
- * @see elm_image_smooth_get()
+ * For the end user to be able to resize a window by dragging the handles
+ * or borders provided by the Window Manager, or using any other similar
+ * mechanism, all of the resize objects in the window should have their
+ * evas_object_size_hint_weight_set() set to EVAS_HINT_EXPAND.
*
- * @ingroup Image
+ * @param obj The window object
+ * @param subobj The resize object to add
*/
- EAPI void elm_image_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_resize_object_add(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
/**
- * Get the smooth effect for an image.
- *
- * @param obj The image object
- * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
+ * Delete @p subobj as a resize object of window @p obj.
*
- * @see elm_image_smooth_get()
+ * This function removes the object @p subobj from the resize objects of
+ * the window @p obj. It will not delete the object itself, which will be
+ * left unmanaged and should be deleted by the developer, manually handled
+ * or set as child of some other container.
*
- * @ingroup Image
+ * @param obj The window object
+ * @param subobj The resize object to add
*/
- EAPI Eina_Bool elm_image_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_resize_object_del(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
/**
- * Gets the current size of the image.
- *
- * @param obj The image object.
- * @param w Pointer to store width, or NULL.
- * @param h Pointer to store height, or NULL.
+ * Set the title of the window
*
- * This is the real size of the image, not the size of the object.
+ * @param obj The window object
+ * @param title The title to set
+ */
+ EAPI void elm_win_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
+ /**
+ * Get the title of the window
*
- * On error, neither w or h will be written.
+ * The returned string is an internal one and should not be freed or
+ * modified. It will also be rendered invalid if a new title is set or if
+ * the window is destroyed.
*
- * @ingroup Image
+ * @param obj The window object
+ * @return The title
*/
- EAPI void elm_image_object_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_win_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Disable scaling of this object.
- *
- * @param obj The image object.
- * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
- * otherwise. Default is @c EINA_FALSE.
+ * Set the window's autodel state.
*
- * This function disables scaling of the elm_image widget through the
- * function elm_object_scale_set(). However, this does not affect the widget
- * size/resize in any way. For that effect, take a look at
- * elm_image_scale_set().
+ * When closing the window in any way outside of the program control, like
+ * pressing the X button in the titlebar or using a command from the
+ * Window Manager, a "delete,request" signal is emitted to indicate that
+ * this event occurred and the developer can take any action, which may
+ * include, or not, destroying the window object.
*
- * @see elm_image_no_scale_get()
- * @see elm_image_scale_set()
- * @see elm_object_scale_set()
+ * When the @p autodel parameter is set, the window will be automatically
+ * destroyed when this event occurs, after the signal is emitted.
+ * If @p autodel is @c EINA_FALSE, then the window will not be destroyed
+ * and is up to the program to do so when it's required.
*
- * @ingroup Image
+ * @param obj The window object
+ * @param autodel If true, the window will automatically delete itself when
+ * closed
*/
- EAPI void elm_image_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_autodel_set(Evas_Object *obj, Eina_Bool autodel) EINA_ARG_NONNULL(1);
/**
- * Get whether scaling is disabled on the object.
- *
- * @param obj The image object
- * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
+ * Get the window's autodel state.
*
- * @see elm_image_no_scale_set()
+ * @param obj The window object
+ * @return If the window will automatically delete itself when closed
*
- * @ingroup Image
+ * @see elm_win_autodel_set()
*/
- EAPI Eina_Bool elm_image_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_win_autodel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set if the object is (up/down) resizeable.
- *
- * @param obj The image object
- * @param scale_up A bool to set if the object is resizeable up. Default is
- * @c EINA_TRUE.
- * @param scale_down A bool to set if the object is resizeable down. Default
- * is @c EINA_TRUE.
+ * Activate a window object.
*
- * This function limits the image resize ability. If @p scale_up is set to
- * @c EINA_FALSE, the object can't have its height or width resized to a value
- * higher than the original image size. Same is valid for @p scale_down.
+ * This function sends a request to the Window Manager to activate the
+ * window pointed by @p obj. If honored by the WM, the window will receive
+ * the keyboard focus.
*
- * @see elm_image_scale_get()
+ * @note This is just a request that a Window Manager may ignore, so calling
+ * this function does not ensure in any way that the window will be the
+ * active one after it.
*
- * @ingroup Image
+ * @param obj The window object
*/
- EAPI void elm_image_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_activate(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get if the object is (up/down) resizeable.
+ * Lower a window object.
*
- * @param obj The image object
- * @param scale_up A bool to set if the object is resizeable up
- * @param scale_down A bool to set if the object is resizeable down
+ * Places the window pointed by @p obj at the bottom of the stack, so that
+ * no other window is covered by it.
*
- * @see elm_image_scale_set()
+ * If elm_win_override_set() is not set, the Window Manager may ignore this
+ * request.
*
- * @ingroup Image
+ * @param obj The window object
*/
- EAPI void elm_image_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_lower(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set if the image fill the entire object area when keeping the aspect ratio.
- *
- * @param obj The image object
- * @param fill_outside @c EINA_TRUE if the object is filled outside,
- * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
- *
- * When the image should keep its aspect ratio even if resized to another
- * aspect ratio, there are two possibilities to resize it: keep the entire
- * image inside the limits of height and width of the object (@p fill_outside
- * is @c EINA_FALSE) or let the extra width or height go outside of the object,
- * and the image will fill the entire object (@p fill_outside is @c EINA_TRUE).
+ * Raise a window object.
*
- * @note This option will have no effect if
- * elm_image_aspect_ratio_retained_set() is set to @c EINA_FALSE.
+ * Places the window pointed by @p obj at the top of the stack, so that it's
+ * not covered by any other window.
*
- * @see elm_image_fill_outside_get()
- * @see elm_image_aspect_ratio_retained_set()
+ * If elm_win_override_set() is not set, the Window Manager may ignore this
+ * request.
*
- * @ingroup Image
+ * @param obj The window object
*/
- EAPI void elm_image_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_raise(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get if the object is filled outside
+ * Set the borderless state of a window.
*
- * @param obj The image object
- * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
+ * This function requests the Window Manager to not draw any decoration
+ * around the window.
*
- * @see elm_image_fill_outside_set()
+ * @param obj The window object
+ * @param borderless If true, the window is borderless
+ */
+ EAPI void elm_win_borderless_set(Evas_Object *obj, Eina_Bool borderless) EINA_ARG_NONNULL(1);
+ /**
+ * Get the borderless state of a window.
*
- * @ingroup Image
+ * @param obj The window object
+ * @return If true, the window is borderless
*/
- EAPI Eina_Bool elm_image_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_win_borderless_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the prescale size for the image
+ * Set the shaped state of a window.
*
- * @param obj The image object
- * @param size The prescale size. This value is used for both width and
- * height.
+ * Shaped windows, when supported, will render the parts of the window that
+ * has no content, transparent.
*
- * This function sets a new size for pixmap representation of the given
- * image. It allows the image to be loaded already in the specified size,
- * reducing the memory usage and load time when loading a big image with load
- * size set to a smaller size.
+ * If @p shaped is EINA_FALSE, then it is strongly adviced to have some
+ * background object or cover the entire window in any other way, or the
+ * parts of the canvas that have no data will show framebuffer artifacts.
*
- * It's equivalent to the elm_bg_load_size_set() function for bg.
+ * @param obj The window object
+ * @param shaped If true, the window is shaped
*
- * @note this is just a hint, the real size of the pixmap may differ
- * depending on the type of image being loaded, being bigger than requested.
+ * @see elm_win_alpha_set()
+ */
+ EAPI void elm_win_shaped_set(Evas_Object *obj, Eina_Bool shaped) EINA_ARG_NONNULL(1);
+ /**
+ * Get the shaped state of a window.
*
- * @see elm_image_prescale_get()
- * @see elm_bg_load_size_set()
+ * @param obj The window object
+ * @return If true, the window is shaped
*
- * @ingroup Image
+ * @see elm_win_shaped_set()
*/
- EAPI void elm_image_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_win_shaped_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the prescale size for the image
+ * Set the alpha channel state of a window.
*
- * @param obj The image object
- * @return The prescale size
+ * If @p alpha is EINA_TRUE, the alpha channel of the canvas will be enabled
+ * possibly making parts of the window completely or partially transparent.
+ * This is also subject to the underlying system supporting it, like for
+ * example, running under a compositing manager. If no compositing is
+ * available, enabling this option will instead fallback to using shaped
+ * windows, with elm_win_shaped_set().
*
- * @see elm_image_prescale_set()
+ * @param obj The window object
+ * @param alpha If true, the window has an alpha channel
*
- * @ingroup Image
+ * @see elm_win_alpha_set()
*/
- EAPI int elm_image_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_alpha_set(Evas_Object *obj, Eina_Bool alpha) EINA_ARG_NONNULL(1);
/**
- * Set the image orientation.
+ * Get the transparency state of a window.
*
- * @param obj The image object
- * @param orient The image orientation
- * (one of #ELM_IMAGE_ORIENT_NONE, #ELM_IMAGE_ROTATE_90_CW,
- * #ELM_IMAGE_ROTATE_180_CW, #ELM_IMAGE_ROTATE_90_CCW,
- * #ELM_IMAGE_FLIP_HORIZONTAL, #ELM_IMAGE_FLIP_VERTICAL,
- * #ELM_IMAGE_FLIP_TRANSPOSE, #ELM_IMAGE_FLIP_TRANSVERSE).
- * Default is #ELM_IMAGE_ORIENT_NONE.
+ * @param obj The window object
+ * @return If true, the window is transparent
*
- * This function allows to rotate or flip the given image.
+ * @see elm_win_transparent_set()
+ */
+ EAPI Eina_Bool elm_win_transparent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the transparency state of a window.
*
- * @see elm_image_orient_get()
- * @see @ref Elm_Image_Orient
+ * Use elm_win_alpha_set() instead.
*
- * @ingroup Image
+ * @param obj The window object
+ * @param transparent If true, the window is transparent
+ *
+ * @see elm_win_alpha_set()
*/
- EAPI void elm_image_orient_set(Evas_Object *obj, Elm_Image_Orient orient) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_transparent_set(Evas_Object *obj, Eina_Bool transparent) EINA_ARG_NONNULL(1);
/**
- * Get the image orientation.
+ * Get the alpha channel state of a window.
*
- * @param obj The image object
- * @return The image orientation
- * (one of #ELM_IMAGE_ORIENT_NONE, #ELM_IMAGE_ROTATE_90_CW,
- * #ELM_IMAGE_ROTATE_180_CW, #ELM_IMAGE_ROTATE_90_CCW,
- * #ELM_IMAGE_FLIP_HORIZONTAL, #ELM_IMAGE_FLIP_VERTICAL,
- * #ELM_IMAGE_FLIP_TRANSPOSE, #ELM_IMAGE_FLIP_TRANSVERSE)
+ * @param obj The window object
+ * @return If true, the window has an alpha channel
+ */
+ EAPI Eina_Bool elm_win_alpha_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the override state of a window.
*
- * @see elm_image_orient_set()
- * @see @ref Elm_Image_Orient
+ * A window with @p override set to EINA_TRUE will not be managed by the
+ * Window Manager. This means that no decorations of any kind will be shown
+ * for it, moving and resizing must be handled by the application, as well
+ * as the window visibility.
*
- * @ingroup Image
+ * This should not be used for normal windows, and even for not so normal
+ * ones, it should only be used when there's a good reason and with a lot
+ * of care. Mishandling override windows may result situations that
+ * disrupt the normal workflow of the end user.
+ *
+ * @param obj The window object
+ * @param override If true, the window is overridden
*/
- EAPI Elm_Image_Orient elm_image_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_override_set(Evas_Object *obj, Eina_Bool override) EINA_ARG_NONNULL(1);
/**
- * Make the image 'editable'.
+ * Get the override state of a window.
*
- * @param obj Image object.
- * @param set Turn on or off editability. Default is @c EINA_FALSE.
+ * @param obj The window object
+ * @return If true, the window is overridden
*
- * This means the image is a valid drag target for drag and drop, and can be
- * cut or pasted too.
+ * @see elm_win_override_set()
+ */
+ EAPI Eina_Bool elm_win_override_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the fullscreen state of a window.
*
- * @ingroup Image
+ * @param obj The window object
+ * @param fullscreen If true, the window is fullscreen
*/
- EAPI void elm_image_editable_set(Evas_Object *obj, Eina_Bool set) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_fullscreen_set(Evas_Object *obj, Eina_Bool fullscreen) EINA_ARG_NONNULL(1);
/**
- * Make the image 'editable'.
+ * Get the fullscreen state of a window.
*
- * @param obj Image object.
- * @return Editability.
+ * @param obj The window object
+ * @return If true, the window is fullscreen
+ */
+ EAPI Eina_Bool elm_win_fullscreen_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the maximized state of a window.
*
- * This means the image is a valid drag target for drag and drop, and can be
- * cut or pasted too.
+ * @param obj The window object
+ * @param maximized If true, the window is maximized
+ */
+ EAPI void elm_win_maximized_set(Evas_Object *obj, Eina_Bool maximized) EINA_ARG_NONNULL(1);
+ /**
+ * Get the maximized state of a window.
*
- * @ingroup Image
+ * @param obj The window object
+ * @return If true, the window is maximized
*/
- EAPI Eina_Bool elm_image_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_win_maximized_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the basic Evas_Image object from this object (widget).
+ * Set the iconified state of a window.
*
- * @param obj The image object to get the inlined image from
- * @return The inlined image object, or NULL if none exists
+ * @param obj The window object
+ * @param iconified If true, the window is iconified
+ */
+ EAPI void elm_win_iconified_set(Evas_Object *obj, Eina_Bool iconified) EINA_ARG_NONNULL(1);
+ /**
+ * Get the iconified state of a window.
*
- * This function allows one to get the underlying @c Evas_Object of type
- * Image from this elementary widget. It can be useful to do things like get
- * the pixel data, save the image to a file, etc.
+ * @param obj The window object
+ * @return If true, the window is iconified
+ */
+ EAPI Eina_Bool elm_win_iconified_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the layer of the window.
*
- * @note Be careful to not manipulate it, as it is under control of
- * elementary.
+ * What this means exactly will depend on the underlying engine used.
*
- * @ingroup Image
+ * In the case of X11 backed engines, the value in @p layer has the
+ * following meanings:
+ * @li < 3: The window will be placed below all others.
+ * @li > 5: The window will be placed above all others.
+ * @li other: The window will be placed in the default layer.
+ *
+ * @param obj The window object
+ * @param layer The layer of the window
*/
- EAPI Evas_Object *elm_image_object_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_layer_set(Evas_Object *obj, int layer) EINA_ARG_NONNULL(1);
/**
- * Set whether the original aspect ratio of the image should be kept on resize.
+ * Get the layer of the window.
*
- * @param obj The image object.
- * @param retained @c EINA_TRUE if the image should retain the aspect,
- * @c EINA_FALSE otherwise.
+ * @param obj The window object
+ * @return The layer of the window
*
- * The original aspect ratio (width / height) of the image is usually
- * distorted to match the object's size. Enabling this option will retain
- * this original aspect, and the way that the image is fit into the object's
- * area depends on the option set by elm_image_fill_outside_set().
+ * @see elm_win_layer_set()
+ */
+ EAPI int elm_win_layer_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the rotation of the window.
*
- * @see elm_image_aspect_ratio_retained_get()
- * @see elm_image_fill_outside_set()
+ * Most engines only work with multiples of 90.
*
- * @ingroup Image
+ * This function is used to set the orientation of the window @p obj to
+ * match that of the screen. The window itself will be resized to adjust
+ * to the new geometry of its contents. If you want to keep the window size,
+ * see elm_win_rotation_with_resize_set().
+ *
+ * @param obj The window object
+ * @param rotation The rotation of the window, in degrees (0-360),
+ * counter-clockwise.
*/
- EAPI void elm_image_aspect_ratio_retained_set(Evas_Object *obj, Eina_Bool retained) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_rotation_set(Evas_Object *obj, int rotation) EINA_ARG_NONNULL(1);
/**
- * Get if the object retains the original aspect ratio.
+ * Rotates the window and resizes it.
*
- * @param obj The image object.
- * @return @c EINA_TRUE if the object keeps the original aspect, @c EINA_FALSE
- * otherwise.
+ * Like elm_win_rotation_set(), but it also resizes the window's contents so
+ * that they fit inside the current window geometry.
*
- * @ingroup Image
+ * @param obj The window object
+ * @param layer The rotation of the window in degrees (0-360),
+ * counter-clockwise.
*/
- EAPI Eina_Bool elm_image_aspect_ratio_retained_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /* smart callbacks called:
- * "clicked" - the user clicked the image
+ EAPI void elm_win_rotation_with_resize_set(Evas_Object *obj, int rotation) EINA_ARG_NONNULL(1);
+ /**
+ * Get the rotation of the window.
+ *
+ * @param obj The window object
+ * @return The rotation of the window in degrees (0-360)
+ *
+ * @see elm_win_rotation_set()
+ * @see elm_win_rotation_with_resize_set()
*/
-
+ EAPI int elm_win_rotation_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @}
+ * Set the sticky state of the window.
+ *
+ * Hints the Window Manager that the window in @p obj should be left fixed
+ * at its position even when the virtual desktop it's on moves or changes.
+ *
+ * @param obj The window object
+ * @param sticky If true, the window's sticky state is enabled
*/
-
- /* glview */
- typedef void (*Elm_GLView_Func_Cb)(Evas_Object *obj);
-
- typedef enum _Elm_GLView_Mode
- {
- ELM_GLVIEW_ALPHA = 1,
- ELM_GLVIEW_DEPTH = 2,
- ELM_GLVIEW_STENCIL = 4
- } Elm_GLView_Mode;
-
+ EAPI void elm_win_sticky_set(Evas_Object *obj, Eina_Bool sticky) EINA_ARG_NONNULL(1);
/**
- * Defines a policy for the glview resizing.
+ * Get the sticky state of the window.
*
- * @note Default is ELM_GLVIEW_RESIZE_POLICY_RECREATE
+ * @param obj The window object
+ * @return If true, the window's sticky state is enabled
+ *
+ * @see elm_win_sticky_set()
*/
- typedef enum _Elm_GLView_Resize_Policy
- {
- ELM_GLVIEW_RESIZE_POLICY_RECREATE = 1, /**< Resize the internal surface along with the image */
- ELM_GLVIEW_RESIZE_POLICY_SCALE = 2 /**< Only reize the internal image and not the surface */
- } Elm_GLView_Resize_Policy;
-
- typedef enum _Elm_GLView_Render_Policy
- {
- ELM_GLVIEW_RENDER_POLICY_ON_DEMAND = 1, /**< Render only when there is a need for redrawing */
- ELM_GLVIEW_RENDER_POLICY_ALWAYS = 2 /**< Render always even when it is not visible */
- } Elm_GLView_Render_Policy;
-
-
- EAPI Evas_Object *elm_glview_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- EAPI void elm_glview_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
- EAPI void elm_glview_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
- EAPI Evas_GL_API *elm_glview_gl_api_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_glview_mode_set(Evas_Object *obj, Elm_GLView_Mode mode) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_glview_resize_policy_set(Evas_Object *obj, Elm_GLView_Resize_Policy policy) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_glview_render_policy_set(Evas_Object *obj, Elm_GLView_Render_Policy policy) EINA_ARG_NONNULL(1);
- EAPI void elm_glview_init_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
- EAPI void elm_glview_del_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
- EAPI void elm_glview_resize_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
- EAPI void elm_glview_render_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
- EAPI void elm_glview_changed_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /* box */
+ EAPI Eina_Bool elm_win_sticky_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @defgroup Box Box
- *
- * @image html img/widget/box/preview-00.png
- * @image latex img/widget/box/preview-00.eps width=\textwidth
- *
- * @image html img/box.png
- * @image latex img/box.eps width=\textwidth
+ * Set if this window is an illume conformant window
*
- * A box arranges objects in a linear fashion, governed by a layout function
- * that defines the details of this arrangement.
+ * @param obj The window object
+ * @param conformant The conformant flag (1 = conformant, 0 = non-conformant)
+ */
+ EAPI void elm_win_conformant_set(Evas_Object *obj, Eina_Bool conformant) EINA_ARG_NONNULL(1);
+ /**
+ * Get if this window is an illume conformant window
*
- * By default, the box will use an internal function to set the layout to
- * a single row, either vertical or horizontal. This layout is affected
- * by a number of parameters, such as the homogeneous flag set by
- * elm_box_homogeneous_set(), the values given by elm_box_padding_set() and
- * elm_box_align_set() and the hints set to each object in the box.
+ * @param obj The window object
+ * @return A boolean if this window is illume conformant or not
+ */
+ EAPI Eina_Bool elm_win_conformant_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set a window to be an illume quickpanel window
*
- * For this default layout, it's possible to change the orientation with
- * elm_box_horizontal_set(). The box will start in the vertical orientation,
- * placing its elements ordered from top to bottom. When horizontal is set,
- * the order will go from left to right. If the box is set to be
- * homogeneous, every object in it will be assigned the same space, that
- * of the largest object. Padding can be used to set some spacing between
- * the cell given to each object. The alignment of the box, set with
- * elm_box_align_set(), determines how the bounding box of all the elements
- * will be placed within the space given to the box widget itself.
+ * By default window objects are not quickpanel windows.
*
- * The size hints of each object also affect how they are placed and sized
- * within the box. evas_object_size_hint_min_set() will give the minimum
- * size the object can have, and the box will use it as the basis for all
- * latter calculations. Elementary widgets set their own minimum size as
- * needed, so there's rarely any need to use it manually.
+ * @param obj The window object
+ * @param quickpanel The quickpanel flag (1 = quickpanel, 0 = normal window)
+ */
+ EAPI void elm_win_quickpanel_set(Evas_Object *obj, Eina_Bool quickpanel) EINA_ARG_NONNULL(1);
+ /**
+ * Get if this window is a quickpanel or not
*
- * evas_object_size_hint_weight_set(), when not in homogeneous mode, is
- * used to tell whether the object will be allocated the minimum size it
- * needs or if the space given to it should be expanded. It's important
- * to realize that expanding the size given to the object is not the same
- * thing as resizing the object. It could very well end being a small
- * widget floating in a much larger empty space. If not set, the weight
- * for objects will normally be 0.0 for both axis, meaning the widget will
- * not be expanded. To take as much space possible, set the weight to
- * EVAS_HINT_EXPAND (defined to 1.0) for the desired axis to expand.
+ * @param obj The window object
+ * @return A boolean if this window is a quickpanel or not
+ */
+ EAPI Eina_Bool elm_win_quickpanel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the major priority of a quickpanel window
*
- * Besides how much space each object is allocated, it's possible to control
- * how the widget will be placed within that space using
- * evas_object_size_hint_align_set(). By default, this value will be 0.5
- * for both axis, meaning the object will be centered, but any value from
- * 0.0 (left or top, for the @c x and @c y axis, respectively) to 1.0
- * (right or bottom) can be used. The special value EVAS_HINT_FILL, which
- * is -1.0, means the object will be resized to fill the entire space it
- * was allocated.
+ * @param obj The window object
+ * @param priority The major priority for this quickpanel
+ */
+ EAPI void elm_win_quickpanel_priority_major_set(Evas_Object *obj, int priority) EINA_ARG_NONNULL(1);
+ /**
+ * Get the major priority of a quickpanel window
*
- * In addition, customized functions to define the layout can be set, which
- * allow the application developer to organize the objects within the box
- * in any number of ways.
+ * @param obj The window object
+ * @return The major priority of this quickpanel
+ */
+ EAPI int elm_win_quickpanel_priority_major_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the minor priority of a quickpanel window
*
- * The special elm_box_layout_transition() function can be used
- * to switch from one layout to another, animating the motion of the
- * children of the box.
+ * @param obj The window object
+ * @param priority The minor priority for this quickpanel
+ */
+ EAPI void elm_win_quickpanel_priority_minor_set(Evas_Object *obj, int priority) EINA_ARG_NONNULL(1);
+ /**
+ * Get the minor priority of a quickpanel window
*
- * @note Objects should not be added to box objects using _add() calls.
+ * @param obj The window object
+ * @return The minor priority of this quickpanel
+ */
+ EAPI int elm_win_quickpanel_priority_minor_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set which zone this quickpanel should appear in
*
- * Some examples on how to use boxes follow:
- * @li @ref box_example_01
- * @li @ref box_example_02
+ * @param obj The window object
+ * @param zone The requested zone for this quickpanel
+ */
+ EAPI void elm_win_quickpanel_zone_set(Evas_Object *obj, int zone) EINA_ARG_NONNULL(1);
+ /**
+ * Get which zone this quickpanel should appear in
*
- * @{
+ * @param obj The window object
+ * @return The requested zone for this quickpanel
*/
+ EAPI int elm_win_quickpanel_zone_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @typedef Elm_Box_Transition
+ * Set the window to be skipped by keyboard focus
*
- * Opaque handler containing the parameters to perform an animated
- * transition of the layout the box uses.
+ * This sets the window to be skipped by normal keyboard input. This means
+ * a window manager will be asked to not focus this window as well as omit
+ * it from things like the taskbar, pager, "alt-tab" list etc. etc.
*
- * @see elm_box_transition_new()
- * @see elm_box_layout_set()
- * @see elm_box_layout_transition()
+ * Call this and enable it on a window BEFORE you show it for the first time,
+ * otherwise it may have no effect.
+ *
+ * Use this for windows that have only output information or might only be
+ * interacted with by the mouse or fingers, and never for typing input.
+ * Be careful that this may have side-effects like making the window
+ * non-accessible in some cases unless the window is specially handled. Use
+ * this with care.
+ *
+ * @param obj The window object
+ * @param skip The skip flag state (EINA_TRUE if it is to be skipped)
*/
- typedef struct _Elm_Box_Transition Elm_Box_Transition;
-
+ EAPI void elm_win_prop_focus_skip_set(Evas_Object *obj, Eina_Bool skip) EINA_ARG_NONNULL(1);
/**
- * Add a new box to the parent
+ * Send a command to the windowing environment
*
- * By default, the box will be in vertical mode and non-homogeneous.
+ * This is intended to work in touchscreen or small screen device
+ * environments where there is a more simplistic window management policy in
+ * place. This uses the window object indicated to select which part of the
+ * environment to control (the part that this window lives in), and provides
+ * a command and an optional parameter structure (use NULL for this if not
+ * needed).
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * @param obj The window object that lives in the environment to control
+ * @param command The command to send
+ * @param params Optional parameters for the command
*/
- EAPI Evas_Object *elm_box_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_illume_command_send(Evas_Object *obj, Elm_Illume_Command command, void *params) EINA_ARG_NONNULL(1);
/**
- * Set the horizontal orientation
- *
- * By default, box object arranges their contents vertically from top to
- * bottom.
- * By calling this function with @p horizontal as EINA_TRUE, the box will
- * become horizontal, arranging contents from left to right.
+ * Get the inlined image object handle
*
- * @note This flag is ignored if a custom layout function is set.
+ * When you create a window with elm_win_add() of type ELM_WIN_INLINED_IMAGE,
+ * then the window is in fact an evas image object inlined in the parent
+ * canvas. You can get this object (be careful to not manipulate it as it
+ * is under control of elementary), and use it to do things like get pixel
+ * data, save the image to a file, etc.
*
- * @param obj The box object
- * @param horizontal The horizontal flag (EINA_TRUE = horizontal,
- * EINA_FALSE = vertical)
+ * @param obj The window object to get the inlined image from
+ * @return The inlined image object, or NULL if none exists
*/
- EAPI void elm_box_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_win_inlined_image_object_get(Evas_Object *obj);
/**
- * Get the horizontal orientation
+ * Set the enabled status for the focus highlight in a window
*
- * @param obj The box object
- * @return EINA_TRUE if the box is set to horizontal mode, EINA_FALSE otherwise
+ * This function will enable or disable the focus highlight only for the
+ * given window, regardless of the global setting for it
+ *
+ * @param obj The window where to enable the highlight
+ * @param enabled The enabled value for the highlight
*/
- EAPI Eina_Bool elm_box_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_focus_highlight_enabled_set(Evas_Object *obj, Eina_Bool enabled) EINA_ARG_NONNULL(1);
/**
- * Set the box to arrange its children homogeneously
- *
- * If enabled, homogeneous layout makes all items the same size, according
- * to the size of the largest of its children.
+ * Get the enabled value of the focus highlight for this window
*
- * @note This flag is ignored if a custom layout function is set.
+ * @param obj The window in which to check if the focus highlight is enabled
*
- * @param obj The box object
- * @param homogeneous The homogeneous flag
+ * @return EINA_TRUE if enabled, EINA_FALSE otherwise
*/
- EAPI void elm_box_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_win_focus_highlight_enabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get whether the box is using homogeneous mode or not
+ * Set the style for the focus highlight on this window
*
- * @param obj The box object
- * @return EINA_TRUE if it's homogeneous, EINA_FALSE otherwise
+ * Sets the style to use for theming the highlight of focused objects on
+ * the given window. If @p style is NULL, the default will be used.
+ *
+ * @param obj The window where to set the style
+ * @param style The style to set
*/
- EAPI Eina_Bool elm_box_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EINA_DEPRECATED EAPI void elm_box_homogenous_set(Evas_Object *obj, Eina_Bool homogenous) EINA_ARG_NONNULL(1);
- EINA_DEPRECATED EAPI Eina_Bool elm_box_homogenous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_focus_highlight_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
/**
- * Add an object to the beginning of the pack list
+ * Get the style set for the focus highlight object
*
- * Pack @p subobj into the box @p obj, placing it first in the list of
- * children objects. The actual position the object will get on screen
- * depends on the layout used. If no custom layout is set, it will be at
- * the top or left, depending if the box is vertical or horizontal,
- * respectively.
+ * Gets the style set for this windows highilght object, or NULL if none
+ * is set.
*
- * @param obj The box object
- * @param subobj The object to add to the box
+ * @param obj The window to retrieve the highlights style from
*
- * @see elm_box_pack_end()
- * @see elm_box_pack_before()
- * @see elm_box_pack_after()
- * @see elm_box_unpack()
- * @see elm_box_unpack_all()
- * @see elm_box_clear()
+ * @return The style set or NULL if none was. Default is used in that case.
*/
- EAPI void elm_box_pack_start(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
- /**
- * Add an object at the end of the pack list
- *
- * Pack @p subobj into the box @p obj, placing it last in the list of
- * children objects. The actual position the object will get on screen
- * depends on the layout used. If no custom layout is set, it will be at
- * the bottom or right, depending if the box is vertical or horizontal,
- * respectively.
+ EAPI const char *elm_win_focus_highlight_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /*...
+ * ecore_x_icccm_hints_set -> accepts_focus (add to ecore_evas)
+ * ecore_x_icccm_hints_set -> window_group (add to ecore_evas)
+ * ecore_x_icccm_size_pos_hints_set -> request_pos (add to ecore_evas)
+ * ecore_x_icccm_client_leader_set -> l (add to ecore_evas)
+ * ecore_x_icccm_window_role_set -> role (add to ecore_evas)
+ * ecore_x_icccm_transient_for_set -> forwin (add to ecore_evas)
+ * ecore_x_netwm_window_type_set -> type (add to ecore_evas)
*
- * @param obj The box object
- * @param subobj The object to add to the box
+ * (add to ecore_x) set netwm argb icon! (add to ecore_evas)
+ * (blank mouse, private mouse obj, defaultmouse)
*
- * @see elm_box_pack_start()
- * @see elm_box_pack_before()
- * @see elm_box_pack_after()
- * @see elm_box_unpack()
- * @see elm_box_unpack_all()
- * @see elm_box_clear()
*/
- EAPI void elm_box_pack_end(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
/**
- * Adds an object to the box before the indicated object
- *
- * This will add the @p subobj to the box indicated before the object
- * indicated with @p before. If @p before is not already in the box, results
- * are undefined. Before means either to the left of the indicated object or
- * above it depending on orientation.
+ * Sets the keyboard mode of the window.
*
- * @param obj The box object
- * @param subobj The object to add to the box
- * @param before The object before which to add it
+ * @param obj The window object
+ * @param mode The mode to set, one of #Elm_Win_Keyboard_Mode
+ */
+ EAPI void elm_win_keyboard_mode_set(Evas_Object *obj, Elm_Win_Keyboard_Mode mode) EINA_ARG_NONNULL(1);
+ /**
+ * Gets the keyboard mode of the window.
*
- * @see elm_box_pack_start()
- * @see elm_box_pack_end()
- * @see elm_box_pack_after()
- * @see elm_box_unpack()
- * @see elm_box_unpack_all()
- * @see elm_box_clear()
+ * @param obj The window object
+ * @return The mode, one of #Elm_Win_Keyboard_Mode
*/
- EAPI void elm_box_pack_before(Evas_Object *obj, Evas_Object *subobj, Evas_Object *before) EINA_ARG_NONNULL(1);
+ EAPI Elm_Win_Keyboard_Mode elm_win_keyboard_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Adds an object to the box after the indicated object
+ * Sets whether the window is a keyboard.
*
- * This will add the @p subobj to the box indicated after the object
- * indicated with @p after. If @p after is not already in the box, results
- * are undefined. After means either to the right of the indicated object or
- * below it depending on orientation.
+ * @param obj The window object
+ * @param is_keyboard If true, the window is a virtual keyboard
+ */
+ EAPI void elm_win_keyboard_win_set(Evas_Object *obj, Eina_Bool is_keyboard) EINA_ARG_NONNULL(1);
+ /**
+ * Gets whether the window is a keyboard.
*
- * @param obj The box object
- * @param subobj The object to add to the box
- * @param after The object after which to add it
+ * @param obj The window object
+ * @return If the window is a virtual keyboard
+ */
+ EAPI Eina_Bool elm_win_keyboard_win_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the screen position of a window.
*
- * @see elm_box_pack_start()
- * @see elm_box_pack_end()
- * @see elm_box_pack_before()
- * @see elm_box_unpack()
- * @see elm_box_unpack_all()
- * @see elm_box_clear()
+ * @param obj The window object
+ * @param x The int to store the x coordinate to
+ * @param y The int to store the y coordinate to
*/
- EAPI void elm_box_pack_after(Evas_Object *obj, Evas_Object *subobj, Evas_Object *after) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_screen_position_get(const Evas_Object *obj, int *x, int *y) EINA_ARG_NONNULL(1);
/**
- * Clear the box of all children
+ * @}
+ */
+
+ /**
+ * @defgroup Inwin Inwin
*
- * Remove all the elements contained by the box, deleting the respective
- * objects.
+ * @image html img/widget/inwin/preview-00.png
+ * @image latex img/widget/inwin/preview-00.eps
+ * @image html img/widget/inwin/preview-01.png
+ * @image latex img/widget/inwin/preview-01.eps
+ * @image html img/widget/inwin/preview-02.png
+ * @image latex img/widget/inwin/preview-02.eps
*
- * @param obj The box object
+ * An inwin is a window inside a window that is useful for a quick popup.
+ * It does not hover.
*
- * @see elm_box_unpack()
- * @see elm_box_unpack_all()
- */
- EAPI void elm_box_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Unpack a box item
+ * It works by creating an object that will occupy the entire window, so it
+ * must be created using an @ref Win "elm_win" as parent only. The inwin
+ * object can be hidden or restacked below every other object if it's
+ * needed to show what's behind it without destroying it. If this is done,
+ * the elm_win_inwin_activate() function can be used to bring it back to
+ * full visibility again.
*
- * Remove the object given by @p subobj from the box @p obj without
- * deleting it.
+ * There are three styles available in the default theme. These are:
+ * @li default: The inwin is sized to take over most of the window it's
+ * placed in.
+ * @li minimal: The size of the inwin will be the minimum necessary to show
+ * its contents.
+ * @li minimal_vertical: Horizontally, the inwin takes as much space as
+ * possible, but it's sized vertically the most it needs to fit its\
+ * contents.
*
- * @param obj The box object
+ * Some examples of Inwin can be found in the following:
+ * @li @ref inwin_example_01
*
- * @see elm_box_unpack_all()
- * @see elm_box_clear()
+ * @{
*/
- EAPI void elm_box_unpack(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
/**
- * Remove all items from the box, without deleting them
+ * Adds an inwin to the current window
*
- * Clear the box from all children, but don't delete the respective objects.
- * If no other references of the box children exist, the objects will never
- * be deleted, and thus the application will leak the memory. Make sure
- * when using this function that you hold a reference to all the objects
- * in the box @p obj.
+ * The @p obj used as parent @b MUST be an @ref Win "Elementary Window".
+ * Never call this function with anything other than the top-most window
+ * as its parameter, unless you are fond of undefined behavior.
*
- * @param obj The box object
+ * After creating the object, the widget will set itself as resize object
+ * for the window with elm_win_resize_object_add(), so when shown it will
+ * appear to cover almost the entire window (how much of it depends on its
+ * content and the style used). It must not be added into other container
+ * objects and it needs not be moved or resized manually.
*
- * @see elm_box_clear()
- * @see elm_box_unpack()
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*/
- EAPI void elm_box_unpack_all(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_win_inwin_add(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Retrieve a list of the objects packed into the box
+ * Activates an inwin object, ensuring its visibility
*
- * Returns a new @c Eina_List with a pointer to @c Evas_Object in its nodes.
- * The order of the list corresponds to the packing order the box uses.
+ * This function will make sure that the inwin @p obj is completely visible
+ * by calling evas_object_show() and evas_object_raise() on it, to bring it
+ * to the front. It also sets the keyboard focus to it, which will be passed
+ * onto its content.
*
- * You must free this list with eina_list_free() once you are done with it.
+ * The object's theme will also receive the signal "elm,action,show" with
+ * source "elm".
*
- * @param obj The box object
+ * @param obj The inwin to activate
*/
- EAPI const Eina_List *elm_box_children_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_inwin_activate(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the space (padding) between the box's elements.
+ * Set the content of an inwin object.
*
- * Extra space in pixels that will be added between a box child and its
- * neighbors after its containing cell has been calculated. This padding
- * is set for all elements in the box, besides any possible padding that
- * individual elements may have through their size hints.
+ * Once the content object is set, a previously set one will be deleted.
+ * If you want to keep that old content object, use the
+ * elm_win_inwin_content_unset() function.
*
- * @param obj The box object
- * @param horizontal The horizontal space between elements
- * @param vertical The vertical space between elements
+ * @param obj The inwin object
+ * @param content The object to set as content
*/
- EAPI void elm_box_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
+ EAPI void elm_win_inwin_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
/**
- * Get the space (padding) between the box's elements.
+ * Get the content of an inwin object.
*
- * @param obj The box object
- * @param horizontal The horizontal space between elements
- * @param vertical The vertical space between elements
+ * Return the content object which is set for this widget.
*
- * @see elm_box_padding_set()
+ * The returned object is valid as long as the inwin is still alive and no
+ * other content is set on it. Deleting the object will notify the inwin
+ * about it and this one will be left empty.
+ *
+ * If you need to remove an inwin's content to be reused somewhere else,
+ * see elm_win_inwin_content_unset().
+ *
+ * @param obj The inwin object
+ * @return The content that is being used
*/
- EAPI void elm_box_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_win_inwin_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the alignment of the whole bouding box of contents.
+ * Unset the content of an inwin object.
*
- * Sets how the bounding box containing all the elements of the box, after
- * their sizes and position has been calculated, will be aligned within
- * the space given for the whole box widget.
+ * Unparent and return the content object which was set for this widget.
*
- * @param obj The box object
- * @param horizontal The horizontal alignment of elements
- * @param vertical The vertical alignment of elements
+ * @param obj The inwin object
+ * @return The content that was being used
*/
- EAPI void elm_box_align_set(Evas_Object *obj, double horizontal, double vertical) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_win_inwin_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the alignment of the whole bouding box of contents.
+ * @}
+ */
+ /* X specific calls - won't work on non-x engines (return 0) */
+
+ /**
+ * Get the Ecore_X_Window of an Evas_Object
*
- * @param obj The box object
- * @param horizontal The horizontal alignment of elements
- * @param vertical The vertical alignment of elements
+ * @param obj The object
*
- * @see elm_box_align_set()
+ * @return The Ecore_X_Window of @p obj
+ *
+ * @ingroup Win
+ */
+ EAPI Ecore_X_Window elm_win_xwindow_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /* smart callbacks called:
+ * "delete,request" - the user requested to delete the window
+ * "focus,in" - window got focus
+ * "focus,out" - window lost focus
+ * "moved" - window that holds the canvas was moved
*/
- EAPI void elm_box_align_get(const Evas_Object *obj, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
/**
- * Set the layout defining function to be used by the box
+ * @defgroup Bg Bg
*
- * Whenever anything changes that requires the box in @p obj to recalculate
- * the size and position of its elements, the function @p cb will be called
- * to determine what the layout of the children will be.
+ * @image html img/widget/bg/preview-00.png
+ * @image latex img/widget/bg/preview-00.eps
*
- * Once a custom function is set, everything about the children layout
- * is defined by it. The flags set by elm_box_horizontal_set() and
- * elm_box_homogeneous_set() no longer have any meaning, and the values
- * given by elm_box_padding_set() and elm_box_align_set() are up to this
- * layout function to decide if they are used and how. These last two
- * will be found in the @c priv parameter, of type @c Evas_Object_Box_Data,
- * passed to @p cb. The @c Evas_Object the function receives is not the
- * Elementary widget, but the internal Evas Box it uses, so none of the
- * functions described here can be used on it.
+ * @brief Background object, used for setting a solid color, image or Edje
+ * group as background to a window or any container object.
*
- * Any of the layout functions in @c Evas can be used here, as well as the
- * special elm_box_layout_transition().
- *
- * The final @p data argument received by @p cb is the same @p data passed
- * here, and the @p free_data function will be called to free it
- * whenever the box is destroyed or another layout function is set.
- *
- * Setting @p cb to NULL will revert back to the default layout function.
- *
- * @param obj The box object
- * @param cb The callback function used for layout
- * @param data Data that will be passed to layout function
- * @param free_data Function called to free @p data
+ * The bg object is used for setting a solid background to a window or
+ * packing into any container object. It works just like an image, but has
+ * some properties useful to a background, like setting it to tiled,
+ * centered, scaled or stretched.
*
- * @see elm_box_layout_transition()
+ * Here is some sample code using it:
+ * @li @ref bg_01_example_page
+ * @li @ref bg_02_example_page
+ * @li @ref bg_03_example_page
*/
- EAPI void elm_box_layout_set(Evas_Object *obj, Evas_Object_Box_Layout cb, const void *data, void (*free_data)(void *data)) EINA_ARG_NONNULL(1);
+
+ /* bg */
+ typedef enum _Elm_Bg_Option
+ {
+ ELM_BG_OPTION_CENTER, /**< center the background */
+ ELM_BG_OPTION_SCALE, /**< scale the background retaining aspect ratio */
+ ELM_BG_OPTION_STRETCH, /**< stretch the background to fill */
+ ELM_BG_OPTION_TILE /**< tile background at its original size */
+ } Elm_Bg_Option;
+
/**
- * Special layout function that animates the transition from one layout to another
- *
- * Normally, when switching the layout function for a box, this will be
- * reflected immediately on screen on the next render, but it's also
- * possible to do this through an animated transition.
- *
- * This is done by creating an ::Elm_Box_Transition and setting the box
- * layout to this function.
- *
- * For example:
- * @code
- * Elm_Box_Transition *t = elm_box_transition_new(1.0,
- * evas_object_box_layout_vertical, // start
- * NULL, // data for initial layout
- * NULL, // free function for initial data
- * evas_object_box_layout_horizontal, // end
- * NULL, // data for final layout
- * NULL, // free function for final data
- * anim_end, // will be called when animation ends
- * NULL); // data for anim_end function\
- * elm_box_layout_set(box, elm_box_layout_transition, t,
- * elm_box_transition_free);
- * @endcode
+ * Add a new background to the parent
*
- * @note This function can only be used with elm_box_layout_set(). Calling
- * it directly will not have the expected results.
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*
- * @see elm_box_transition_new
- * @see elm_box_transition_free
- * @see elm_box_layout_set
+ * @ingroup Bg
*/
- EAPI void elm_box_layout_transition(Evas_Object *obj, Evas_Object_Box_Data *priv, void *data);
+ EAPI Evas_Object *elm_bg_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
/**
- * Create a new ::Elm_Box_Transition to animate the switch of layouts
+ * Set the file (image or edje) used for the background
*
- * If you want to animate the change from one layout to another, you need
- * to set the layout function of the box to elm_box_layout_transition(),
- * passing as user data to it an instance of ::Elm_Box_Transition with the
- * necessary information to perform this animation. The free function to
- * set for the layout is elm_box_transition_free().
+ * @param obj The bg object
+ * @param file The file path
+ * @param group Optional key (group in Edje) within the file
*
- * The parameters to create an ::Elm_Box_Transition sum up to how long
- * will it be, in seconds, a layout function to describe the initial point,
- * another for the final position of the children and one function to be
- * called when the whole animation ends. This last function is useful to
- * set the definitive layout for the box, usually the same as the end
- * layout for the animation, but could be used to start another transition.
+ * This sets the image file used in the background object. The image (or edje)
+ * will be stretched (retaining aspect if its an image file) to completely fill
+ * the bg object. This may mean some parts are not visible.
*
- * @param start_layout The layout function that will be used to start the animation
- * @param start_layout_data The data to be passed the @p start_layout function
- * @param start_layout_free_data Function to free @p start_layout_data
- * @param end_layout The layout function that will be used to end the animation
- * @param end_layout_free_data The data to be passed the @p end_layout function
- * @param end_layout_free_data Function to free @p end_layout_data
- * @param transition_end_cb Callback function called when animation ends
- * @param transition_end_data Data to be passed to @p transition_end_cb
- * @return An instance of ::Elm_Box_Transition
+ * @note Once the image of @p obj is set, a previously set one will be deleted,
+ * even if @p file is NULL.
*
- * @see elm_box_transition_new
- * @see elm_box_layout_transition
+ * @ingroup Bg
*/
- EAPI Elm_Box_Transition *elm_box_transition_new(const double duration, Evas_Object_Box_Layout start_layout, void *start_layout_data, void(*start_layout_free_data)(void *data), Evas_Object_Box_Layout end_layout, void *end_layout_data, void(*end_layout_free_data)(void *data), void(*transition_end_cb)(void *data), void *transition_end_data) EINA_ARG_NONNULL(2, 5);
+ EAPI void elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1);
+
/**
- * Free a Elm_Box_Transition instance created with elm_box_transition_new().
- *
- * This function is mostly useful as the @c free_data parameter in
- * elm_box_layout_set() when elm_box_layout_transition().
+ * Get the file (image or edje) used for the background
*
- * @param data The Elm_Box_Transition instance to be freed.
+ * @param obj The bg object
+ * @param file The file path
+ * @param group Optional key (group in Edje) within the file
*
- * @see elm_box_transition_new
- * @see elm_box_layout_transition
- */
- EAPI void elm_box_transition_free(void *data);
- /**
- * @}
+ * @ingroup Bg
*/
+ EAPI void elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
- /* button */
/**
- * @defgroup Button Button
- *
- * @image html img/widget/button/preview-00.png
- * @image html img/widget/button/preview-01.png
- * @image html img/widget/button/preview-02.png
- *
- * This is a push-button. Press it and run some function. It can contain
- * a simple label and icon object and it also has an autorepeat feature.
+ * Set the option used for the background image
*
- * This widgets emits the following signals:
- * @li "clicked": the user clicked the button (press/release).
- * @li "repeated": the user pressed the button without releasing it.
- * @li "pressed": button was pressed.
- * @li "unpressed": button was released after being pressed.
- * In all three cases, the @c event parameter of the callback will be
- * @c NULL.
+ * @param obj The bg object
+ * @param option The desired background option (TILE, SCALE)
*
- * Also, defined in the default theme, the button has the following styles
- * available:
- * @li default: a normal button.
- * @li anchor: Like default, but the button fades away when the mouse is not
- * over it, leaving only the text or icon.
- * @li hoversel_vertical: Internally used by @ref Hoversel to give a
- * continuous look across its options.
- * @li hoversel_vertical_entry: Another internal for @ref Hoversel.
+ * This sets the option used for manipulating the display of the background
+ * image. The image can be tiled or scaled.
*
- * Follow through a complete example @ref button_example_01 "here".
- * @{
+ * @ingroup Bg
*/
+ EAPI void elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option) EINA_ARG_NONNULL(1);
+
/**
- * Add a new button to the parent's canvas
+ * Get the option used for the background image
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * @param obj The bg object
+ * @return The desired background option (CENTER, SCALE, STRETCH or TILE)
+ *
+ * @ingroup Bg
*/
- EAPI Evas_Object *elm_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI Elm_Bg_Option elm_bg_option_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the label used in the button
+ * Set the option used for the background color
*
- * The passed @p label can be NULL to clean any existing text in it and
- * leave the button as an icon only object.
+ * @param obj The bg object
+ * @param r
+ * @param g
+ * @param b
*
- * @param obj The button object
- * @param label The text will be written on the button
- * @deprecated use elm_object_text_set() instead.
+ * This sets the color used for the background rectangle. Its range goes
+ * from 0 to 255.
+ *
+ * @ingroup Bg
*/
- EINA_DEPRECATED EAPI void elm_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+ EAPI void elm_bg_color_set(Evas_Object *obj, int r, int g, int b) EINA_ARG_NONNULL(1);
/**
- * Get the label set for the button
+ * Get the option used for the background color
*
- * The string returned is an internal pointer and should not be freed or
- * altered. It will also become invalid when the button is destroyed.
- * The string returned, if not NULL, is a stringshare, so if you need to
- * keep it around even after the button is destroyed, you can use
- * eina_stringshare_ref().
+ * @param obj The bg object
+ * @param r
+ * @param g
+ * @param b
*
- * @param obj The button object
- * @return The text set to the label, or NULL if nothing is set
- * @deprecated use elm_object_text_set() instead.
+ * @ingroup Bg
*/
- EINA_DEPRECATED EAPI const char *elm_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b) EINA_ARG_NONNULL(1);
+
/**
- * Set the icon used for the button
+ * Set the overlay object used for the background object.
*
- * Setting a new icon will delete any other that was previously set, making
- * any reference to them invalid. If you need to maintain the previous
- * object alive, unset it first with elm_button_icon_unset().
+ * @param obj The bg object
+ * @param overlay The overlay object
*
- * @param obj The button object
- * @param icon The icon object for the button
+ * This provides a way for elm_bg to have an 'overlay' that will be on top
+ * of the bg. Once the over object is set, a previously set one will be
+ * deleted, even if you set the new one to NULL. If you want to keep that
+ * old content object, use the elm_bg_overlay_unset() function.
+ *
+ * @ingroup Bg
*/
- EAPI void elm_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+
+ EAPI void elm_bg_overlay_set(Evas_Object *obj, Evas_Object *overlay) EINA_ARG_NONNULL(1);
+
/**
- * Get the icon used for the button
+ * Get the overlay object used for the background object.
*
- * Return the icon object which is set for this widget. If the button is
- * destroyed or another icon is set, the returned object will be deleted
- * and any reference to it will be invalid.
+ * @param obj The bg object
+ * @return The content that is being used
*
- * @param obj The button object
- * @return The icon object that is being used
+ * Return the content object which is set for this widget
*
- * @see elm_button_icon_unset()
+ * @ingroup Bg
*/
- EAPI Evas_Object *elm_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_bg_overlay_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Remove the icon set without deleting it and return the object
+ * Get the overlay object used for the background object.
*
- * This function drops the reference the button holds of the icon object
- * and returns this last object. It is used in case you want to remove any
- * icon, or set another one, without deleting the actual object. The button
- * will be left without an icon set.
+ * @param obj The bg object
+ * @return The content that was being used
*
- * @param obj The button object
- * @return The icon object that was being used
+ * Unparent and return the overlay object which was set for this widget
+ *
+ * @ingroup Bg
*/
- EAPI Evas_Object *elm_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_bg_overlay_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Turn on/off the autorepeat event generated when the button is kept pressed
+ * Set the size of the pixmap representation of the image.
*
- * When off, no autorepeat is performed and buttons emit a normal @c clicked
- * signal when they are clicked.
+ * This option just makes sense if an image is going to be set in the bg.
*
- * When on, keeping a button pressed will continuously emit a @c repeated
- * signal until the button is released. The time it takes until it starts
- * emitting the signal is given by
- * elm_button_autorepeat_initial_timeout_set(), and the time between each
- * new emission by elm_button_autorepeat_gap_timeout_set().
- *
- * @param obj The button object
- * @param on A bool to turn on/off the event
- */
- EAPI void elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on) EINA_ARG_NONNULL(1);
- /**
- * Get whether the autorepeat feature is enabled
- *
- * @param obj The button object
- * @return EINA_TRUE if autorepeat is on, EINA_FALSE otherwise
- *
- * @see elm_button_autorepeat_set()
- */
- EAPI Eina_Bool elm_button_autorepeat_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Set the initial timeout before the autorepeat event is generated
+ * @param obj The bg object
+ * @param w The new width of the image pixmap representation.
+ * @param h The new height of the image pixmap representation.
*
- * Sets the timeout, in seconds, since the button is pressed until the
- * first @c repeated signal is emitted. If @p t is 0.0 or less, there
- * won't be any delay and the even will be fired the moment the button is
- * pressed.
+ * This function sets a new size for pixmap representation of the given bg
+ * image. It allows the image to be loaded already in the specified size,
+ * reducing the memory usage and load time when loading a big image with load
+ * size set to a smaller size.
*
- * @param obj The button object
- * @param t Timeout in seconds
+ * NOTE: this is just a hint, the real size of the pixmap may differ
+ * depending on the type of image being loaded, being bigger than requested.
*
- * @see elm_button_autorepeat_set()
- * @see elm_button_autorepeat_gap_timeout_set()
+ * @ingroup Bg
*/
- EAPI void elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
- /**
- * Get the initial timeout before the autorepeat event is generated
- *
- * @param obj The button object
- * @return Timeout in seconds
- *
- * @see elm_button_autorepeat_initial_timeout_set()
+ EAPI void elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+ /* smart callbacks called:
*/
- EAPI double elm_button_autorepeat_initial_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Set the interval between each generated autorepeat event
+ * @defgroup Icon Icon
*
- * After the first @c repeated event is fired, all subsequent ones will
- * follow after a delay of @p t seconds for each.
+ * @image html img/widget/icon/preview-00.png
+ * @image latex img/widget/icon/preview-00.eps
*
- * @param obj The button object
- * @param t Interval in seconds
+ * An object that provides standard icon images (delete, edit, arrows, etc.)
+ * or a custom file (PNG, JPG, EDJE, etc.) used for an icon.
*
- * @see elm_button_autorepeat_initial_timeout_set()
- */
- EAPI void elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
- /**
- * Get the interval between each generated autorepeat event
+ * The icon image requested can be in the elementary theme, or in the
+ * freedesktop.org paths. It's possible to set the order of preference from
+ * where the image will be used.
*
- * @param obj The button object
- * @return Interval in seconds
- */
- EAPI double elm_button_autorepeat_gap_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * @}
- */
-
- /**
- * @defgroup File_Selector_Button File Selector Button
+ * This API is very similar to @ref Image, but with ready to use images.
*
- * @image html img/widget/fileselector_button/preview-00.png
- * @image html img/widget/fileselector_button/preview-01.png
- * @image html img/widget/fileselector_button/preview-02.png
+ * Default images provided by the theme are described below.
*
- * This is a button that, when clicked, creates an Elementary
- * window (or inner window) <b> with a @ref Fileselector "file
- * selector widget" within</b>. When a file is chosen, the (inner)
- * window is closed and the button emits a signal having the
- * selected file as it's @c event_info.
+ * The first list contains icons that were first intended to be used in
+ * toolbars, but can be used in many other places too:
+ * @li home
+ * @li close
+ * @li apps
+ * @li arrow_up
+ * @li arrow_down
+ * @li arrow_left
+ * @li arrow_right
+ * @li chat
+ * @li clock
+ * @li delete
+ * @li edit
+ * @li refresh
+ * @li folder
+ * @li file
*
- * This widget encapsulates operations on its internal file
- * selector on its own API. There is less control over its file
- * selector than that one would have instatiating one directly.
+ * Now some icons that were designed to be used in menus (but again, you can
+ * use them anywhere else):
+ * @li menu/home
+ * @li menu/close
+ * @li menu/apps
+ * @li menu/arrow_up
+ * @li menu/arrow_down
+ * @li menu/arrow_left
+ * @li menu/arrow_right
+ * @li menu/chat
+ * @li menu/clock
+ * @li menu/delete
+ * @li menu/edit
+ * @li menu/refresh
+ * @li menu/folder
+ * @li menu/file
*
- * The following styles are available for this button:
- * @li @c "default"
- * @li @c "anchor"
- * @li @c "hoversel_vertical"
- * @li @c "hoversel_vertical_entry"
+ * And here we have some media player specific icons:
+ * @li media_player/forward
+ * @li media_player/info
+ * @li media_player/next
+ * @li media_player/pause
+ * @li media_player/play
+ * @li media_player/prev
+ * @li media_player/rewind
+ * @li media_player/stop
*
- * Smart callbacks one can register to:
- * - @c "file,chosen" - the user has selected a path, whose string
- * pointer comes as the @c event_info data (a stringshared
- * string)
+ * Signals that you can add callbacks for are:
*
- * Here is an example on its usage:
- * @li @ref fileselector_button_example
+ * "clicked" - This is called when a user has clicked the icon
*
- * @see @ref File_Selector_Entry for a similar widget.
- * @{
+ * An example of usage for this API follows:
+ * @li @ref tutorial_icon
*/
/**
- * Add a new file selector button widget to the given parent
- * Elementary (container) object
- *
- * @param parent The parent object
- * @return a new file selector button widget handle or @c NULL, on
- * errors
+ * @addtogroup Icon
+ * @{
*/
- EAPI Evas_Object *elm_fileselector_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ typedef enum _Elm_Icon_Type
+ {
+ ELM_ICON_NONE,
+ ELM_ICON_FILE,
+ ELM_ICON_STANDARD
+ } Elm_Icon_Type;
/**
- * Set the label for a given file selector button widget
+ * @enum _Elm_Icon_Lookup_Order
+ * @typedef Elm_Icon_Lookup_Order
*
- * @param obj The file selector button widget
- * @param label The text label to be displayed on @p obj
+ * Lookup order used by elm_icon_standard_set(). Should look for icons in the
+ * theme, FDO paths, or both?
*
- * @deprecated use elm_object_text_set() instead.
+ * @ingroup Icon
*/
- EINA_DEPRECATED EAPI void elm_fileselector_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+ typedef enum _Elm_Icon_Lookup_Order
+ {
+ ELM_ICON_LOOKUP_FDO_THEME, /**< icon look up order: freedesktop, theme */
+ ELM_ICON_LOOKUP_THEME_FDO, /**< icon look up order: theme, freedesktop */
+ ELM_ICON_LOOKUP_FDO, /**< icon look up order: freedesktop */
+ ELM_ICON_LOOKUP_THEME /**< icon look up order: theme */
+ } Elm_Icon_Lookup_Order;
/**
- * Get the label set for a given file selector button widget
+ * Add a new icon object to the parent.
*
- * @param obj The file selector button widget
- * @return The button label
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*
- * @deprecated use elm_object_text_set() instead.
+ * @see elm_icon_file_set()
+ *
+ * @ingroup Icon
*/
- EINA_DEPRECATED EAPI const char *elm_fileselector_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI Evas_Object *elm_icon_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * Set the icon on a given file selector button widget
+ * Set the file that will be used as icon.
*
- * @param obj The file selector button widget
- * @param icon The icon object for the button
+ * @param obj The icon object
+ * @param file The path to file that will be used as icon image
+ * @param group The group that the icon belongs to in edje file
*
- * Once the icon object is set, a previously set one will be
- * deleted. If you want to keep the latter, use the
- * elm_fileselector_button_icon_unset() function.
+ * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
*
- * @see elm_fileselector_button_icon_get()
+ * @note The icon image set by this function can be changed by
+ * elm_icon_standard_set().
+ *
+ * @see elm_icon_file_get()
+ *
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_icon_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
/**
- * Get the icon set for a given file selector button widget
+ * Set a location in memory to be used as an icon
*
- * @param obj The file selector button widget
- * @return The icon object currently set on @p obj or @c NULL, if
- * none is
+ * @param obj The icon object
+ * @param img The binary data that will be used as an image
+ * @param size The size of binary data @p img
+ * @param format Optional format of @p img to pass to the image loader
+ * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
*
- * @see elm_fileselector_button_icon_set()
+ * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
+ *
+ * @note The icon image set by this function can be changed by
+ * elm_icon_standard_set().
+ *
+ * @ingroup Icon
*/
- EAPI Evas_Object *elm_fileselector_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_icon_memfile_set(Evas_Object *obj, const void *img, size_t size, const char *format, const char *key); EINA_ARG_NONNULL(1, 2);
/**
- * Unset the icon used in a given file selector button widget
+ * Get the file that will be used as icon.
*
- * @param obj The file selector button widget
- * @return The icon object that was being used on @p obj or @c
- * NULL, on errors
+ * @param obj The icon object
+ * @param file The path to file that will be used as icon icon image
+ * @param group The group that the icon belongs to in edje file
*
- * Unparent and return the icon object which was set for this
- * widget.
+ * @see elm_icon_file_set()
*
- * @see elm_fileselector_button_icon_set()
+ * @ingroup Icon
*/
- EAPI Evas_Object *elm_fileselector_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
+ EAPI void elm_icon_thumb_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
/**
- * Set the title for a given file selector button widget's window
+ * Set the icon by icon standards names.
*
- * @param obj The file selector button widget
- * @param title The title string
+ * @param obj The icon object
+ * @param name The icon name
*
- * This will change the window's title, when the file selector pops
- * out after a click on the button. Those windows have the default
- * (unlocalized) value of @c "Select a file" as titles.
+ * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
*
- * @note It will only take any effect if the file selector
- * button widget is @b not under "inwin mode".
+ * For example, freedesktop.org defines standard icon names such as "home",
+ * "network", etc. There can be different icon sets to match those icon
+ * keys. The @p name given as parameter is one of these "keys", and will be
+ * used to look in the freedesktop.org paths and elementary theme. One can
+ * change the lookup order with elm_icon_order_lookup_set().
*
- * @see elm_fileselector_button_window_title_get()
- */
- EAPI void elm_fileselector_button_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
-
- /**
- * Get the title set for a given file selector button widget's
- * window
+ * If name is not found in any of the expected locations and it is the
+ * absolute path of an image file, this image will be used.
*
- * @param obj The file selector button widget
- * @return Title of the file selector button's window
+ * @note The icon image set by this function can be changed by
+ * elm_icon_file_set().
*
- * @see elm_fileselector_button_window_title_get() for more details
+ * @see elm_icon_standard_get()
+ * @see elm_icon_file_set()
+ *
+ * @ingroup Icon
*/
- EAPI const char *elm_fileselector_button_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_icon_standard_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
/**
- * Set the size of a given file selector button widget's window,
- * holding the file selector itself.
+ * Get the icon name set by icon standard names.
*
- * @param obj The file selector button widget
- * @param width The window's width
- * @param height The window's height
+ * @param obj The icon object
+ * @return The icon name
*
- * @note it will only take any effect if the file selector button
- * widget is @b not under "inwin mode". The default size for the
- * window (when applicable) is 400x400 pixels.
+ * If the icon image was set using elm_icon_file_set() instead of
+ * elm_icon_standard_set(), then this function will return @c NULL.
*
- * @see elm_fileselector_button_window_size_get()
+ * @see elm_icon_standard_set()
+ *
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_button_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
-
+ EAPI const char *elm_icon_standard_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the size of a given file selector button widget's window,
- * holding the file selector itself.
+ * Set the smooth effect for an icon object.
*
- * @param obj The file selector button widget
- * @param width Pointer into which to store the width value
- * @param height Pointer into which to store the height value
+ * @param obj The icon object
+ * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
+ * otherwise. Default is @c EINA_TRUE.
*
- * @note Use @c NULL pointers on the size values you're not
- * interested in: they'll be ignored by the function.
+ * Set the scaling algorithm to be used when scaling the icon image. Smooth
+ * scaling provides a better resulting image, but is slower.
*
- * @see elm_fileselector_button_window_size_set(), for more details
+ * The smooth scaling should be disabled when making animations that change
+ * the icon size, since they will be faster. Animations that don't require
+ * resizing of the icon can keep the smooth scaling enabled (even if the icon
+ * is already scaled, since the scaled icon image will be cached).
+ *
+ * @see elm_icon_smooth_get()
+ *
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_button_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1);
/**
- * Set the initial file system path for a given file selector
- * button widget
+ * Get the smooth effect for an icon object.
*
- * @param obj The file selector button widget
- * @param path The path string
+ * @param obj The icon object
+ * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
*
- * It must be a <b>directory</b> path, which will have the contents
- * displayed initially in the file selector's view, when invoked
- * from @p obj. The default initial path is the @c "HOME"
- * environment variable's value.
+ * @see elm_icon_smooth_set()
*
- * @see elm_fileselector_button_path_get()
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_button_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_icon_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the initial file system path set for a given file selector
- * button widget
+ * Disable scaling of this object.
*
- * @param obj The file selector button widget
- * @return path The path string
+ * @param obj The icon object.
+ * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
+ * otherwise. Default is @c EINA_FALSE.
*
- * @see elm_fileselector_button_path_set() for more details
+ * This function disables scaling of the icon object through the function
+ * elm_object_scale_set(). However, this does not affect the object
+ * size/resize in any way. For that effect, take a look at
+ * elm_icon_scale_set().
+ *
+ * @see elm_icon_no_scale_get()
+ * @see elm_icon_scale_set()
+ * @see elm_object_scale_set()
+ *
+ * @ingroup Icon
*/
- EAPI const char *elm_fileselector_button_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1);
/**
- * Enable/disable a tree view in the given file selector button
- * widget's internal file selector
- *
- * @param obj The file selector button widget
- * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
- * disable
+ * Get whether scaling is disabled on the object.
*
- * This has the same effect as elm_fileselector_expandable_set(),
- * but now applied to a file selector button's internal file
- * selector.
+ * @param obj The icon object
+ * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
*
- * @note There's no way to put a file selector button's internal
- * file selector in "grid mode", as one may do with "pure" file
- * selectors.
+ * @see elm_icon_no_scale_set()
*
- * @see elm_fileselector_expandable_get()
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_button_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_icon_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get whether tree view is enabled for the given file selector
- * button widget's internal file selector
+ * Set if the object is (up/down) resizable.
*
- * @param obj The file selector button widget
- * @return @c EINA_TRUE if @p obj widget's internal file selector
- * is in tree view, @c EINA_FALSE otherwise (and or errors)
+ * @param obj The icon object
+ * @param scale_up A bool to set if the object is resizable up. Default is
+ * @c EINA_TRUE.
+ * @param scale_down A bool to set if the object is resizable down. Default
+ * is @c EINA_TRUE.
*
- * @see elm_fileselector_expandable_set() for more details
+ * This function limits the icon object resize ability. If @p scale_up is set to
+ * @c EINA_FALSE, the object can't have its height or width resized to a value
+ * higher than the original icon size. Same is valid for @p scale_down.
+ *
+ * @see elm_icon_scale_get()
+ *
+ * @ingroup Icon
*/
- EAPI Eina_Bool elm_fileselector_button_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1);
/**
- * Set whether a given file selector button widget's internal file
- * selector is to display folders only or the directory contents,
- * as well.
+ * Get if the object is (up/down) resizable.
*
- * @param obj The file selector button widget
- * @param only @c EINA_TRUE to make @p obj widget's internal file
- * selector only display directories, @c EINA_FALSE to make files
- * to be displayed in it too
+ * @param obj The icon object
+ * @param scale_up A bool to set if the object is resizable up
+ * @param scale_down A bool to set if the object is resizable down
*
- * This has the same effect as elm_fileselector_folder_only_set(),
- * but now applied to a file selector button's internal file
- * selector.
+ * @see elm_icon_scale_set()
*
- * @see elm_fileselector_folder_only_get()
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_button_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1);
/**
- * Get whether a given file selector button widget's internal file
- * selector is displaying folders only or the directory contents,
- * as well.
+ * Get the object's image size
*
- * @param obj The file selector button widget
- * @return @c EINA_TRUE if @p obj widget's internal file
- * selector is only displaying directories, @c EINA_FALSE if files
- * are being displayed in it too (and on errors)
+ * @param obj The icon object
+ * @param w A pointer to store the width in
+ * @param h A pointer to store the height in
*
- * @see elm_fileselector_button_folder_only_set() for more details
+ * @ingroup Icon
*/
- EAPI Eina_Bool elm_fileselector_button_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
/**
- * Enable/disable the file name entry box where the user can type
- * in a name for a file, in a given file selector button widget's
- * internal file selector.
+ * Set if the icon fill the entire object area.
*
- * @param obj The file selector button widget
- * @param is_save @c EINA_TRUE to make @p obj widget's internal
- * file selector a "saving dialog", @c EINA_FALSE otherwise
+ * @param obj The icon object
+ * @param fill_outside @c EINA_TRUE if the object is filled outside,
+ * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
*
- * This has the same effect as elm_fileselector_is_save_set(),
- * but now applied to a file selector button's internal file
- * selector.
+ * When the icon object is resized to a different aspect ratio from the
+ * original icon image, the icon image will still keep its aspect. This flag
+ * tells how the image should fill the object's area. They are: keep the
+ * entire icon inside the limits of height and width of the object (@p
+ * fill_outside is @c EINA_FALSE) or let the extra width or height go outside
+ * of the object, and the icon will fill the entire object (@p fill_outside
+ * is @c EINA_TRUE).
*
- * @see elm_fileselector_is_save_get()
- */
- EAPI void elm_fileselector_button_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
- /**
- * Get whether the given file selector button widget's internal
- * file selector is in "saving dialog" mode
+ * @note Unlike @ref Image, there's no option in icon to set the aspect ratio
+ * retain property to false. Thus, the icon image will always keep its
+ * original aspect ratio.
*
- * @param obj The file selector button widget
- * @return @c EINA_TRUE, if @p obj widget's internal file selector
- * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
- * errors)
+ * @see elm_icon_fill_outside_get()
+ * @see elm_image_fill_outside_set()
*
- * @see elm_fileselector_button_is_save_set() for more details
+ * @ingroup Icon
*/
- EAPI Eina_Bool elm_fileselector_button_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1);
/**
- * Set whether a given file selector button widget's internal file
- * selector will raise an Elementary "inner window", instead of a
- * dedicated Elementary window. By default, it won't.
+ * Get if the object is filled outside.
*
- * @param obj The file selector button widget
- * @param value @c EINA_TRUE to make it use an inner window, @c
- * EINA_TRUE to make it use a dedicated window
+ * @param obj The icon object
+ * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
*
- * @see elm_win_inwin_add() for more information on inner windows
- * @see elm_fileselector_button_inwin_mode_get()
+ * @see elm_icon_fill_outside_set()
+ *
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_button_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_icon_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get whether a given file selector button widget's internal file
- * selector will raise an Elementary "inner window", instead of a
- * dedicated Elementary window.
- *
- * @param obj The file selector button widget
- * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
- * if it will use a dedicated window
+ * Set the prescale size for the icon.
*
- * @see elm_fileselector_button_inwin_mode_set() for more details
- */
- EAPI Eina_Bool elm_fileselector_button_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * @}
- */
-
- /**
- * @defgroup File_Selector_Entry File Selector Entry
- *
- * @image html img/widget/fileselector_entry/preview-00.png
- * @image latex img/widget/fileselector_entry/preview-00.eps
- *
- * This is an entry made to be filled with or display a <b>file
- * system path string</b>. Besides the entry itself, the widget has
- * a @ref File_Selector_Button "file selector button" on its side,
- * which will raise an internal @ref Fileselector "file selector widget",
- * when clicked, for path selection aided by file system
- * navigation.
+ * @param obj The icon object
+ * @param size The prescale size. This value is used for both width and
+ * height.
*
- * This file selector may appear in an Elementary window or in an
- * inner window. When a file is chosen from it, the (inner) window
- * is closed and the selected file's path string is exposed both as
- * an smart event and as the new text on the entry.
+ * This function sets a new size for pixmap representation of the given
+ * icon. It allows the icon to be loaded already in the specified size,
+ * reducing the memory usage and load time when loading a big icon with load
+ * size set to a smaller size.
*
- * This widget encapsulates operations on its internal file
- * selector on its own API. There is less control over its file
- * selector than that one would have instatiating one directly.
+ * It's equivalent to the elm_bg_load_size_set() function for bg.
*
- * Smart callbacks one can register to:
- * - @c "changed" - The text within the entry was changed
- * - @c "activated" - The entry has had editing finished and
- * changes are to be "committed"
- * - @c "press" - The entry has been clicked
- * - @c "longpressed" - The entry has been clicked (and held) for a
- * couple seconds
- * - @c "clicked" - The entry has been clicked
- * - @c "clicked,double" - The entry has been double clicked
- * - @c "focused" - The entry has received focus
- * - @c "unfocused" - The entry has lost focus
- * - @c "selection,paste" - A paste action has occurred on the
- * entry
- * - @c "selection,copy" - A copy action has occurred on the entry
- * - @c "selection,cut" - A cut action has occurred on the entry
- * - @c "unpressed" - The file selector entry's button was released
- * after being pressed.
- * - @c "file,chosen" - The user has selected a path via the file
- * selector entry's internal file selector, whose string pointer
- * comes as the @c event_info data (a stringshared string)
+ * @note this is just a hint, the real size of the pixmap may differ
+ * depending on the type of icon being loaded, being bigger than requested.
*
- * Here is an example on its usage:
- * @li @ref fileselector_entry_example
+ * @see elm_icon_prescale_get()
+ * @see elm_bg_load_size_set()
*
- * @see @ref File_Selector_Button for a similar widget.
- * @{
+ * @ingroup Icon
*/
-
+ EAPI void elm_icon_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
/**
- * Add a new file selector entry widget to the given parent
- * Elementary (container) object
+ * Get the prescale size for the icon.
*
- * @param parent The parent object
- * @return a new file selector entry widget handle or @c NULL, on
- * errors
- */
- EAPI Evas_Object *elm_fileselector_entry_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
-
- /**
- * Set the label for a given file selector entry widget's button
+ * @param obj The icon object
+ * @return The prescale size
*
- * @param obj The file selector entry widget
- * @param label The text label to be displayed on @p obj widget's
- * button
+ * @see elm_icon_prescale_set()
*
- * @deprecated use elm_object_text_set() instead.
+ * @ingroup Icon
*/
- EINA_DEPRECATED EAPI void elm_fileselector_entry_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
-
+ EAPI int elm_icon_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the label set for a given file selector entry widget's button
+ * Sets the icon lookup order used by elm_icon_standard_set().
*
- * @param obj The file selector entry widget
- * @return The widget button's label
+ * @param obj The icon object
+ * @param order The icon lookup order (can be one of
+ * ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO
+ * or ELM_ICON_LOOKUP_THEME)
*
- * @deprecated use elm_object_text_set() instead.
+ * @see elm_icon_order_lookup_get()
+ * @see Elm_Icon_Lookup_Order
+ *
+ * @ingroup Icon
*/
- EINA_DEPRECATED EAPI const char *elm_fileselector_entry_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) EINA_ARG_NONNULL(1);
/**
- * Set the icon on a given file selector entry widget's button
+ * Gets the icon lookup order.
*
- * @param obj The file selector entry widget
- * @param icon The icon object for the entry's button
+ * @param obj The icon object
+ * @return The icon lookup order
*
- * Once the icon object is set, a previously set one will be
- * deleted. If you want to keep the latter, use the
- * elm_fileselector_entry_button_icon_unset() function.
+ * @see elm_icon_order_lookup_set()
+ * @see Elm_Icon_Lookup_Order
*
- * @see elm_fileselector_entry_button_icon_get()
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_entry_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
-
+ EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the icon set for a given file selector entry widget's button
+ * Get if the icon supports animation or not.
*
- * @param obj The file selector entry widget
- * @return The icon object currently set on @p obj widget's button
- * or @c NULL, if none is
+ * @param obj The icon object
+ * @return @c EINA_TRUE if the icon supports animation,
+ * @c EINA_FALSE otherwise.
*
- * @see elm_fileselector_entry_button_icon_set()
+ * Return if this elm icon's image can be animated. Currently Evas only
+ * supports gif animation. If the return value is EINA_FALSE, other
+ * elm_icon_animated_XXX APIs won't work.
+ * @ingroup Icon
*/
- EAPI Evas_Object *elm_fileselector_entry_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_icon_animated_available_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Unset the icon used in a given file selector entry widget's
- * button
- *
- * @param obj The file selector entry widget
- * @return The icon object that was being used on @p obj widget's
- * button or @c NULL, on errors
+ * Set animation mode of the icon.
*
- * Unparent and return the icon object which was set for this
- * widget's button.
+ * @param obj The icon object
+ * @param anim @c EINA_TRUE if the object do animation job,
+ * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
*
- * @see elm_fileselector_entry_button_icon_set()
+ * Even though elm icon's file can be animated,
+ * sometimes appication developer want to just first page of image.
+ * In that time, don't call this function, because default value is EINA_FALSE
+ * Only when you want icon support anition,
+ * use this function and set animated to EINA_TURE
+ * @ingroup Icon
*/
- EAPI Evas_Object *elm_fileselector_entry_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_animated_set(Evas_Object *obj, Eina_Bool animated) EINA_ARG_NONNULL(1);
/**
- * Set the title for a given file selector entry widget's window
+ * Get animation mode of the icon.
*
- * @param obj The file selector entry widget
- * @param title The title string
+ * @param obj The icon object
+ * @return The animation mode of the icon object
+ * @see elm_icon_animated_set
+ * @ingroup Icon
+ */
+ EAPI Eina_Bool elm_icon_animated_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set animation play mode of the icon.
*
- * This will change the window's title, when the file selector pops
- * out after a click on the entry's button. Those windows have the
- * default (unlocalized) value of @c "Select a file" as titles.
+ * @param obj The icon object
+ * @param play @c EINA_TRUE the object play animation images,
+ * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
*
- * @note It will only take any effect if the file selector
- * entry widget is @b not under "inwin mode".
+ * If you want to play elm icon's animation, you set play to EINA_TURE.
+ * For example, you make gif player using this set/get API and click event.
*
- * @see elm_fileselector_entry_window_title_get()
+ * 1. Click event occurs
+ * 2. Check play flag using elm_icon_animaged_play_get
+ * 3. If elm icon was playing, set play to EINA_FALSE.
+ * Then animation will be stopped and vice versa
+ * @ingroup Icon
*/
- EAPI void elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_icon_animated_play_set(Evas_Object *obj, Eina_Bool play) EINA_ARG_NONNULL(1);
/**
- * Get the title set for a given file selector entry widget's
- * window
+ * Get animation play mode of the icon.
*
- * @param obj The file selector entry widget
- * @return Title of the file selector entry's window
+ * @param obj The icon object
+ * @return The play mode of the icon object
*
- * @see elm_fileselector_entry_window_title_get() for more details
+ * @see elm_icon_animated_lay_get
+ * @ingroup Icon
*/
- EAPI const char *elm_fileselector_entry_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_icon_animated_play_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the size of a given file selector entry widget's window,
- * holding the file selector itself.
- *
- * @param obj The file selector entry widget
- * @param width The window's width
- * @param height The window's height
- *
- * @note it will only take any effect if the file selector entry
- * widget is @b not under "inwin mode". The default size for the
- * window (when applicable) is 400x400 pixels.
- *
- * @see elm_fileselector_entry_window_size_get()
+ * @}
*/
- EAPI void elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
/**
- * Get the size of a given file selector entry widget's window,
- * holding the file selector itself.
+ * @defgroup Image Image
*
- * @param obj The file selector entry widget
- * @param width Pointer into which to store the width value
- * @param height Pointer into which to store the height value
+ * @image html img/widget/image/preview-00.png
+ * @image latex img/widget/image/preview-00.eps
+
*
- * @note Use @c NULL pointers on the size values you're not
- * interested in: they'll be ignored by the function.
+ * An object that allows one to load an image file to it. It can be used
+ * anywhere like any other elementary widget.
*
- * @see elm_fileselector_entry_window_size_set(), for more details
- */
- EAPI void elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
-
- /**
- * Set the initial file system path and the entry's path string for
- * a given file selector entry widget
+ * This widget provides most of the functionality provided from @ref Bg or @ref
+ * Icon, but with a slightly different API (use the one that fits better your
+ * needs).
*
- * @param obj The file selector entry widget
- * @param path The path string
+ * The features not provided by those two other image widgets are:
+ * @li allowing to get the basic @c Evas_Object with elm_image_object_get();
+ * @li change the object orientation with elm_image_orient_set();
+ * @li and turning the image editable with elm_image_editable_set().
*
- * It must be a <b>directory</b> path, which will have the contents
- * displayed initially in the file selector's view, when invoked
- * from @p obj. The default initial path is the @c "HOME"
- * environment variable's value.
+ * Signals that you can add callbacks for are:
*
- * @see elm_fileselector_entry_path_get()
+ * @li @c "clicked" - This is called when a user has clicked the image
+ *
+ * An example of usage for this API follows:
+ * @li @ref tutorial_image
*/
- EAPI void elm_fileselector_entry_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
/**
- * Get the entry's path string for a given file selector entry
- * widget
- *
- * @param obj The file selector entry widget
- * @return path The path string
- *
- * @see elm_fileselector_entry_path_set() for more details
+ * @addtogroup Image
+ * @{
*/
- EAPI const char *elm_fileselector_entry_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Enable/disable a tree view in the given file selector entry
- * widget's internal file selector
- *
- * @param obj The file selector entry widget
- * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
- * disable
+ * @enum _Elm_Image_Orient
+ * @typedef Elm_Image_Orient
*
- * This has the same effect as elm_fileselector_expandable_set(),
- * but now applied to a file selector entry's internal file
- * selector.
+ * Possible orientation options for elm_image_orient_set().
*
- * @note There's no way to put a file selector entry's internal
- * file selector in "grid mode", as one may do with "pure" file
- * selectors.
+ * @image html elm_image_orient_set.png
+ * @image latex elm_image_orient_set.eps width=\textwidth
*
- * @see elm_fileselector_expandable_get()
+ * @ingroup Image
*/
- EAPI void elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
- /**
- * Get whether tree view is enabled for the given file selector
- * entry widget's internal file selector
- *
- * @param obj The file selector entry widget
- * @return @c EINA_TRUE if @p obj widget's internal file selector
- * is in tree view, @c EINA_FALSE otherwise (and or errors)
- *
- * @see elm_fileselector_expandable_set() for more details
- */
- EAPI Eina_Bool elm_fileselector_entry_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef enum _Elm_Image_Orient
+ {
+ ELM_IMAGE_ORIENT_NONE, /**< no orientation change */
+ ELM_IMAGE_ROTATE_90_CW, /**< rotate 90 degrees clockwise */
+ ELM_IMAGE_ROTATE_180_CW, /**< rotate 180 degrees clockwise */
+ ELM_IMAGE_ROTATE_90_CCW, /**< rotate 90 degrees counter-clockwise (i.e. 270 degrees clockwise) */
+ ELM_IMAGE_FLIP_HORIZONTAL, /**< flip image horizontally */
+ ELM_IMAGE_FLIP_VERTICAL, /**< flip image vertically */
+ ELM_IMAGE_FLIP_TRANSPOSE, /**< flip the image along the y = (side - x) line*/
+ ELM_IMAGE_FLIP_TRANSVERSE /**< flip the image along the y = x line */
+ } Elm_Image_Orient;
/**
- * Set whether a given file selector entry widget's internal file
- * selector is to display folders only or the directory contents,
- * as well.
+ * Add a new image to the parent.
*
- * @param obj The file selector entry widget
- * @param only @c EINA_TRUE to make @p obj widget's internal file
- * selector only display directories, @c EINA_FALSE to make files
- * to be displayed in it too
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*
- * This has the same effect as elm_fileselector_folder_only_set(),
- * but now applied to a file selector entry's internal file
- * selector.
+ * @see elm_image_file_set()
*
- * @see elm_fileselector_folder_only_get()
+ * @ingroup Image
*/
- EAPI void elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
+ EAPI Evas_Object *elm_image_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * Get whether a given file selector entry widget's internal file
- * selector is displaying folders only or the directory contents,
- * as well.
- *
- * @param obj The file selector entry widget
- * @return @c EINA_TRUE if @p obj widget's internal file
- * selector is only displaying directories, @c EINA_FALSE if files
- * are being displayed in it too (and on errors)
+ * Set the file that will be used as image.
*
- * @see elm_fileselector_entry_folder_only_set() for more details
- */
- EAPI Eina_Bool elm_fileselector_entry_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * Enable/disable the file name entry box where the user can type
- * in a name for a file, in a given file selector entry widget's
- * internal file selector.
+ * @param obj The image object
+ * @param file The path to file that will be used as image
+ * @param group The group that the image belongs in edje file (if it's an
+ * edje image)
*
- * @param obj The file selector entry widget
- * @param is_save @c EINA_TRUE to make @p obj widget's internal
- * file selector a "saving dialog", @c EINA_FALSE otherwise
+ * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
*
- * This has the same effect as elm_fileselector_is_save_set(),
- * but now applied to a file selector entry's internal file
- * selector.
+ * @see elm_image_file_get()
*
- * @see elm_fileselector_is_save_get()
+ * @ingroup Image
*/
- EAPI void elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_image_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
/**
- * Get whether the given file selector entry widget's internal
- * file selector is in "saving dialog" mode
- *
- * @param obj The file selector entry widget
- * @return @c EINA_TRUE, if @p obj widget's internal file selector
- * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
- * errors)
+ * Get the file that will be used as image.
*
- * @see elm_fileselector_entry_is_save_set() for more details
- */
- EAPI Eina_Bool elm_fileselector_entry_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * Set whether a given file selector entry widget's internal file
- * selector will raise an Elementary "inner window", instead of a
- * dedicated Elementary window. By default, it won't.
+ * @param obj The image object
+ * @param file The path to file
+ * @param group The group that the image belongs in edje file
*
- * @param obj The file selector entry widget
- * @param value @c EINA_TRUE to make it use an inner window, @c
- * EINA_TRUE to make it use a dedicated window
+ * @see elm_image_file_set()
*
- * @see elm_win_inwin_add() for more information on inner windows
- * @see elm_fileselector_entry_inwin_mode_get()
+ * @ingroup Image
*/
- EAPI void elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_image_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
/**
- * Get whether a given file selector entry widget's internal file
- * selector will raise an Elementary "inner window", instead of a
- * dedicated Elementary window.
+ * Set the smooth effect for an image.
*
- * @param obj The file selector entry widget
- * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
- * if it will use a dedicated window
+ * @param obj The image object
+ * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
+ * otherwise. Default is @c EINA_TRUE.
*
- * @see elm_fileselector_entry_inwin_mode_set() for more details
- */
- EAPI Eina_Bool elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * Set the initial file system path for a given file selector entry
- * widget
+ * Set the scaling algorithm to be used when scaling the image. Smooth
+ * scaling provides a better resulting image, but is slower.
*
- * @param obj The file selector entry widget
- * @param path The path string
+ * The smooth scaling should be disabled when making animations that change
+ * the image size, since it will be faster. Animations that don't require
+ * resizing of the image can keep the smooth scaling enabled (even if the
+ * image is already scaled, since the scaled image will be cached).
*
- * It must be a <b>directory</b> path, which will have the contents
- * displayed initially in the file selector's view, when invoked
- * from @p obj. The default initial path is the @c "HOME"
- * environment variable's value.
+ * @see elm_image_smooth_get()
*
- * @see elm_fileselector_entry_path_get()
+ * @ingroup Image
*/
- EAPI void elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_image_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1);
/**
- * Get the parent directory's path to the latest file selection on
- * a given filer selector entry widget
+ * Get the smooth effect for an image.
*
- * @param obj The file selector object
- * @return The (full) path of the directory of the last selection
- * on @p obj widget, a @b stringshared string
+ * @param obj The image object
+ * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
*
- * @see elm_fileselector_entry_path_set()
- */
- EAPI const char *elm_fileselector_entry_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * @}
+ * @see elm_image_smooth_get()
+ *
+ * @ingroup Image
*/
-
+ EAPI Eina_Bool elm_image_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @defgroup Scroller Scroller
+ * Gets the current size of the image.
*
- * A scroller holds a single object and "scrolls it around". This means that
- * it allows the user to use a scrollbar (or a finger) to drag the viewable
- * region around, allowing to move through a much larger object that is
- * contained in the scroller. The scroiller will always have a small minimum
- * size by default as it won't be limited by the contents of the scroller.
+ * @param obj The image object.
+ * @param w Pointer to store width, or NULL.
+ * @param h Pointer to store height, or NULL.
*
- * Signals that you can add callbacks for are:
- * @li "edge,left" - the left edge of the content has been reached
- * @li "edge,right" - the right edge of the content has been reached
- * @li "edge,top" - the top edge of the content has been reached
- * @li "edge,bottom" - the bottom edge of the content has been reached
- * @li "scroll" - the content has been scrolled (moved)
- * @li "scroll,anim,start" - scrolling animation has started
- * @li "scroll,anim,stop" - scrolling animation has stopped
- * @li "scroll,drag,start" - dragging the contents around has started
- * @li "scroll,drag,stop" - dragging the contents around has stopped
- * @note The "scroll,anim,*" and "scroll,drag,*" signals are only emitted by
- * user intervetion.
+ * This is the real size of the image, not the size of the object.
*
- * @note When Elemementary is in embedded mode the scrollbars will not be
- * dragable, they appear merely as indicators of how much has been scrolled.
- * @note When Elementary is in desktop mode the thumbscroll(a.k.a.
- * fingerscroll) won't work.
+ * On error, neither w or h will be written.
*
- * In @ref tutorial_scroller you'll find an example of how to use most of
- * this API.
- * @{
+ * @ingroup Image
*/
+ EAPI void elm_image_object_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
/**
- * @brief Type that controls when scrollbars should appear.
+ * Disable scaling of this object.
*
- * @see elm_scroller_policy_set()
- */
- typedef enum _Elm_Scroller_Policy
- {
- ELM_SCROLLER_POLICY_AUTO = 0, /**< Show scrollbars as needed */
- ELM_SCROLLER_POLICY_ON, /**< Always show scrollbars */
- ELM_SCROLLER_POLICY_OFF, /**< Never show scrollbars */
- ELM_SCROLLER_POLICY_LAST
- } Elm_Scroller_Policy;
- /**
- * @brief Add a new scroller to the parent
+ * @param obj The image object.
+ * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
+ * otherwise. Default is @c EINA_FALSE.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- */
- EAPI Evas_Object *elm_scroller_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- /**
- * @brief Set the content of the scroller widget (the object to be scrolled around).
+ * This function disables scaling of the elm_image widget through the
+ * function elm_object_scale_set(). However, this does not affect the widget
+ * size/resize in any way. For that effect, take a look at
+ * elm_image_scale_set().
*
- * @param obj The scroller object
- * @param content The new content object
+ * @see elm_image_no_scale_get()
+ * @see elm_image_scale_set()
+ * @see elm_object_scale_set()
*
- * Once the content object is set, a previously set one will be deleted.
- * If you want to keep that old content object, use the
- * elm_scroller_content_unset() function.
+ * @ingroup Image
*/
- EAPI void elm_scroller_content_set(Evas_Object *obj, Evas_Object *child) EINA_ARG_NONNULL(1);
+ EAPI void elm_image_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1);
/**
- * @brief Get the content of the scroller widget
+ * Get whether scaling is disabled on the object.
*
- * @param obj The slider object
- * @return The content that is being used
+ * @param obj The image object
+ * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
*
- * Return the content object which is set for this widget
+ * @see elm_image_no_scale_set()
*
- * @see elm_scroller_content_set()
+ * @ingroup Image
*/
- EAPI Evas_Object *elm_scroller_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_image_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Unset the content of the scroller widget
+ * Set if the object is (up/down) resizable.
*
- * @param obj The slider object
- * @return The content that was being used
+ * @param obj The image object
+ * @param scale_up A bool to set if the object is resizable up. Default is
+ * @c EINA_TRUE.
+ * @param scale_down A bool to set if the object is resizable down. Default
+ * is @c EINA_TRUE.
*
- * Unparent and return the content object which was set for this widget
+ * This function limits the image resize ability. If @p scale_up is set to
+ * @c EINA_FALSE, the object can't have its height or width resized to a value
+ * higher than the original image size. Same is valid for @p scale_down.
*
- * @see elm_scroller_content_set()
+ * @see elm_image_scale_get()
+ *
+ * @ingroup Image
*/
- EAPI Evas_Object *elm_scroller_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_image_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1);
/**
- * @brief Set custom theme elements for the scroller
+ * Get if the object is (up/down) resizable.
*
- * @param obj The scroller object
- * @param widget The widget name to use (default is "scroller")
- * @param base The base name to use (default is "base")
- */
- EAPI void elm_scroller_custom_widget_base_theme_set(Evas_Object *obj, const char *widget, const char *base) EINA_ARG_NONNULL(1, 2, 3);
- /**
- * @brief Make the scroller minimum size limited to the minimum size of the content
+ * @param obj The image object
+ * @param scale_up A bool to set if the object is resizable up
+ * @param scale_down A bool to set if the object is resizable down
*
- * @param obj The scroller object
- * @param w Enable limiting minimum size horizontally
- * @param h Enable limiting minimum size vertically
+ * @see elm_image_scale_set()
*
- * By default the scroller will be as small as its design allows,
- * irrespective of its content. This will make the scroller minimum size the
- * right size horizontally and/or vertically to perfectly fit its content in
- * that direction.
+ * @ingroup Image
*/
- EAPI void elm_scroller_content_min_limit(Evas_Object *obj, Eina_Bool w, Eina_Bool h) EINA_ARG_NONNULL(1);
+ EAPI void elm_image_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1);
/**
- * @brief Show a specific virtual region within the scroller content object
+ * Set if the image fill the entire object area when keeping the aspect ratio.
*
- * @param obj The scroller object
- * @param x X coordinate of the region
- * @param y Y coordinate of the region
- * @param w Width of the region
- * @param h Height of the region
+ * @param obj The image object
+ * @param fill_outside @c EINA_TRUE if the object is filled outside,
+ * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
*
- * This will ensure all (or part if it does not fit) of the designated
- * region in the virtual content object (0, 0 starting at the top-left of the
- * virtual content object) is shown within the scroller.
- */
- EAPI void elm_scroller_region_show(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
- /**
- * @brief Set the scrollbar visibility policy
+ * When the image should keep its aspect ratio even if resized to another
+ * aspect ratio, there are two possibilities to resize it: keep the entire
+ * image inside the limits of height and width of the object (@p fill_outside
+ * is @c EINA_FALSE) or let the extra width or height go outside of the object,
+ * and the image will fill the entire object (@p fill_outside is @c EINA_TRUE).
*
- * @param obj The scroller object
- * @param policy_h Horizontal scrollbar policy
- * @param policy_v Vertical scrollbar policy
+ * @note This option will have no effect if
+ * elm_image_aspect_ratio_retained_set() is set to @c EINA_FALSE.
*
- * This sets the scrollbar visibility policy for the given scroller.
- * ELM_SCROLLER_POLICY_AUTO means the scrollber is made visible if it is
- * needed, and otherwise kept hidden. ELM_SCROLLER_POLICY_ON turns it on all
- * the time, and ELM_SCROLLER_POLICY_OFF always keeps it off. This applies
- * respectively for the horizontal and vertical scrollbars.
+ * @see elm_image_fill_outside_get()
+ * @see elm_image_aspect_ratio_retained_set()
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v) EINA_ARG_NONNULL(1);
+ EAPI void elm_image_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1);
/**
- * @brief Gets scrollbar visibility policy
+ * Get if the object is filled outside
*
- * @param obj The scroller object
- * @param policy_h Horizontal scrollbar policy
- * @param policy_v Vertical scrollbar policy
+ * @param obj The image object
+ * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
*
- * @see elm_scroller_policy_set()
+ * @see elm_image_fill_outside_set()
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_image_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Get the currently visible content region
+ * Set the prescale size for the image
*
- * @param obj The scroller object
- * @param x X coordinate of the region
- * @param y Y coordinate of the region
- * @param w Width of the region
- * @param h Height of the region
+ * @param obj The image object
+ * @param size The prescale size. This value is used for both width and
+ * height.
*
- * This gets the current region in the content object that is visible through
- * the scroller. The region co-ordinates are returned in the @p x, @p y, @p
- * w, @p h values pointed to.
+ * This function sets a new size for pixmap representation of the given
+ * image. It allows the image to be loaded already in the specified size,
+ * reducing the memory usage and load time when loading a big image with load
+ * size set to a smaller size.
*
- * @note All coordinates are relative to the content.
+ * It's equivalent to the elm_bg_load_size_set() function for bg.
*
- * @see elm_scroller_region_show()
+ * @note this is just a hint, the real size of the pixmap may differ
+ * depending on the type of image being loaded, being bigger than requested.
+ *
+ * @see elm_image_prescale_get()
+ * @see elm_bg_load_size_set()
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_region_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+ EAPI void elm_image_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
/**
- * @brief Get the size of the content object
+ * Get the prescale size for the image
*
- * @param obj The scroller object
- * @param w Width return
- * @param h Height return
+ * @param obj The image object
+ * @return The prescale size
*
- * This gets the size of the content object of the scroller.
+ * @see elm_image_prescale_set()
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_child_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+ EAPI int elm_image_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Set bouncing behavior
+ * Set the image orientation.
*
- * @param obj The scroller object
- * @param h_bounce Will the scroller bounce horizontally or not
- * @param v_bounce Will the scroller bounce vertically or not
+ * @param obj The image object
+ * @param orient The image orientation
+ * (one of #ELM_IMAGE_ORIENT_NONE, #ELM_IMAGE_ROTATE_90_CW,
+ * #ELM_IMAGE_ROTATE_180_CW, #ELM_IMAGE_ROTATE_90_CCW,
+ * #ELM_IMAGE_FLIP_HORIZONTAL, #ELM_IMAGE_FLIP_VERTICAL,
+ * #ELM_IMAGE_FLIP_TRANSPOSE, #ELM_IMAGE_FLIP_TRANSVERSE).
+ * Default is #ELM_IMAGE_ORIENT_NONE.
*
- * When scrolling, the scroller may "bounce" when reaching an edge of the
- * content object. This is a visual way to indicate the end has been reached.
- * This is enabled by default for both axis. This will set if it is enabled
- * for that axis with the boolean parameters for each axis.
+ * This function allows to rotate or flip the given image.
+ *
+ * @see elm_image_orient_get()
+ * @see @ref Elm_Image_Orient
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
+ EAPI void elm_image_orient_set(Evas_Object *obj, Elm_Image_Orient orient) EINA_ARG_NONNULL(1);
/**
- * @brief Get the bounce mode
+ * Get the image orientation.
*
- * @param obj The Scroller object
- * @param h_bounce Allow bounce horizontally
- * @param v_bounce Allow bounce vertically
+ * @param obj The image object
+ * @return The image orientation
+ * (one of #ELM_IMAGE_ORIENT_NONE, #ELM_IMAGE_ROTATE_90_CW,
+ * #ELM_IMAGE_ROTATE_180_CW, #ELM_IMAGE_ROTATE_90_CCW,
+ * #ELM_IMAGE_FLIP_HORIZONTAL, #ELM_IMAGE_FLIP_VERTICAL,
+ * #ELM_IMAGE_FLIP_TRANSPOSE, #ELM_IMAGE_FLIP_TRANSVERSE)
*
- * @see elm_scroller_bounce_set()
+ * @see elm_image_orient_set()
+ * @see @ref Elm_Image_Orient
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
+ EAPI Elm_Image_Orient elm_image_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Set scroll page size relative to viewport size.
+ * Make the image 'editable'.
*
- * @param obj The scroller object
- * @param h_pagerel The horizontal page relative size
- * @param v_pagerel The vertical page relative size
+ * @param obj Image object.
+ * @param set Turn on or off editability. Default is @c EINA_FALSE.
*
- * The scroller is capable of limiting scrolling by the user to "pages". That
- * is to jump by and only show a "whole page" at a time as if the continuous
- * area of the scroller content is split into page sized pieces. This sets
- * the size of a page relative to the viewport of the scroller. 1.0 is "1
- * viewport" is size (horizontally or vertically). 0.0 turns it off in that
- * axis. This is mutually exclusive with page size
- * (see elm_scroller_page_size_set() for more information). Likewise 0.5
- * is "half a viewport". Sane usable valus are normally between 0.0 and 1.0
- * including 1.0. If you only want 1 axis to be page "limited", use 0.0 for
- * the other axis.
+ * This means the image is a valid drag target for drag and drop, and can be
+ * cut or pasted too.
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel) EINA_ARG_NONNULL(1);
+ EAPI void elm_image_editable_set(Evas_Object *obj, Eina_Bool set) EINA_ARG_NONNULL(1);
/**
- * @brief Set scroll page size.
+ * Make the image 'editable'.
*
- * @param obj The scroller object
- * @param h_pagesize The horizontal page size
- * @param v_pagesize The vertical page size
+ * @param obj Image object.
+ * @return Editability.
*
- * This sets the page size to an absolute fixed value, with 0 turning it off
- * for that axis.
+ * This means the image is a valid drag target for drag and drop, and can be
+ * cut or pasted too.
*
- * @see elm_scroller_page_relative_set()
+ * @ingroup Image
*/
- EAPI void elm_scroller_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_image_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Show a specific virtual region within the scroller content object.
+ * Get the basic Evas_Image object from this object (widget).
*
- * @param obj The scroller object
- * @param x X coordinate of the region
- * @param y Y coordinate of the region
- * @param w Width of the region
- * @param h Height of the region
+ * @param obj The image object to get the inlined image from
+ * @return The inlined image object, or NULL if none exists
*
- * This will ensure all (or part if it does not fit) of the designated
- * region in the virtual content object (0, 0 starting at the top-left of the
- * virtual content object) is shown within the scroller. Unlike
- * elm_scroller_region_show(), this allow the scroller to "smoothly slide"
- * to this location (if configuration in general calls for transitions). It
- * may not jump immediately to the new location and make take a while and
- * show other content along the way.
+ * This function allows one to get the underlying @c Evas_Object of type
+ * Image from this elementary widget. It can be useful to do things like get
+ * the pixel data, save the image to a file, etc.
*
- * @see elm_scroller_region_show()
+ * @note Be careful to not manipulate it, as it is under control of
+ * elementary.
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_region_bring_in(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_image_object_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Set event propagation on a scroller
+ * Set whether the original aspect ratio of the image should be kept on resize.
*
- * @param obj The scroller object
- * @param propagation If propagation is enabled or not
+ * @param obj The image object.
+ * @param retained @c EINA_TRUE if the image should retain the aspect,
+ * @c EINA_FALSE otherwise.
*
- * This enables or disabled event propagation from the scroller content to
- * the scroller and its parent. By default event propagation is disabled.
+ * The original aspect ratio (width / height) of the image is usually
+ * distorted to match the object's size. Enabling this option will retain
+ * this original aspect, and the way that the image is fit into the object's
+ * area depends on the option set by elm_image_fill_outside_set().
+ *
+ * @see elm_image_aspect_ratio_retained_get()
+ * @see elm_image_fill_outside_set()
+ *
+ * @ingroup Image
*/
- EAPI void elm_scroller_propagate_events_set(Evas_Object *obj, Eina_Bool propagation);
+ EAPI void elm_image_aspect_ratio_retained_set(Evas_Object *obj, Eina_Bool retained) EINA_ARG_NONNULL(1);
/**
- * @brief Get event propagation for a scroller
- *
- * @param obj The scroller object
- * @return The propagation state
+ * Get if the object retains the original aspect ratio.
*
- * This gets the event propagation for a scroller.
+ * @param obj The image object.
+ * @return @c EINA_TRUE if the object keeps the original aspect, @c EINA_FALSE
+ * otherwise.
*
- * @see elm_scroller_propagate_events_set()
+ * @ingroup Image
*/
- EAPI Eina_Bool elm_scroller_propagate_events_get(const Evas_Object *obj);
+ EAPI Eina_Bool elm_image_aspect_ratio_retained_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
* @}
*/
+ /* glview */
+ typedef void (*Elm_GLView_Func_Cb)(Evas_Object *obj);
+
+ typedef enum _Elm_GLView_Mode
+ {
+ ELM_GLVIEW_ALPHA = 1,
+ ELM_GLVIEW_DEPTH = 2,
+ ELM_GLVIEW_STENCIL = 4
+ } Elm_GLView_Mode;
+
/**
- * @defgroup Label Label
- *
- * @image html img/widget/label/preview-00.png
- * @image latex img/widget/label/preview-00.eps
- *
- * @brief Widget to display text, with simple html-like markup.
- *
- * The Label widget @b doesn't allow text to overflow its boundaries, if the
- * text doesn't fit the geometry of the label it will be ellipsized or be
- * cut. Elementary provides several themes for this widget:
- * @li default - No animation
- * @li marker - Centers the text in the label and make it bold by default
- * @li slide_long - The entire text appears from the right of the screen and
- * slides until it disappears in the left of the screen(reappering on the
- * right again).
- * @li slide_short - The text appears in the left of the label and slides to
- * the right to show the overflow. When all of the text has been shown the
- * position is reset.
- * @li slide_bounce - The text appears in the left of the label and slides to
- * the right to show the overflow. When all of the text has been shown the
- * animation reverses, moving the text to the left.
- *
- * Custom themes can of course invent new markup tags and style them any way
- * they like.
- *
- * See @ref tutorial_label for a demonstration of how to use a label widget.
- * @{
- */
- /**
- * @brief Add a new label to the parent
+ * Defines a policy for the glview resizing.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * @note Default is ELM_GLVIEW_RESIZE_POLICY_RECREATE
*/
- EAPI Evas_Object *elm_label_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ typedef enum _Elm_GLView_Resize_Policy
+ {
+ ELM_GLVIEW_RESIZE_POLICY_RECREATE = 1, /**< Resize the internal surface along with the image */
+ ELM_GLVIEW_RESIZE_POLICY_SCALE = 2 /**< Only reize the internal image and not the surface */
+ } Elm_GLView_Resize_Policy;
+
+ typedef enum _Elm_GLView_Render_Policy
+ {
+ ELM_GLVIEW_RENDER_POLICY_ON_DEMAND = 1, /**< Render only when there is a need for redrawing */
+ ELM_GLVIEW_RENDER_POLICY_ALWAYS = 2 /**< Render always even when it is not visible */
+ } Elm_GLView_Render_Policy;
+
/**
- * @brief Set the label on the label object
+ * @defgroup GLView
*
- * @param obj The label object
- * @param label The label will be used on the label object
- * @deprecated See elm_object_text_set()
- */
- EINA_DEPRECATED EAPI void elm_label_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1); /* deprecated, use elm_object_text_set instead */
- /**
- * @brief Get the label used on the label object
+ * A simple GLView widget that allows GL rendering.
*
- * @param obj The label object
- * @return The string inside the label
- * @deprecated See elm_object_text_get()
+ * Signals that you can add callbacks for are:
+ *
+ * @{
*/
- EINA_DEPRECATED EAPI const char *elm_label_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); /* deprecated, use elm_object_text_get instead */
+
/**
- * @brief Set the wrapping behavior of the label
+ * Add a new glview to the parent
*
- * @param obj The label object
- * @param wrap To wrap text or not
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*
- * By default no wrapping is done. Possible values for @p wrap are:
- * @li ELM_WRAP_NONE - No wrapping
- * @li ELM_WRAP_CHAR - wrap between characters
- * @li ELM_WRAP_WORD - wrap between words
- * @li ELM_WRAP_MIXED - Word wrap, and if that fails, char wrap
+ * @ingroup GLView
*/
- EAPI void elm_label_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_glview_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
/**
- * @brief Get the wrapping behavior of the label
+ * Sets the size of the glview
*
- * @param obj The label object
- * @return Wrap type
+ * @param obj The glview object
+ * @param width width of the glview object
+ * @param height height of the glview object
*
- * @see elm_label_line_wrap_set()
+ * @ingroup GLView
*/
- EAPI Elm_Wrap_Type elm_label_line_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_glview_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
+
/**
- * @brief Set wrap width of the label
+ * Gets the size of the glview.
*
- * @param obj The label object
- * @param w The wrap width in pixels at a minimum where words need to wrap
+ * @param obj The glview object
+ * @param width width of the glview object
+ * @param height height of the glview object
*
- * This function sets the maximum width size hint of the label.
+ * Note that this function returns the actual image size of the
+ * glview. This means that when the scale policy is set to
+ * ELM_GLVIEW_RESIZE_POLICY_SCALE, it'll return the non-scaled
+ * size.
*
- * @warning This is only relevant if the label is inside a container.
+ * @ingroup GLView
*/
- EAPI void elm_label_wrap_width_set(Evas_Object *obj, Evas_Coord w) EINA_ARG_NONNULL(1);
+ EAPI void elm_glview_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
+
/**
- * @brief Get wrap width of the label
+ * Gets the gl api struct for gl rendering
*
- * @param obj The label object
- * @return The wrap width in pixels at a minimum where words need to wrap
+ * @param obj The glview object
+ * @return The api object or NULL if it cannot be created
*
- * @see elm_label_wrap_width_set()
+ * @ingroup GLView
*/
- EAPI Evas_Coord elm_label_wrap_width_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_GL_API *elm_glview_gl_api_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * @brief Set wrap height of the label
- *
- * @param obj The label object
- * @param h The wrap height in pixels at a minimum where words need to wrap
- *
- * This function sets the maximum height size hint of the label.
+ * Set the mode of the GLView. Supports Three simple modes.
*
- * @warning This is only relevant if the label is inside a container.
- */
- EAPI void elm_label_wrap_height_set(Evas_Object *obj, Evas_Coord h) EINA_ARG_NONNULL(1);
- /**
- * @brief get wrap width of the label
+ * @param obj The glview object
+ * @param mode The mode Options OR'ed enabling Alpha, Depth, Stencil.
+ * @return True if set properly.
*
- * @param obj The label object
- * @return The wrap height in pixels at a minimum where words need to wrap
+ * @ingroup GLView
*/
- EAPI Evas_Coord elm_label_wrap_height_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_glview_mode_set(Evas_Object *obj, Elm_GLView_Mode mode) EINA_ARG_NONNULL(1);
+
/**
- * @brief Set the font size on the label object.
- *
- * @param obj The label object
- * @param size font size
+ * Set the resize policy for the glview object.
*
- * @warning NEVER use this. It is for hyper-special cases only. use styles
- * instead. e.g. "big", "medium", "small" - or better name them by use:
- * "title", "footnote", "quote" etc.
- */
- EAPI void elm_label_fontsize_set(Evas_Object *obj, int fontsize) EINA_ARG_NONNULL(1);
- /**
- * @brief Set the text color on the label object
+ * @param obj The glview object.
+ * @param policy The scaling policy.
*
- * @param obj The label object
- * @param r Red property background color of The label object
- * @param g Green property background color of The label object
- * @param b Blue property background color of The label object
- * @param a Alpha property background color of The label object
+ * By default, the resize policy is set to
+ * ELM_GLVIEW_RESIZE_POLICY_RECREATE. When resize is called it
+ * destroys the previous surface and recreates the newly specified
+ * size. If the policy is set to ELM_GLVIEW_RESIZE_POLICY_SCALE,
+ * however, glview only scales the image object and not the underlying
+ * GL Surface.
*
- * @warning NEVER use this. It is for hyper-special cases only. use styles
- * instead. e.g. "big", "medium", "small" - or better name them by use:
- * "title", "footnote", "quote" etc.
+ * @ingroup GLView
*/
- EAPI void elm_label_text_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_glview_resize_policy_set(Evas_Object *obj, Elm_GLView_Resize_Policy policy) EINA_ARG_NONNULL(1);
+
/**
- * @brief Set the text align on the label object
- *
- * @param obj The label object
- * @param align align mode ("left", "center", "right")
+ * Set the render policy for the glview object.
*
- * @warning NEVER use this. It is for hyper-special cases only. use styles
- * instead. e.g. "big", "medium", "small" - or better name them by use:
- * "title", "footnote", "quote" etc.
- */
- EAPI void elm_label_text_align_set(Evas_Object *obj, const char *alignmode) EINA_ARG_NONNULL(1);
- /**
- * @brief Set background color of the label
+ * @param obj The glview object.
+ * @param policy The render policy.
*
- * @param obj The label object
- * @param r Red property background color of The label object
- * @param g Green property background color of The label object
- * @param b Blue property background color of The label object
- * @param a Alpha property background alpha of The label object
+ * By default, the render policy is set to
+ * ELM_GLVIEW_RENDER_POLICY_ON_DEMAND. This policy is set such
+ * that during the render loop, glview is only redrawn if it needs
+ * to be redrawn. (i.e. When it is visible) If the policy is set to
+ * ELM_GLVIEWW_RENDER_POLICY_ALWAYS, it redraws regardless of
+ * whether it is visible/need redrawing or not.
*
- * @warning NEVER use this. It is for hyper-special cases only. use styles
- * instead. e.g. "big", "medium", "small" - or better name them by use:
- * "title", "footnote", "quote" etc.
+ * @ingroup GLView
*/
- EAPI void elm_label_background_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_glview_render_policy_set(Evas_Object *obj, Elm_GLView_Render_Policy policy) EINA_ARG_NONNULL(1);
+
/**
- * @brief Set the ellipsis behavior of the label
+ * Set the init function that runs once in the main loop.
*
- * @param obj The label object
- * @param ellipsis To ellipsis text or not
+ * @param obj The glview object.
+ * @param func The init function to be registered.
*
- * If set to true and the text doesn't fit in the label an ellipsis("...")
- * will be shown at the end of the widget.
+ * The registered init function gets called once during the render loop.
*
- * @warning This doesn't work with slide(elm_label_slide_set()) or if the
- * choosen wrap method was ELM_WRAP_WORD.
+ * @ingroup GLView
*/
- EAPI void elm_label_ellipsis_set(Evas_Object *obj, Eina_Bool ellipsis) EINA_ARG_NONNULL(1);
+ EAPI void elm_glview_init_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
+
/**
- * @brief Set the text slide of the label
+ * Set the render function that runs in the main loop.
*
- * @param obj The label object
- * @param slide To start slide or stop
+ * @param obj The glview object.
+ * @param func The delete function to be registered.
*
- * If set to true the text of the label will slide throught the length of
- * label.
+ * The registered del function gets called when GLView object is deleted.
*
- * @warning This only work with the themes "slide_short", "slide_long" and
- * "slide_bounce".
+ * @ingroup GLView
*/
- EAPI void elm_label_slide_set(Evas_Object *obj, Eina_Bool slide) EINA_ARG_NONNULL(1);
+ EAPI void elm_glview_del_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
+
/**
- * @brief Get the text slide mode of the label
+ * Set the resize function that gets called when resize happens.
*
- * @param obj The label object
- * @return slide slide mode value
+ * @param obj The glview object.
+ * @param func The resize function to be registered.
*
- * @see elm_label_slide_set()
+ * @ingroup GLView
*/
- EAPI Eina_Bool elm_label_slide_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_glview_resize_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
+
/**
- * @brief Set the slide duration(speed) of the label
+ * Set the render function that runs in the main loop.
*
- * @param obj The label object
- * @return The duration in seconds in moving text from slide begin position
- * to slide end position
+ * @param obj The glview object.
+ * @param func The render function to be registered.
+ *
+ * @ingroup GLView
*/
- EAPI void elm_label_slide_duration_set(Evas_Object *obj, double duration) EINA_ARG_NONNULL(1);
+ EAPI void elm_glview_render_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func) EINA_ARG_NONNULL(1);
+
/**
- * @brief Get the slide duration(speed) of the label
+ * Notifies that there has been changes in the GLView.
*
- * @param obj The label object
- * @return The duration time in moving text from slide begin position to slide end position
+ * @param obj The glview object.
*
- * @see elm_label_slide_duration_set()
+ * @ingroup GLView
*/
- EAPI double elm_label_slide_duration_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_glview_changed_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
* @}
*/
+ /* box */
/**
- * @defgroup Toggle Toggle
- *
- * @image html img/widget/toggle/preview-00.png
- * @image latex img/widget/toggle/preview-00.eps
+ * @defgroup Box Box
*
- * @brief A toggle is a slider which can be used to toggle between
- * two values. It has two states: on and off.
+ * @image html img/widget/box/preview-00.png
+ * @image latex img/widget/box/preview-00.eps width=\textwidth
*
- * Signals that you can add callbacks for are:
- * @li "changed" - Whenever the toggle value has been changed. Is not called
- * until the toggle is released by the cursor (assuming it
- * has been triggered by the cursor in the first place).
+ * @image html img/box.png
+ * @image latex img/box.eps width=\textwidth
*
- * @ref tutorial_toggle show how to use a toggle.
- * @{
- */
- /**
- * @brief Add a toggle to @p parent.
+ * A box arranges objects in a linear fashion, governed by a layout function
+ * that defines the details of this arrangement.
*
- * @param parent The parent object
+ * By default, the box will use an internal function to set the layout to
+ * a single row, either vertical or horizontal. This layout is affected
+ * by a number of parameters, such as the homogeneous flag set by
+ * elm_box_homogeneous_set(), the values given by elm_box_padding_set() and
+ * elm_box_align_set() and the hints set to each object in the box.
*
- * @return The toggle object
- */
- EAPI Evas_Object *elm_toggle_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- /**
- * @brief Sets the label to be displayed with the toggle.
+ * For this default layout, it's possible to change the orientation with
+ * elm_box_horizontal_set(). The box will start in the vertical orientation,
+ * placing its elements ordered from top to bottom. When horizontal is set,
+ * the order will go from left to right. If the box is set to be
+ * homogeneous, every object in it will be assigned the same space, that
+ * of the largest object. Padding can be used to set some spacing between
+ * the cell given to each object. The alignment of the box, set with
+ * elm_box_align_set(), determines how the bounding box of all the elements
+ * will be placed within the space given to the box widget itself.
*
- * @param obj The toggle object
- * @param label The label to be displayed
+ * The size hints of each object also affect how they are placed and sized
+ * within the box. evas_object_size_hint_min_set() will give the minimum
+ * size the object can have, and the box will use it as the basis for all
+ * latter calculations. Elementary widgets set their own minimum size as
+ * needed, so there's rarely any need to use it manually.
*
- * @deprecated use elm_object_text_set() instead.
- */
- EINA_DEPRECATED EAPI void elm_toggle_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
- /**
- * @brief Gets the label of the toggle
+ * evas_object_size_hint_weight_set(), when not in homogeneous mode, is
+ * used to tell whether the object will be allocated the minimum size it
+ * needs or if the space given to it should be expanded. It's important
+ * to realize that expanding the size given to the object is not the same
+ * thing as resizing the object. It could very well end being a small
+ * widget floating in a much larger empty space. If not set, the weight
+ * for objects will normally be 0.0 for both axis, meaning the widget will
+ * not be expanded. To take as much space possible, set the weight to
+ * EVAS_HINT_EXPAND (defined to 1.0) for the desired axis to expand.
*
- * @param obj toggle object
- * @return The label of the toggle
+ * Besides how much space each object is allocated, it's possible to control
+ * how the widget will be placed within that space using
+ * evas_object_size_hint_align_set(). By default, this value will be 0.5
+ * for both axis, meaning the object will be centered, but any value from
+ * 0.0 (left or top, for the @c x and @c y axis, respectively) to 1.0
+ * (right or bottom) can be used. The special value EVAS_HINT_FILL, which
+ * is -1.0, means the object will be resized to fill the entire space it
+ * was allocated.
*
- * @deprecated use elm_object_text_get() instead.
+ * In addition, customized functions to define the layout can be set, which
+ * allow the application developer to organize the objects within the box
+ * in any number of ways.
+ *
+ * The special elm_box_layout_transition() function can be used
+ * to switch from one layout to another, animating the motion of the
+ * children of the box.
+ *
+ * @note Objects should not be added to box objects using _add() calls.
+ *
+ * Some examples on how to use boxes follow:
+ * @li @ref box_example_01
+ * @li @ref box_example_02
+ *
+ * @{
*/
- EINA_DEPRECATED EAPI const char *elm_toggle_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Set the icon used for the toggle
+ * @typedef Elm_Box_Transition
*
- * @param obj The toggle object
- * @param icon The icon object for the button
+ * Opaque handler containing the parameters to perform an animated
+ * transition of the layout the box uses.
*
- * Once the icon object is set, a previously set one will be deleted
- * If you want to keep that old content object, use the
- * elm_toggle_icon_unset() function.
+ * @see elm_box_transition_new()
+ * @see elm_box_layout_set()
+ * @see elm_box_layout_transition()
*/
- EAPI void elm_toggle_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Box_Transition Elm_Box_Transition;
+
/**
- * @brief Get the icon used for the toggle
- *
- * @param obj The toggle object
- * @return The icon object that is being used
+ * Add a new box to the parent
*
- * Return the icon object which is set for this widget.
+ * By default, the box will be in vertical mode and non-homogeneous.
*
- * @see elm_toggle_icon_set()
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*/
- EAPI Evas_Object *elm_toggle_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_box_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * @brief Unset the icon used for the toggle
+ * Set the horizontal orientation
*
- * @param obj The toggle object
- * @return The icon object that was being used
+ * By default, box object arranges their contents vertically from top to
+ * bottom.
+ * By calling this function with @p horizontal as EINA_TRUE, the box will
+ * become horizontal, arranging contents from left to right.
*
- * Unparent and return the icon object which was set for this widget.
+ * @note This flag is ignored if a custom layout function is set.
*
- * @see elm_toggle_icon_set()
+ * @param obj The box object
+ * @param horizontal The horizontal flag (EINA_TRUE = horizontal,
+ * EINA_FALSE = vertical)
*/
- EAPI Evas_Object *elm_toggle_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the labels to be associated with the on and off states of the toggle.
+ * Get the horizontal orientation
*
- * @param obj The toggle object
- * @param onlabel The label displayed when the toggle is in the "on" state
- * @param offlabel The label displayed when the toggle is in the "off" state
+ * @param obj The box object
+ * @return EINA_TRUE if the box is set to horizontal mode, EINA_FALSE otherwise
*/
- EAPI void elm_toggle_states_labels_set(Evas_Object *obj, const char *onlabel, const char *offlabel) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_box_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Gets the labels associated with the on and off states of the toggle.
+ * Set the box to arrange its children homogeneously
*
- * @param obj The toggle object
- * @param onlabel A char** to place the onlabel of @p obj into
- * @param offlabel A char** to place the offlabel of @p obj into
- */
- EAPI void elm_toggle_states_labels_get(const Evas_Object *obj, const char **onlabel, const char **offlabel) EINA_ARG_NONNULL(1);
- /**
- * @brief Sets the state of the toggle to @p state.
+ * If enabled, homogeneous layout makes all items the same size, according
+ * to the size of the largest of its children.
*
- * @param obj The toggle object
- * @param state The state of @p obj
- */
- EAPI void elm_toggle_state_set(Evas_Object *obj, Eina_Bool state) EINA_ARG_NONNULL(1);
- /**
- * @brief Gets the state of the toggle to @p state.
+ * @note This flag is ignored if a custom layout function is set.
*
- * @param obj The toggle object
- * @return The state of @p obj
+ * @param obj The box object
+ * @param homogeneous The homogeneous flag
*/
- EAPI Eina_Bool elm_toggle_state_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the state pointer of the toggle to @p statep.
+ * Get whether the box is using homogeneous mode or not
*
- * @param obj The toggle object
- * @param statep The state pointer of @p obj
- */
- EAPI void elm_toggle_state_pointer_set(Evas_Object *obj, Eina_Bool *statep) EINA_ARG_NONNULL(1);
- /**
- * @}
+ * @param obj The box object
+ * @return EINA_TRUE if it's homogeneous, EINA_FALSE otherwise
*/
-
+ EAPI Eina_Bool elm_box_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI void elm_box_homogenous_set(Evas_Object *obj, Eina_Bool homogenous) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI Eina_Bool elm_box_homogenous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @defgroup Frame Frame
+ * Add an object to the beginning of the pack list
*
- * @image html img/widget/frame/preview-00.png
- * @image latex img/widget/frame/preview-00.eps
+ * Pack @p subobj into the box @p obj, placing it first in the list of
+ * children objects. The actual position the object will get on screen
+ * depends on the layout used. If no custom layout is set, it will be at
+ * the top or left, depending if the box is vertical or horizontal,
+ * respectively.
*
- * @brief Frame is a widget that holds some content and has a title.
+ * @param obj The box object
+ * @param subobj The object to add to the box
*
- * The default look is a frame with a title, but Frame supports multple
- * styles:
- * @li default
- * @li pad_small
- * @li pad_medium
- * @li pad_large
- * @li pad_huge
- * @li outdent_top
- * @li outdent_bottom
+ * @see elm_box_pack_end()
+ * @see elm_box_pack_before()
+ * @see elm_box_pack_after()
+ * @see elm_box_unpack()
+ * @see elm_box_unpack_all()
+ * @see elm_box_clear()
+ */
+ EAPI void elm_box_pack_start(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
+ /**
+ * Add an object at the end of the pack list
*
- * Of all this styles only default shows the title. Frame emits no signals.
+ * Pack @p subobj into the box @p obj, placing it last in the list of
+ * children objects. The actual position the object will get on screen
+ * depends on the layout used. If no custom layout is set, it will be at
+ * the bottom or right, depending if the box is vertical or horizontal,
+ * respectively.
*
- * For a detailed example see the @ref tutorial_frame.
+ * @param obj The box object
+ * @param subobj The object to add to the box
*
- * @{
+ * @see elm_box_pack_start()
+ * @see elm_box_pack_before()
+ * @see elm_box_pack_after()
+ * @see elm_box_unpack()
+ * @see elm_box_unpack_all()
+ * @see elm_box_clear()
*/
+ EAPI void elm_box_pack_end(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
/**
- * @brief Add a new frame to the parent
+ * Adds an object to the box before the indicated object
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- */
- EAPI Evas_Object *elm_frame_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- /**
- * @brief Set the frame label
+ * This will add the @p subobj to the box indicated before the object
+ * indicated with @p before. If @p before is not already in the box, results
+ * are undefined. Before means either to the left of the indicated object or
+ * above it depending on orientation.
*
- * @param obj The frame object
- * @param label The label of this frame object
+ * @param obj The box object
+ * @param subobj The object to add to the box
+ * @param before The object before which to add it
*
- * @deprecated use elm_object_text_set() instead.
+ * @see elm_box_pack_start()
+ * @see elm_box_pack_end()
+ * @see elm_box_pack_after()
+ * @see elm_box_unpack()
+ * @see elm_box_unpack_all()
+ * @see elm_box_clear()
*/
- EINA_DEPRECATED EAPI void elm_frame_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_pack_before(Evas_Object *obj, Evas_Object *subobj, Evas_Object *before) EINA_ARG_NONNULL(1);
/**
- * @brief Get the frame label
+ * Adds an object to the box after the indicated object
*
- * @param obj The frame object
+ * This will add the @p subobj to the box indicated after the object
+ * indicated with @p after. If @p after is not already in the box, results
+ * are undefined. After means either to the right of the indicated object or
+ * below it depending on orientation.
*
- * @return The label of this frame objet or NULL if unable to get frame
+ * @param obj The box object
+ * @param subobj The object to add to the box
+ * @param after The object after which to add it
*
- * @deprecated use elm_object_text_get() instead.
+ * @see elm_box_pack_start()
+ * @see elm_box_pack_end()
+ * @see elm_box_pack_before()
+ * @see elm_box_unpack()
+ * @see elm_box_unpack_all()
+ * @see elm_box_clear()
*/
- EINA_DEPRECATED EAPI const char *elm_frame_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_pack_after(Evas_Object *obj, Evas_Object *subobj, Evas_Object *after) EINA_ARG_NONNULL(1);
/**
- * @brief Set the content of the frame widget
+ * Clear the box of all children
*
- * Once the content object is set, a previously set one will be deleted.
- * If you want to keep that old content object, use the
- * elm_frame_content_unset() function.
+ * Remove all the elements contained by the box, deleting the respective
+ * objects.
*
- * @param obj The frame object
- * @param content The content will be filled in this frame object
+ * @param obj The box object
+ *
+ * @see elm_box_unpack()
+ * @see elm_box_unpack_all()
*/
- EAPI void elm_frame_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Get the content of the frame widget
+ * Unpack a box item
*
- * Return the content object which is set for this widget
+ * Remove the object given by @p subobj from the box @p obj without
+ * deleting it.
*
- * @param obj The frame object
- * @return The content that is being used
+ * @param obj The box object
+ *
+ * @see elm_box_unpack_all()
+ * @see elm_box_clear()
*/
- EAPI Evas_Object *elm_frame_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_unpack(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
/**
- * @brief Unset the content of the frame widget
- *
- * Unparent and return the content object which was set for this widget
+ * Remove all items from the box, without deleting them
*
- * @param obj The frame object
- * @return The content that was being used
- */
- EAPI Evas_Object *elm_frame_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * @}
+ * Clear the box from all children, but don't delete the respective objects.
+ * If no other references of the box children exist, the objects will never
+ * be deleted, and thus the application will leak the memory. Make sure
+ * when using this function that you hold a reference to all the objects
+ * in the box @p obj.
+ *
+ * @param obj The box object
+ *
+ * @see elm_box_clear()
+ * @see elm_box_unpack()
*/
-
+ EAPI void elm_box_unpack_all(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @defgroup Table Table
+ * Retrieve a list of the objects packed into the box
*
- * A container widget to arrange other widgets in a table where items can
- * also span multiple columns or rows - even overlap (and then be raised or
- * lowered accordingly to adjust stacking if they do overlap).
+ * Returns a new @c Eina_List with a pointer to @c Evas_Object in its nodes.
+ * The order of the list corresponds to the packing order the box uses.
*
- * The followin are examples of how to use a table:
- * @li @ref tutorial_table_01
- * @li @ref tutorial_table_02
+ * You must free this list with eina_list_free() once you are done with it.
*
- * @{
+ * @param obj The box object
*/
+ EAPI const Eina_List *elm_box_children_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Add a new table to the parent
+ * Set the space (padding) between the box's elements.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- */
- EAPI Evas_Object *elm_table_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- /**
- * @brief Set the homogeneous layout in the table
+ * Extra space in pixels that will be added between a box child and its
+ * neighbors after its containing cell has been calculated. This padding
+ * is set for all elements in the box, besides any possible padding that
+ * individual elements may have through their size hints.
*
- * @param obj The layout object
- * @param homogeneous A boolean to set if the layout is homogeneous in the
- * table (EINA_TRUE = homogeneous, EINA_FALSE = no homogeneous)
+ * @param obj The box object
+ * @param horizontal The horizontal space between elements
+ * @param vertical The vertical space between elements
*/
- EAPI void elm_table_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
/**
- * @brief Get the current table homogeneous mode.
+ * Get the space (padding) between the box's elements.
*
- * @param obj The table object
- * @return A boolean to indicating if the layout is homogeneous in the table
- * (EINA_TRUE = homogeneous, EINA_FALSE = no homogeneous)
- */
- EAPI Eina_Bool elm_table_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * @warning <b>Use elm_table_homogeneous_set() instead</b>
- */
- EINA_DEPRECATED EAPI void elm_table_homogenous_set(Evas_Object *obj, Eina_Bool homogenous) EINA_ARG_NONNULL(1);
- /**
- * @warning <b>Use elm_table_homogeneous_get() instead</b>
+ * @param obj The box object
+ * @param horizontal The horizontal space between elements
+ * @param vertical The vertical space between elements
+ *
+ * @see elm_box_padding_set()
*/
- EINA_DEPRECATED EAPI Eina_Bool elm_table_homogenous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
/**
- * @brief Set padding between cells.
+ * Set the alignment of the whole bouding box of contents.
*
- * @param obj The layout object.
- * @param horizontal set the horizontal padding.
- * @param vertical set the vertical padding.
+ * Sets how the bounding box containing all the elements of the box, after
+ * their sizes and position has been calculated, will be aligned within
+ * the space given for the whole box widget.
*
- * Default value is 0.
+ * @param obj The box object
+ * @param horizontal The horizontal alignment of elements
+ * @param vertical The vertical alignment of elements
*/
- EAPI void elm_table_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_align_set(Evas_Object *obj, double horizontal, double vertical) EINA_ARG_NONNULL(1);
/**
- * @brief Get padding between cells.
+ * Get the alignment of the whole bouding box of contents.
*
- * @param obj The layout object.
- * @param horizontal set the horizontal padding.
- * @param vertical set the vertical padding.
+ * @param obj The box object
+ * @param horizontal The horizontal alignment of elements
+ * @param vertical The vertical alignment of elements
+ *
+ * @see elm_box_align_set()
*/
- EAPI void elm_table_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_align_get(const Evas_Object *obj, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
+
/**
- * @brief Add a subobject on the table with the coordinates passed
+ * Force the box to recalculate its children packing.
*
- * @param obj The table object
- * @param subobj The subobject to be added to the table
- * @param x Row number
- * @param y Column number
- * @param w rowspan
- * @param h colspan
+ * If any children was added or removed, box will not calculate the
+ * values immediately rather leaving it to the next main loop
+ * iteration. While this is great as it would save lots of
+ * recalculation, whenever you need to get the position of a just
+ * added item you must force recalculate before doing so.
*
- * @note All positioning inside the table is relative to rows and columns, so
- * a value of 0 for x and y, means the top left cell of the table, and a
- * value of 1 for w and h means @p subobj only takes that 1 cell.
+ * @param obj The box object.
*/
- EAPI void elm_table_pack(Evas_Object *obj, Evas_Object *subobj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_recalculate(Evas_Object *obj);
+
/**
- * @brief Remove child from table.
+ * Set the layout defining function to be used by the box
*
- * @param obj The table object
- * @param subobj The subobject
+ * Whenever anything changes that requires the box in @p obj to recalculate
+ * the size and position of its elements, the function @p cb will be called
+ * to determine what the layout of the children will be.
+ *
+ * Once a custom function is set, everything about the children layout
+ * is defined by it. The flags set by elm_box_horizontal_set() and
+ * elm_box_homogeneous_set() no longer have any meaning, and the values
+ * given by elm_box_padding_set() and elm_box_align_set() are up to this
+ * layout function to decide if they are used and how. These last two
+ * will be found in the @c priv parameter, of type @c Evas_Object_Box_Data,
+ * passed to @p cb. The @c Evas_Object the function receives is not the
+ * Elementary widget, but the internal Evas Box it uses, so none of the
+ * functions described here can be used on it.
+ *
+ * Any of the layout functions in @c Evas can be used here, as well as the
+ * special elm_box_layout_transition().
+ *
+ * The final @p data argument received by @p cb is the same @p data passed
+ * here, and the @p free_data function will be called to free it
+ * whenever the box is destroyed or another layout function is set.
+ *
+ * Setting @p cb to NULL will revert back to the default layout function.
+ *
+ * @param obj The box object
+ * @param cb The callback function used for layout
+ * @param data Data that will be passed to layout function
+ * @param free_data Function called to free @p data
+ *
+ * @see elm_box_layout_transition()
*/
- EAPI void elm_table_unpack(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_layout_set(Evas_Object *obj, Evas_Object_Box_Layout cb, const void *data, void (*free_data)(void *data)) EINA_ARG_NONNULL(1);
/**
- * @brief Faster way to remove all child objects from a table object.
+ * Special layout function that animates the transition from one layout to another
*
- * @param obj The table object
- * @param clear If true, will delete children, else just remove from table.
+ * Normally, when switching the layout function for a box, this will be
+ * reflected immediately on screen on the next render, but it's also
+ * possible to do this through an animated transition.
+ *
+ * This is done by creating an ::Elm_Box_Transition and setting the box
+ * layout to this function.
+ *
+ * For example:
+ * @code
+ * Elm_Box_Transition *t = elm_box_transition_new(1.0,
+ * evas_object_box_layout_vertical, // start
+ * NULL, // data for initial layout
+ * NULL, // free function for initial data
+ * evas_object_box_layout_horizontal, // end
+ * NULL, // data for final layout
+ * NULL, // free function for final data
+ * anim_end, // will be called when animation ends
+ * NULL); // data for anim_end function\
+ * elm_box_layout_set(box, elm_box_layout_transition, t,
+ * elm_box_transition_free);
+ * @endcode
+ *
+ * @note This function can only be used with elm_box_layout_set(). Calling
+ * it directly will not have the expected results.
+ *
+ * @see elm_box_transition_new
+ * @see elm_box_transition_free
+ * @see elm_box_layout_set
*/
- EAPI void elm_table_clear(Evas_Object *obj, Eina_Bool clear) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_layout_transition(Evas_Object *obj, Evas_Object_Box_Data *priv, void *data);
/**
- * @brief Set the packing location of an existing child of the table
+ * Create a new ::Elm_Box_Transition to animate the switch of layouts
*
- * @param subobj The subobject to be modified in the table
- * @param x Row number
- * @param y Column number
- * @param w rowspan
- * @param h colspan
+ * If you want to animate the change from one layout to another, you need
+ * to set the layout function of the box to elm_box_layout_transition(),
+ * passing as user data to it an instance of ::Elm_Box_Transition with the
+ * necessary information to perform this animation. The free function to
+ * set for the layout is elm_box_transition_free().
*
- * Modifies the position of an object already in the table.
+ * The parameters to create an ::Elm_Box_Transition sum up to how long
+ * will it be, in seconds, a layout function to describe the initial point,
+ * another for the final position of the children and one function to be
+ * called when the whole animation ends. This last function is useful to
+ * set the definitive layout for the box, usually the same as the end
+ * layout for the animation, but could be used to start another transition.
*
- * @note All positioning inside the table is relative to rows and columns, so
- * a value of 0 for x and y, means the top left cell of the table, and a
- * value of 1 for w and h means @p subobj only takes that 1 cell.
+ * @param start_layout The layout function that will be used to start the animation
+ * @param start_layout_data The data to be passed the @p start_layout function
+ * @param start_layout_free_data Function to free @p start_layout_data
+ * @param end_layout The layout function that will be used to end the animation
+ * @param end_layout_free_data The data to be passed the @p end_layout function
+ * @param end_layout_free_data Function to free @p end_layout_data
+ * @param transition_end_cb Callback function called when animation ends
+ * @param transition_end_data Data to be passed to @p transition_end_cb
+ * @return An instance of ::Elm_Box_Transition
+ *
+ * @see elm_box_transition_new
+ * @see elm_box_layout_transition
*/
- EAPI void elm_table_pack_set(Evas_Object *subobj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+ EAPI Elm_Box_Transition *elm_box_transition_new(const double duration, Evas_Object_Box_Layout start_layout, void *start_layout_data, void(*start_layout_free_data)(void *data), Evas_Object_Box_Layout end_layout, void *end_layout_data, void(*end_layout_free_data)(void *data), void(*transition_end_cb)(void *data), void *transition_end_data) EINA_ARG_NONNULL(2, 5);
/**
- * @brief Get the packing location of an existing child of the table
+ * Free a Elm_Box_Transition instance created with elm_box_transition_new().
*
- * @param subobj The subobject to be modified in the table
- * @param x Row number
- * @param y Column number
- * @param w rowspan
- * @param h colspan
+ * This function is mostly useful as the @c free_data parameter in
+ * elm_box_layout_set() when elm_box_layout_transition().
*
- * @see elm_table_pack_set()
+ * @param data The Elm_Box_Transition instance to be freed.
+ *
+ * @see elm_box_transition_new
+ * @see elm_box_layout_transition
*/
- EAPI void elm_table_pack_get(Evas_Object *subobj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
+ EAPI void elm_box_transition_free(void *data);
/**
* @}
*/
+ /* button */
/**
- * @defgroup Gengrid Gengrid (Generic grid)
- *
- * This widget aims to position objects in a grid layout while
- * actually creating and rendering only the visible ones, using the
- * same idea as the @ref Genlist "genlist": the user defines a @b
- * class for each item, specifying functions that will be called at
- * object creation, deletion, etc. When those items are selected by
- * the user, a callback function is issued. Users may interact with
- * a gengrid via the mouse (by clicking on items to select them and
- * clicking on the grid's viewport and swiping to pan the whole
- * view) or via the keyboard, navigating through item with the
- * arrow keys.
+ * @defgroup Button Button
*
- * @section Gengrid_Layouts Gengrid layouts
+ * @image html img/widget/button/preview-00.png
+ * @image latex img/widget/button/preview-00.eps
+ * @image html img/widget/button/preview-01.png
+ * @image latex img/widget/button/preview-01.eps
+ * @image html img/widget/button/preview-02.png
+ * @image latex img/widget/button/preview-02.eps
*
- * Gengrids may layout its items in one of two possible layouts:
- * - horizontal or
- * - vertical.
+ * This is a push-button. Press it and run some function. It can contain
+ * a simple label and icon object and it also has an autorepeat feature.
*
- * When in "horizontal mode", items will be placed in @b columns,
- * from top to bottom and, when the space for a column is filled,
+ * This widgets emits the following signals:
+ * @li "clicked": the user clicked the button (press/release).
+ * @li "repeated": the user pressed the button without releasing it.
+ * @li "pressed": button was pressed.
+ * @li "unpressed": button was released after being pressed.
+ * In all three cases, the @c event parameter of the callback will be
+ * @c NULL.
+ *
+ * Also, defined in the default theme, the button has the following styles
+ * available:
+ * @li default: a normal button.
+ * @li anchor: Like default, but the button fades away when the mouse is not
+ * over it, leaving only the text or icon.
+ * @li hoversel_vertical: Internally used by @ref Hoversel to give a
+ * continuous look across its options.
+ * @li hoversel_vertical_entry: Another internal for @ref Hoversel.
+ *
+ * Follow through a complete example @ref button_example_01 "here".
+ * @{
+ */
+ /**
+ * Add a new button to the parent's canvas
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
+ EAPI Evas_Object *elm_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * Set the label used in the button
+ *
+ * The passed @p label can be NULL to clean any existing text in it and
+ * leave the button as an icon only object.
+ *
+ * @param obj The button object
+ * @param label The text will be written on the button
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI void elm_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+ /**
+ * Get the label set for the button
+ *
+ * The string returned is an internal pointer and should not be freed or
+ * altered. It will also become invalid when the button is destroyed.
+ * The string returned, if not NULL, is a stringshare, so if you need to
+ * keep it around even after the button is destroyed, you can use
+ * eina_stringshare_ref().
+ *
+ * @param obj The button object
+ * @return The text set to the label, or NULL if nothing is set
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI const char *elm_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the icon used for the button
+ *
+ * Setting a new icon will delete any other that was previously set, making
+ * any reference to them invalid. If you need to maintain the previous
+ * object alive, unset it first with elm_button_icon_unset().
+ *
+ * @param obj The button object
+ * @param icon The icon object for the button
+ */
+ EAPI void elm_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+ /**
+ * Get the icon used for the button
+ *
+ * Return the icon object which is set for this widget. If the button is
+ * destroyed or another icon is set, the returned object will be deleted
+ * and any reference to it will be invalid.
+ *
+ * @param obj The button object
+ * @return The icon object that is being used
+ *
+ * @see elm_button_icon_unset()
+ */
+ EAPI Evas_Object *elm_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Remove the icon set without deleting it and return the object
+ *
+ * This function drops the reference the button holds of the icon object
+ * and returns this last object. It is used in case you want to remove any
+ * icon, or set another one, without deleting the actual object. The button
+ * will be left without an icon set.
+ *
+ * @param obj The button object
+ * @return The icon object that was being used
+ */
+ EAPI Evas_Object *elm_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Turn on/off the autorepeat event generated when the button is kept pressed
+ *
+ * When off, no autorepeat is performed and buttons emit a normal @c clicked
+ * signal when they are clicked.
+ *
+ * When on, keeping a button pressed will continuously emit a @c repeated
+ * signal until the button is released. The time it takes until it starts
+ * emitting the signal is given by
+ * elm_button_autorepeat_initial_timeout_set(), and the time between each
+ * new emission by elm_button_autorepeat_gap_timeout_set().
+ *
+ * @param obj The button object
+ * @param on A bool to turn on/off the event
+ */
+ EAPI void elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on) EINA_ARG_NONNULL(1);
+ /**
+ * Get whether the autorepeat feature is enabled
+ *
+ * @param obj The button object
+ * @return EINA_TRUE if autorepeat is on, EINA_FALSE otherwise
+ *
+ * @see elm_button_autorepeat_set()
+ */
+ EAPI Eina_Bool elm_button_autorepeat_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the initial timeout before the autorepeat event is generated
+ *
+ * Sets the timeout, in seconds, since the button is pressed until the
+ * first @c repeated signal is emitted. If @p t is 0.0 or less, there
+ * won't be any delay and the even will be fired the moment the button is
+ * pressed.
+ *
+ * @param obj The button object
+ * @param t Timeout in seconds
+ *
+ * @see elm_button_autorepeat_set()
+ * @see elm_button_autorepeat_gap_timeout_set()
+ */
+ EAPI void elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
+ /**
+ * Get the initial timeout before the autorepeat event is generated
+ *
+ * @param obj The button object
+ * @return Timeout in seconds
+ *
+ * @see elm_button_autorepeat_initial_timeout_set()
+ */
+ EAPI double elm_button_autorepeat_initial_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Set the interval between each generated autorepeat event
+ *
+ * After the first @c repeated event is fired, all subsequent ones will
+ * follow after a delay of @p t seconds for each.
+ *
+ * @param obj The button object
+ * @param t Interval in seconds
+ *
+ * @see elm_button_autorepeat_initial_timeout_set()
+ */
+ EAPI void elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
+ /**
+ * Get the interval between each generated autorepeat event
+ *
+ * @param obj The button object
+ * @return Interval in seconds
+ */
+ EAPI double elm_button_autorepeat_gap_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup File_Selector_Button File Selector Button
+ *
+ * @image html img/widget/fileselector_button/preview-00.png
+ * @image latex img/widget/fileselector_button/preview-00.eps
+ * @image html img/widget/fileselector_button/preview-01.png
+ * @image latex img/widget/fileselector_button/preview-01.eps
+ * @image html img/widget/fileselector_button/preview-02.png
+ * @image latex img/widget/fileselector_button/preview-02.eps
+ *
+ * This is a button that, when clicked, creates an Elementary
+ * window (or inner window) <b> with a @ref Fileselector "file
+ * selector widget" within</b>. When a file is chosen, the (inner)
+ * window is closed and the button emits a signal having the
+ * selected file as it's @c event_info.
+ *
+ * This widget encapsulates operations on its internal file
+ * selector on its own API. There is less control over its file
+ * selector than that one would have instatiating one directly.
+ *
+ * The following styles are available for this button:
+ * @li @c "default"
+ * @li @c "anchor"
+ * @li @c "hoversel_vertical"
+ * @li @c "hoversel_vertical_entry"
+ *
+ * Smart callbacks one can register to:
+ * - @c "file,chosen" - the user has selected a path, whose string
+ * pointer comes as the @c event_info data (a stringshared
+ * string)
+ *
+ * Here is an example on its usage:
+ * @li @ref fileselector_button_example
+ *
+ * @see @ref File_Selector_Entry for a similar widget.
+ * @{
+ */
+
+ /**
+ * Add a new file selector button widget to the given parent
+ * Elementary (container) object
+ *
+ * @param parent The parent object
+ * @return a new file selector button widget handle or @c NULL, on
+ * errors
+ */
+ EAPI Evas_Object *elm_fileselector_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the label for a given file selector button widget
+ *
+ * @param obj The file selector button widget
+ * @param label The text label to be displayed on @p obj
+ *
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI void elm_fileselector_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the label set for a given file selector button widget
+ *
+ * @param obj The file selector button widget
+ * @return The button label
+ *
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI const char *elm_fileselector_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the icon on a given file selector button widget
+ *
+ * @param obj The file selector button widget
+ * @param icon The icon object for the button
+ *
+ * Once the icon object is set, a previously set one will be
+ * deleted. If you want to keep the latter, use the
+ * elm_fileselector_button_icon_unset() function.
+ *
+ * @see elm_fileselector_button_icon_get()
+ */
+ EAPI void elm_fileselector_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the icon set for a given file selector button widget
+ *
+ * @param obj The file selector button widget
+ * @return The icon object currently set on @p obj or @c NULL, if
+ * none is
+ *
+ * @see elm_fileselector_button_icon_set()
+ */
+ EAPI Evas_Object *elm_fileselector_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Unset the icon used in a given file selector button widget
+ *
+ * @param obj The file selector button widget
+ * @return The icon object that was being used on @p obj or @c
+ * NULL, on errors
+ *
+ * Unparent and return the icon object which was set for this
+ * widget.
+ *
+ * @see elm_fileselector_button_icon_set()
+ */
+ EAPI Evas_Object *elm_fileselector_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the title for a given file selector button widget's window
+ *
+ * @param obj The file selector button widget
+ * @param title The title string
+ *
+ * This will change the window's title, when the file selector pops
+ * out after a click on the button. Those windows have the default
+ * (unlocalized) value of @c "Select a file" as titles.
+ *
+ * @note It will only take any effect if the file selector
+ * button widget is @b not under "inwin mode".
+ *
+ * @see elm_fileselector_button_window_title_get()
+ */
+ EAPI void elm_fileselector_button_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the title set for a given file selector button widget's
+ * window
+ *
+ * @param obj The file selector button widget
+ * @return Title of the file selector button's window
+ *
+ * @see elm_fileselector_button_window_title_get() for more details
+ */
+ EAPI const char *elm_fileselector_button_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the size of a given file selector button widget's window,
+ * holding the file selector itself.
+ *
+ * @param obj The file selector button widget
+ * @param width The window's width
+ * @param height The window's height
+ *
+ * @note it will only take any effect if the file selector button
+ * widget is @b not under "inwin mode". The default size for the
+ * window (when applicable) is 400x400 pixels.
+ *
+ * @see elm_fileselector_button_window_size_get()
+ */
+ EAPI void elm_fileselector_button_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the size of a given file selector button widget's window,
+ * holding the file selector itself.
+ *
+ * @param obj The file selector button widget
+ * @param width Pointer into which to store the width value
+ * @param height Pointer into which to store the height value
+ *
+ * @note Use @c NULL pointers on the size values you're not
+ * interested in: they'll be ignored by the function.
+ *
+ * @see elm_fileselector_button_window_size_set(), for more details
+ */
+ EAPI void elm_fileselector_button_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the initial file system path for a given file selector
+ * button widget
+ *
+ * @param obj The file selector button widget
+ * @param path The path string
+ *
+ * It must be a <b>directory</b> path, which will have the contents
+ * displayed initially in the file selector's view, when invoked
+ * from @p obj. The default initial path is the @c "HOME"
+ * environment variable's value.
+ *
+ * @see elm_fileselector_button_path_get()
+ */
+ EAPI void elm_fileselector_button_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the initial file system path set for a given file selector
+ * button widget
+ *
+ * @param obj The file selector button widget
+ * @return path The path string
+ *
+ * @see elm_fileselector_button_path_set() for more details
+ */
+ EAPI const char *elm_fileselector_button_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable/disable a tree view in the given file selector button
+ * widget's internal file selector
+ *
+ * @param obj The file selector button widget
+ * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
+ * disable
+ *
+ * This has the same effect as elm_fileselector_expandable_set(),
+ * but now applied to a file selector button's internal file
+ * selector.
+ *
+ * @note There's no way to put a file selector button's internal
+ * file selector in "grid mode", as one may do with "pure" file
+ * selectors.
+ *
+ * @see elm_fileselector_expandable_get()
+ */
+ EAPI void elm_fileselector_button_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether tree view is enabled for the given file selector
+ * button widget's internal file selector
+ *
+ * @param obj The file selector button widget
+ * @return @c EINA_TRUE if @p obj widget's internal file selector
+ * is in tree view, @c EINA_FALSE otherwise (and or errors)
+ *
+ * @see elm_fileselector_expandable_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_button_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given file selector button widget's internal file
+ * selector is to display folders only or the directory contents,
+ * as well.
+ *
+ * @param obj The file selector button widget
+ * @param only @c EINA_TRUE to make @p obj widget's internal file
+ * selector only display directories, @c EINA_FALSE to make files
+ * to be displayed in it too
+ *
+ * This has the same effect as elm_fileselector_folder_only_set(),
+ * but now applied to a file selector button's internal file
+ * selector.
+ *
+ * @see elm_fileselector_folder_only_get()
+ */
+ EAPI void elm_fileselector_button_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given file selector button widget's internal file
+ * selector is displaying folders only or the directory contents,
+ * as well.
+ *
+ * @param obj The file selector button widget
+ * @return @c EINA_TRUE if @p obj widget's internal file
+ * selector is only displaying directories, @c EINA_FALSE if files
+ * are being displayed in it too (and on errors)
+ *
+ * @see elm_fileselector_button_folder_only_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_button_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable/disable the file name entry box where the user can type
+ * in a name for a file, in a given file selector button widget's
+ * internal file selector.
+ *
+ * @param obj The file selector button widget
+ * @param is_save @c EINA_TRUE to make @p obj widget's internal
+ * file selector a "saving dialog", @c EINA_FALSE otherwise
+ *
+ * This has the same effect as elm_fileselector_is_save_set(),
+ * but now applied to a file selector button's internal file
+ * selector.
+ *
+ * @see elm_fileselector_is_save_get()
+ */
+ EAPI void elm_fileselector_button_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether the given file selector button widget's internal
+ * file selector is in "saving dialog" mode
+ *
+ * @param obj The file selector button widget
+ * @return @c EINA_TRUE, if @p obj widget's internal file selector
+ * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
+ * errors)
+ *
+ * @see elm_fileselector_button_is_save_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_button_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given file selector button widget's internal file
+ * selector will raise an Elementary "inner window", instead of a
+ * dedicated Elementary window. By default, it won't.
+ *
+ * @param obj The file selector button widget
+ * @param value @c EINA_TRUE to make it use an inner window, @c
+ * EINA_TRUE to make it use a dedicated window
+ *
+ * @see elm_win_inwin_add() for more information on inner windows
+ * @see elm_fileselector_button_inwin_mode_get()
+ */
+ EAPI void elm_fileselector_button_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given file selector button widget's internal file
+ * selector will raise an Elementary "inner window", instead of a
+ * dedicated Elementary window.
+ *
+ * @param obj The file selector button widget
+ * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
+ * if it will use a dedicated window
+ *
+ * @see elm_fileselector_button_inwin_mode_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_button_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup File_Selector_Entry File Selector Entry
+ *
+ * @image html img/widget/fileselector_entry/preview-00.png
+ * @image latex img/widget/fileselector_entry/preview-00.eps
+ *
+ * This is an entry made to be filled with or display a <b>file
+ * system path string</b>. Besides the entry itself, the widget has
+ * a @ref File_Selector_Button "file selector button" on its side,
+ * which will raise an internal @ref Fileselector "file selector widget",
+ * when clicked, for path selection aided by file system
+ * navigation.
+ *
+ * This file selector may appear in an Elementary window or in an
+ * inner window. When a file is chosen from it, the (inner) window
+ * is closed and the selected file's path string is exposed both as
+ * an smart event and as the new text on the entry.
+ *
+ * This widget encapsulates operations on its internal file
+ * selector on its own API. There is less control over its file
+ * selector than that one would have instatiating one directly.
+ *
+ * Smart callbacks one can register to:
+ * - @c "changed" - The text within the entry was changed
+ * - @c "activated" - The entry has had editing finished and
+ * changes are to be "committed"
+ * - @c "press" - The entry has been clicked
+ * - @c "longpressed" - The entry has been clicked (and held) for a
+ * couple seconds
+ * - @c "clicked" - The entry has been clicked
+ * - @c "clicked,double" - The entry has been double clicked
+ * - @c "focused" - The entry has received focus
+ * - @c "unfocused" - The entry has lost focus
+ * - @c "selection,paste" - A paste action has occurred on the
+ * entry
+ * - @c "selection,copy" - A copy action has occurred on the entry
+ * - @c "selection,cut" - A cut action has occurred on the entry
+ * - @c "unpressed" - The file selector entry's button was released
+ * after being pressed.
+ * - @c "file,chosen" - The user has selected a path via the file
+ * selector entry's internal file selector, whose string pointer
+ * comes as the @c event_info data (a stringshared string)
+ *
+ * Here is an example on its usage:
+ * @li @ref fileselector_entry_example
+ *
+ * @see @ref File_Selector_Button for a similar widget.
+ * @{
+ */
+
+ /**
+ * Add a new file selector entry widget to the given parent
+ * Elementary (container) object
+ *
+ * @param parent The parent object
+ * @return a new file selector entry widget handle or @c NULL, on
+ * errors
+ */
+ EAPI Evas_Object *elm_fileselector_entry_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the label for a given file selector entry widget's button
+ *
+ * @param obj The file selector entry widget
+ * @param label The text label to be displayed on @p obj widget's
+ * button
+ *
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI void elm_fileselector_entry_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the label set for a given file selector entry widget's button
+ *
+ * @param obj The file selector entry widget
+ * @return The widget button's label
+ *
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI const char *elm_fileselector_entry_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the icon on a given file selector entry widget's button
+ *
+ * @param obj The file selector entry widget
+ * @param icon The icon object for the entry's button
+ *
+ * Once the icon object is set, a previously set one will be
+ * deleted. If you want to keep the latter, use the
+ * elm_fileselector_entry_button_icon_unset() function.
+ *
+ * @see elm_fileselector_entry_button_icon_get()
+ */
+ EAPI void elm_fileselector_entry_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the icon set for a given file selector entry widget's button
+ *
+ * @param obj The file selector entry widget
+ * @return The icon object currently set on @p obj widget's button
+ * or @c NULL, if none is
+ *
+ * @see elm_fileselector_entry_button_icon_set()
+ */
+ EAPI Evas_Object *elm_fileselector_entry_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Unset the icon used in a given file selector entry widget's
+ * button
+ *
+ * @param obj The file selector entry widget
+ * @return The icon object that was being used on @p obj widget's
+ * button or @c NULL, on errors
+ *
+ * Unparent and return the icon object which was set for this
+ * widget's button.
+ *
+ * @see elm_fileselector_entry_button_icon_set()
+ */
+ EAPI Evas_Object *elm_fileselector_entry_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the title for a given file selector entry widget's window
+ *
+ * @param obj The file selector entry widget
+ * @param title The title string
+ *
+ * This will change the window's title, when the file selector pops
+ * out after a click on the entry's button. Those windows have the
+ * default (unlocalized) value of @c "Select a file" as titles.
+ *
+ * @note It will only take any effect if the file selector
+ * entry widget is @b not under "inwin mode".
+ *
+ * @see elm_fileselector_entry_window_title_get()
+ */
+ EAPI void elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the title set for a given file selector entry widget's
+ * window
+ *
+ * @param obj The file selector entry widget
+ * @return Title of the file selector entry's window
+ *
+ * @see elm_fileselector_entry_window_title_get() for more details
+ */
+ EAPI const char *elm_fileselector_entry_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the size of a given file selector entry widget's window,
+ * holding the file selector itself.
+ *
+ * @param obj The file selector entry widget
+ * @param width The window's width
+ * @param height The window's height
+ *
+ * @note it will only take any effect if the file selector entry
+ * widget is @b not under "inwin mode". The default size for the
+ * window (when applicable) is 400x400 pixels.
+ *
+ * @see elm_fileselector_entry_window_size_get()
+ */
+ EAPI void elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the size of a given file selector entry widget's window,
+ * holding the file selector itself.
+ *
+ * @param obj The file selector entry widget
+ * @param width Pointer into which to store the width value
+ * @param height Pointer into which to store the height value
+ *
+ * @note Use @c NULL pointers on the size values you're not
+ * interested in: they'll be ignored by the function.
+ *
+ * @see elm_fileselector_entry_window_size_set(), for more details
+ */
+ EAPI void elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the initial file system path and the entry's path string for
+ * a given file selector entry widget
+ *
+ * @param obj The file selector entry widget
+ * @param path The path string
+ *
+ * It must be a <b>directory</b> path, which will have the contents
+ * displayed initially in the file selector's view, when invoked
+ * from @p obj. The default initial path is the @c "HOME"
+ * environment variable's value.
+ *
+ * @see elm_fileselector_entry_path_get()
+ */
+ EAPI void elm_fileselector_entry_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the entry's path string for a given file selector entry
+ * widget
+ *
+ * @param obj The file selector entry widget
+ * @return path The path string
+ *
+ * @see elm_fileselector_entry_path_set() for more details
+ */
+ EAPI const char *elm_fileselector_entry_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable/disable a tree view in the given file selector entry
+ * widget's internal file selector
+ *
+ * @param obj The file selector entry widget
+ * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
+ * disable
+ *
+ * This has the same effect as elm_fileselector_expandable_set(),
+ * but now applied to a file selector entry's internal file
+ * selector.
+ *
+ * @note There's no way to put a file selector entry's internal
+ * file selector in "grid mode", as one may do with "pure" file
+ * selectors.
+ *
+ * @see elm_fileselector_expandable_get()
+ */
+ EAPI void elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether tree view is enabled for the given file selector
+ * entry widget's internal file selector
+ *
+ * @param obj The file selector entry widget
+ * @return @c EINA_TRUE if @p obj widget's internal file selector
+ * is in tree view, @c EINA_FALSE otherwise (and or errors)
+ *
+ * @see elm_fileselector_expandable_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_entry_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given file selector entry widget's internal file
+ * selector is to display folders only or the directory contents,
+ * as well.
+ *
+ * @param obj The file selector entry widget
+ * @param only @c EINA_TRUE to make @p obj widget's internal file
+ * selector only display directories, @c EINA_FALSE to make files
+ * to be displayed in it too
+ *
+ * This has the same effect as elm_fileselector_folder_only_set(),
+ * but now applied to a file selector entry's internal file
+ * selector.
+ *
+ * @see elm_fileselector_folder_only_get()
+ */
+ EAPI void elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given file selector entry widget's internal file
+ * selector is displaying folders only or the directory contents,
+ * as well.
+ *
+ * @param obj The file selector entry widget
+ * @return @c EINA_TRUE if @p obj widget's internal file
+ * selector is only displaying directories, @c EINA_FALSE if files
+ * are being displayed in it too (and on errors)
+ *
+ * @see elm_fileselector_entry_folder_only_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_entry_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable/disable the file name entry box where the user can type
+ * in a name for a file, in a given file selector entry widget's
+ * internal file selector.
+ *
+ * @param obj The file selector entry widget
+ * @param is_save @c EINA_TRUE to make @p obj widget's internal
+ * file selector a "saving dialog", @c EINA_FALSE otherwise
+ *
+ * This has the same effect as elm_fileselector_is_save_set(),
+ * but now applied to a file selector entry's internal file
+ * selector.
+ *
+ * @see elm_fileselector_is_save_get()
+ */
+ EAPI void elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether the given file selector entry widget's internal
+ * file selector is in "saving dialog" mode
+ *
+ * @param obj The file selector entry widget
+ * @return @c EINA_TRUE, if @p obj widget's internal file selector
+ * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
+ * errors)
+ *
+ * @see elm_fileselector_entry_is_save_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_entry_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given file selector entry widget's internal file
+ * selector will raise an Elementary "inner window", instead of a
+ * dedicated Elementary window. By default, it won't.
+ *
+ * @param obj The file selector entry widget
+ * @param value @c EINA_TRUE to make it use an inner window, @c
+ * EINA_TRUE to make it use a dedicated window
+ *
+ * @see elm_win_inwin_add() for more information on inner windows
+ * @see elm_fileselector_entry_inwin_mode_get()
+ */
+ EAPI void elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given file selector entry widget's internal file
+ * selector will raise an Elementary "inner window", instead of a
+ * dedicated Elementary window.
+ *
+ * @param obj The file selector entry widget
+ * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
+ * if it will use a dedicated window
+ *
+ * @see elm_fileselector_entry_inwin_mode_set() for more details
+ */
+ EAPI Eina_Bool elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the initial file system path for a given file selector entry
+ * widget
+ *
+ * @param obj The file selector entry widget
+ * @param path The path string
+ *
+ * It must be a <b>directory</b> path, which will have the contents
+ * displayed initially in the file selector's view, when invoked
+ * from @p obj. The default initial path is the @c "HOME"
+ * environment variable's value.
+ *
+ * @see elm_fileselector_entry_path_get()
+ */
+ EAPI void elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the parent directory's path to the latest file selection on
+ * a given filer selector entry widget
+ *
+ * @param obj The file selector object
+ * @return The (full) path of the directory of the last selection
+ * on @p obj widget, a @b stringshared string
+ *
+ * @see elm_fileselector_entry_path_set()
+ */
+ EAPI const char *elm_fileselector_entry_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Scroller Scroller
+ *
+ * A scroller holds a single object and "scrolls it around". This means that
+ * it allows the user to use a scrollbar (or a finger) to drag the viewable
+ * region around, allowing to move through a much larger object that is
+ * contained in the scroller. The scroiller will always have a small minimum
+ * size by default as it won't be limited by the contents of the scroller.
+ *
+ * Signals that you can add callbacks for are:
+ * @li "edge,left" - the left edge of the content has been reached
+ * @li "edge,right" - the right edge of the content has been reached
+ * @li "edge,top" - the top edge of the content has been reached
+ * @li "edge,bottom" - the bottom edge of the content has been reached
+ * @li "scroll" - the content has been scrolled (moved)
+ * @li "scroll,anim,start" - scrolling animation has started
+ * @li "scroll,anim,stop" - scrolling animation has stopped
+ * @li "scroll,drag,start" - dragging the contents around has started
+ * @li "scroll,drag,stop" - dragging the contents around has stopped
+ * @note The "scroll,anim,*" and "scroll,drag,*" signals are only emitted by
+ * user intervetion.
+ *
+ * @note When Elemementary is in embedded mode the scrollbars will not be
+ * dragable, they appear merely as indicators of how much has been scrolled.
+ * @note When Elementary is in desktop mode the thumbscroll(a.k.a.
+ * fingerscroll) won't work.
+ *
+ * In @ref tutorial_scroller you'll find an example of how to use most of
+ * this API.
+ * @{
+ */
+ /**
+ * @brief Type that controls when scrollbars should appear.
+ *
+ * @see elm_scroller_policy_set()
+ */
+ typedef enum _Elm_Scroller_Policy
+ {
+ ELM_SCROLLER_POLICY_AUTO = 0, /**< Show scrollbars as needed */
+ ELM_SCROLLER_POLICY_ON, /**< Always show scrollbars */
+ ELM_SCROLLER_POLICY_OFF, /**< Never show scrollbars */
+ ELM_SCROLLER_POLICY_LAST
+ } Elm_Scroller_Policy;
+ /**
+ * @brief Add a new scroller to the parent
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
+ EAPI Evas_Object *elm_scroller_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the content of the scroller widget (the object to be scrolled around).
+ *
+ * @param obj The scroller object
+ * @param content The new content object
+ *
+ * Once the content object is set, a previously set one will be deleted.
+ * If you want to keep that old content object, use the
+ * elm_scroller_content_unset() function.
+ */
+ EAPI void elm_scroller_content_set(Evas_Object *obj, Evas_Object *child) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the content of the scroller widget
+ *
+ * @param obj The slider object
+ * @return The content that is being used
+ *
+ * Return the content object which is set for this widget
+ *
+ * @see elm_scroller_content_set()
+ */
+ EAPI Evas_Object *elm_scroller_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Unset the content of the scroller widget
+ *
+ * @param obj The slider object
+ * @return The content that was being used
+ *
+ * Unparent and return the content object which was set for this widget
+ *
+ * @see elm_scroller_content_set()
+ */
+ EAPI Evas_Object *elm_scroller_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set custom theme elements for the scroller
+ *
+ * @param obj The scroller object
+ * @param widget The widget name to use (default is "scroller")
+ * @param base The base name to use (default is "base")
+ */
+ EAPI void elm_scroller_custom_widget_base_theme_set(Evas_Object *obj, const char *widget, const char *base) EINA_ARG_NONNULL(1, 2, 3);
+ /**
+ * @brief Make the scroller minimum size limited to the minimum size of the content
+ *
+ * @param obj The scroller object
+ * @param w Enable limiting minimum size horizontally
+ * @param h Enable limiting minimum size vertically
+ *
+ * By default the scroller will be as small as its design allows,
+ * irrespective of its content. This will make the scroller minimum size the
+ * right size horizontally and/or vertically to perfectly fit its content in
+ * that direction.
+ */
+ EAPI void elm_scroller_content_min_limit(Evas_Object *obj, Eina_Bool w, Eina_Bool h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Show a specific virtual region within the scroller content object
+ *
+ * @param obj The scroller object
+ * @param x X coordinate of the region
+ * @param y Y coordinate of the region
+ * @param w Width of the region
+ * @param h Height of the region
+ *
+ * This will ensure all (or part if it does not fit) of the designated
+ * region in the virtual content object (0, 0 starting at the top-left of the
+ * virtual content object) is shown within the scroller.
+ */
+ EAPI void elm_scroller_region_show(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the scrollbar visibility policy
+ *
+ * @param obj The scroller object
+ * @param policy_h Horizontal scrollbar policy
+ * @param policy_v Vertical scrollbar policy
+ *
+ * This sets the scrollbar visibility policy for the given scroller.
+ * ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it is
+ * needed, and otherwise kept hidden. ELM_SCROLLER_POLICY_ON turns it on all
+ * the time, and ELM_SCROLLER_POLICY_OFF always keeps it off. This applies
+ * respectively for the horizontal and vertical scrollbars.
+ */
+ EAPI void elm_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Gets scrollbar visibility policy
+ *
+ * @param obj The scroller object
+ * @param policy_h Horizontal scrollbar policy
+ * @param policy_v Vertical scrollbar policy
+ *
+ * @see elm_scroller_policy_set()
+ */
+ EAPI void elm_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the currently visible content region
+ *
+ * @param obj The scroller object
+ * @param x X coordinate of the region
+ * @param y Y coordinate of the region
+ * @param w Width of the region
+ * @param h Height of the region
+ *
+ * This gets the current region in the content object that is visible through
+ * the scroller. The region co-ordinates are returned in the @p x, @p y, @p
+ * w, @p h values pointed to.
+ *
+ * @note All coordinates are relative to the content.
+ *
+ * @see elm_scroller_region_show()
+ */
+ EAPI void elm_scroller_region_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the size of the content object
+ *
+ * @param obj The scroller object
+ * @param w Width return
+ * @param h Height return
+ *
+ * This gets the size of the content object of the scroller.
+ */
+ EAPI void elm_scroller_child_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set bouncing behavior
+ *
+ * @param obj The scroller object
+ * @param h_bounce Will the scroller bounce horizontally or not
+ * @param v_bounce Will the scroller bounce vertically or not
+ *
+ * When scrolling, the scroller may "bounce" when reaching an edge of the
+ * content object. This is a visual way to indicate the end has been reached.
+ * This is enabled by default for both axis. This will set if it is enabled
+ * for that axis with the boolean parameters for each axis.
+ */
+ EAPI void elm_scroller_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the bounce mode
+ *
+ * @param obj The Scroller object
+ * @param h_bounce Allow bounce horizontally
+ * @param v_bounce Allow bounce vertically
+ *
+ * @see elm_scroller_bounce_set()
+ */
+ EAPI void elm_scroller_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set scroll page size relative to viewport size.
+ *
+ * @param obj The scroller object
+ * @param h_pagerel The horizontal page relative size
+ * @param v_pagerel The vertical page relative size
+ *
+ * The scroller is capable of limiting scrolling by the user to "pages". That
+ * is to jump by and only show a "whole page" at a time as if the continuous
+ * area of the scroller content is split into page sized pieces. This sets
+ * the size of a page relative to the viewport of the scroller. 1.0 is "1
+ * viewport" is size (horizontally or vertically). 0.0 turns it off in that
+ * axis. This is mutually exclusive with page size
+ * (see elm_scroller_page_size_set() for more information). Likewise 0.5
+ * is "half a viewport". Sane usable valus are normally between 0.0 and 1.0
+ * including 1.0. If you only want 1 axis to be page "limited", use 0.0 for
+ * the other axis.
+ */
+ EAPI void elm_scroller_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set scroll page size.
+ *
+ * @param obj The scroller object
+ * @param h_pagesize The horizontal page size
+ * @param v_pagesize The vertical page size
+ *
+ * This sets the page size to an absolute fixed value, with 0 turning it off
+ * for that axis.
+ *
+ * @see elm_scroller_page_relative_set()
+ */
+ EAPI void elm_scroller_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get scroll current page number.
+ *
+ * @param obj The scroller object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * The page number starts from 0. 0 is the first page.
+ * Current page means the page which meet the top-left of the viewport.
+ * If there are two or more pages in the viewport, it returns the number of page
+ * which meet the top-left of the viewport.
+ *
+ * @see elm_scroller_last_page_get()
+ * @see elm_scroller_page_show()
+ * @see elm_scroller_page_brint_in()
+ */
+ EAPI void elm_scroller_current_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get scroll last page number.
+ *
+ * @param obj The scroller object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * The page number starts from 0. 0 is the first page.
+ * This returns the last page number among the pages.
+ *
+ * @see elm_scroller_current_page_get()
+ * @see elm_scroller_page_show()
+ * @see elm_scroller_page_brint_in()
+ */
+ EAPI void elm_scroller_last_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber) EINA_ARG_NONNULL(1);
+ /**
+ * Show a specific virtual region within the scroller content object by page number.
+ *
+ * @param obj The scroller object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * 0, 0 of the indicated page is located at the top-left of the viewport.
+ * This will jump to the page directly without animation.
+ *
+ * Example of usage:
+ *
+ * @code
+ * sc = elm_scroller_add(win);
+ * elm_scroller_content_set(sc, content);
+ * elm_scroller_page_relative_set(sc, 1, 0);
+ * elm_scroller_current_page_get(sc, &h_page, &v_page);
+ * elm_scroller_page_show(sc, h_page + 1, v_page);
+ * @endcode
+ *
+ * @see elm_scroller_page_bring_in()
+ */
+ EAPI void elm_scroller_page_show(Evas_Object *obj, int h_pagenumber, int v_pagenumber) EINA_ARG_NONNULL(1);
+ /**
+ * Show a specific virtual region within the scroller content object by page number.
+ *
+ * @param obj The scroller object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * 0, 0 of the indicated page is located at the top-left of the viewport.
+ * This will slide to the page with animation.
+ *
+ * Example of usage:
+ *
+ * @code
+ * sc = elm_scroller_add(win);
+ * elm_scroller_content_set(sc, content);
+ * elm_scroller_page_relative_set(sc, 1, 0);
+ * elm_scroller_last_page_get(sc, &h_page, &v_page);
+ * elm_scroller_page_bring_in(sc, h_page, v_page);
+ * @endcode
+ *
+ * @see elm_scroller_page_show()
+ */
+ EAPI void elm_scroller_page_bring_in(Evas_Object *obj, int h_pagenumber, int v_pagenumber) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Show a specific virtual region within the scroller content object.
+ *
+ * @param obj The scroller object
+ * @param x X coordinate of the region
+ * @param y Y coordinate of the region
+ * @param w Width of the region
+ * @param h Height of the region
+ *
+ * This will ensure all (or part if it does not fit) of the designated
+ * region in the virtual content object (0, 0 starting at the top-left of the
+ * virtual content object) is shown within the scroller. Unlike
+ * elm_scroller_region_show(), this allow the scroller to "smoothly slide"
+ * to this location (if configuration in general calls for transitions). It
+ * may not jump immediately to the new location and make take a while and
+ * show other content along the way.
+ *
+ * @see elm_scroller_region_show()
+ */
+ EAPI void elm_scroller_region_bring_in(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set event propagation on a scroller
+ *
+ * @param obj The scroller object
+ * @param propagation If propagation is enabled or not
+ *
+ * This enables or disabled event propagation from the scroller content to
+ * the scroller and its parent. By default event propagation is disabled.
+ */
+ EAPI void elm_scroller_propagate_events_set(Evas_Object *obj, Eina_Bool propagation);
+ /**
+ * @brief Get event propagation for a scroller
+ *
+ * @param obj The scroller object
+ * @return The propagation state
+ *
+ * This gets the event propagation for a scroller.
+ *
+ * @see elm_scroller_propagate_events_set()
+ */
+ EAPI Eina_Bool elm_scroller_propagate_events_get(const Evas_Object *obj);
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Label Label
+ *
+ * @image html img/widget/label/preview-00.png
+ * @image latex img/widget/label/preview-00.eps
+ *
+ * @brief Widget to display text, with simple html-like markup.
+ *
+ * The Label widget @b doesn't allow text to overflow its boundaries, if the
+ * text doesn't fit the geometry of the label it will be ellipsized or be
+ * cut. Elementary provides several themes for this widget:
+ * @li default - No animation
+ * @li marker - Centers the text in the label and make it bold by default
+ * @li slide_long - The entire text appears from the right of the screen and
+ * slides until it disappears in the left of the screen(reappering on the
+ * right again).
+ * @li slide_short - The text appears in the left of the label and slides to
+ * the right to show the overflow. When all of the text has been shown the
+ * position is reset.
+ * @li slide_bounce - The text appears in the left of the label and slides to
+ * the right to show the overflow. When all of the text has been shown the
+ * animation reverses, moving the text to the left.
+ *
+ * Custom themes can of course invent new markup tags and style them any way
+ * they like.
+ *
+ * See @ref tutorial_label for a demonstration of how to use a label widget.
+ * @{
+ */
+ /**
+ * @brief Add a new label to the parent
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
+ EAPI Evas_Object *elm_label_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the label on the label object
+ *
+ * @param obj The label object
+ * @param label The label will be used on the label object
+ * @deprecated See elm_object_text_set()
+ */
+ EINA_DEPRECATED EAPI void elm_label_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1); /* deprecated, use elm_object_text_set instead */
+ /**
+ * @brief Get the label used on the label object
+ *
+ * @param obj The label object
+ * @return The string inside the label
+ * @deprecated See elm_object_text_get()
+ */
+ EINA_DEPRECATED EAPI const char *elm_label_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); /* deprecated, use elm_object_text_get instead */
+ /**
+ * @brief Set the wrapping behavior of the label
+ *
+ * @param obj The label object
+ * @param wrap To wrap text or not
+ *
+ * By default no wrapping is done. Possible values for @p wrap are:
+ * @li ELM_WRAP_NONE - No wrapping
+ * @li ELM_WRAP_CHAR - wrap between characters
+ * @li ELM_WRAP_WORD - wrap between words
+ * @li ELM_WRAP_MIXED - Word wrap, and if that fails, char wrap
+ */
+ EAPI void elm_label_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the wrapping behavior of the label
+ *
+ * @param obj The label object
+ * @return Wrap type
+ *
+ * @see elm_label_line_wrap_set()
+ */
+ EAPI Elm_Wrap_Type elm_label_line_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set wrap width of the label
+ *
+ * @param obj The label object
+ * @param w The wrap width in pixels at a minimum where words need to wrap
+ *
+ * This function sets the maximum width size hint of the label.
+ *
+ * @warning This is only relevant if the label is inside a container.
+ */
+ EAPI void elm_label_wrap_width_set(Evas_Object *obj, Evas_Coord w) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get wrap width of the label
+ *
+ * @param obj The label object
+ * @return The wrap width in pixels at a minimum where words need to wrap
+ *
+ * @see elm_label_wrap_width_set()
+ */
+ EAPI Evas_Coord elm_label_wrap_width_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set wrap height of the label
+ *
+ * @param obj The label object
+ * @param h The wrap height in pixels at a minimum where words need to wrap
+ *
+ * This function sets the maximum height size hint of the label.
+ *
+ * @warning This is only relevant if the label is inside a container.
+ */
+ EAPI void elm_label_wrap_height_set(Evas_Object *obj, Evas_Coord h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief get wrap width of the label
+ *
+ * @param obj The label object
+ * @return The wrap height in pixels at a minimum where words need to wrap
+ */
+ EAPI Evas_Coord elm_label_wrap_height_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the font size on the label object.
+ *
+ * @param obj The label object
+ * @param size font size
+ *
+ * @warning NEVER use this. It is for hyper-special cases only. use styles
+ * instead. e.g. "big", "medium", "small" - or better name them by use:
+ * "title", "footnote", "quote" etc.
+ */
+ EAPI void elm_label_fontsize_set(Evas_Object *obj, int fontsize) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the text color on the label object
+ *
+ * @param obj The label object
+ * @param r Red property background color of The label object
+ * @param g Green property background color of The label object
+ * @param b Blue property background color of The label object
+ * @param a Alpha property background color of The label object
+ *
+ * @warning NEVER use this. It is for hyper-special cases only. use styles
+ * instead. e.g. "big", "medium", "small" - or better name them by use:
+ * "title", "footnote", "quote" etc.
+ */
+ EAPI void elm_label_text_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the text align on the label object
+ *
+ * @param obj The label object
+ * @param align align mode ("left", "center", "right")
+ *
+ * @warning NEVER use this. It is for hyper-special cases only. use styles
+ * instead. e.g. "big", "medium", "small" - or better name them by use:
+ * "title", "footnote", "quote" etc.
+ */
+ EAPI void elm_label_text_align_set(Evas_Object *obj, const char *alignmode) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set background color of the label
+ *
+ * @param obj The label object
+ * @param r Red property background color of The label object
+ * @param g Green property background color of The label object
+ * @param b Blue property background color of The label object
+ * @param a Alpha property background alpha of The label object
+ *
+ * @warning NEVER use this. It is for hyper-special cases only. use styles
+ * instead. e.g. "big", "medium", "small" - or better name them by use:
+ * "title", "footnote", "quote" etc.
+ */
+ EAPI void elm_label_background_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the ellipsis behavior of the label
+ *
+ * @param obj The label object
+ * @param ellipsis To ellipsis text or not
+ *
+ * If set to true and the text doesn't fit in the label an ellipsis("...")
+ * will be shown at the end of the widget.
+ *
+ * @warning This doesn't work with slide(elm_label_slide_set()) or if the
+ * choosen wrap method was ELM_WRAP_WORD.
+ */
+ EAPI void elm_label_ellipsis_set(Evas_Object *obj, Eina_Bool ellipsis) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the text slide of the label
+ *
+ * @param obj The label object
+ * @param slide To start slide or stop
+ *
+ * If set to true the text of the label will slide throught the length of
+ * label.
+ *
+ * @warning This only work with the themes "slide_short", "slide_long" and
+ * "slide_bounce".
+ */
+ EAPI void elm_label_slide_set(Evas_Object *obj, Eina_Bool slide) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the text slide mode of the label
+ *
+ * @param obj The label object
+ * @return slide slide mode value
+ *
+ * @see elm_label_slide_set()
+ */
+ EAPI Eina_Bool elm_label_slide_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the slide duration(speed) of the label
+ *
+ * @param obj The label object
+ * @return The duration in seconds in moving text from slide begin position
+ * to slide end position
+ */
+ EAPI void elm_label_slide_duration_set(Evas_Object *obj, double duration) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the slide duration(speed) of the label
+ *
+ * @param obj The label object
+ * @return The duration time in moving text from slide begin position to slide end position
+ *
+ * @see elm_label_slide_duration_set()
+ */
+ EAPI double elm_label_slide_duration_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Toggle Toggle
+ *
+ * @image html img/widget/toggle/preview-00.png
+ * @image latex img/widget/toggle/preview-00.eps
+ *
+ * @brief A toggle is a slider which can be used to toggle between
+ * two values. It has two states: on and off.
+ *
+ * Signals that you can add callbacks for are:
+ * @li "changed" - Whenever the toggle value has been changed. Is not called
+ * until the toggle is released by the cursor (assuming it
+ * has been triggered by the cursor in the first place).
+ *
+ * @ref tutorial_toggle show how to use a toggle.
+ * @{
+ */
+ /**
+ * @brief Add a toggle to @p parent.
+ *
+ * @param parent The parent object
+ *
+ * @return The toggle object
+ */
+ EAPI Evas_Object *elm_toggle_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Sets the label to be displayed with the toggle.
+ *
+ * @param obj The toggle object
+ * @param label The label to be displayed
+ *
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI void elm_toggle_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Gets the label of the toggle
+ *
+ * @param obj toggle object
+ * @return The label of the toggle
+ *
+ * @deprecated use elm_object_text_get() instead.
+ */
+ EINA_DEPRECATED EAPI const char *elm_toggle_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the icon used for the toggle
+ *
+ * @param obj The toggle object
+ * @param icon The icon object for the button
+ *
+ * Once the icon object is set, a previously set one will be deleted
+ * If you want to keep that old content object, use the
+ * elm_toggle_icon_unset() function.
+ */
+ EAPI void elm_toggle_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the icon used for the toggle
+ *
+ * @param obj The toggle object
+ * @return The icon object that is being used
+ *
+ * Return the icon object which is set for this widget.
+ *
+ * @see elm_toggle_icon_set()
+ */
+ EAPI Evas_Object *elm_toggle_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Unset the icon used for the toggle
+ *
+ * @param obj The toggle object
+ * @return The icon object that was being used
+ *
+ * Unparent and return the icon object which was set for this widget.
+ *
+ * @see elm_toggle_icon_set()
+ */
+ EAPI Evas_Object *elm_toggle_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Sets the labels to be associated with the on and off states of the toggle.
+ *
+ * @param obj The toggle object
+ * @param onlabel The label displayed when the toggle is in the "on" state
+ * @param offlabel The label displayed when the toggle is in the "off" state
+ */
+ EAPI void elm_toggle_states_labels_set(Evas_Object *obj, const char *onlabel, const char *offlabel) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Gets the labels associated with the on and off states of the toggle.
+ *
+ * @param obj The toggle object
+ * @param onlabel A char** to place the onlabel of @p obj into
+ * @param offlabel A char** to place the offlabel of @p obj into
+ */
+ EAPI void elm_toggle_states_labels_get(const Evas_Object *obj, const char **onlabel, const char **offlabel) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Sets the state of the toggle to @p state.
+ *
+ * @param obj The toggle object
+ * @param state The state of @p obj
+ */
+ EAPI void elm_toggle_state_set(Evas_Object *obj, Eina_Bool state) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Gets the state of the toggle to @p state.
+ *
+ * @param obj The toggle object
+ * @return The state of @p obj
+ */
+ EAPI Eina_Bool elm_toggle_state_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Sets the state pointer of the toggle to @p statep.
+ *
+ * @param obj The toggle object
+ * @param statep The state pointer of @p obj
+ */
+ EAPI void elm_toggle_state_pointer_set(Evas_Object *obj, Eina_Bool *statep) EINA_ARG_NONNULL(1);
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Frame Frame
+ *
+ * @image html img/widget/frame/preview-00.png
+ * @image latex img/widget/frame/preview-00.eps
+ *
+ * @brief Frame is a widget that holds some content and has a title.
+ *
+ * The default look is a frame with a title, but Frame supports multple
+ * styles:
+ * @li default
+ * @li pad_small
+ * @li pad_medium
+ * @li pad_large
+ * @li pad_huge
+ * @li outdent_top
+ * @li outdent_bottom
+ *
+ * Of all this styles only default shows the title. Frame emits no signals.
+ *
+ * For a detailed example see the @ref tutorial_frame.
+ *
+ * @{
+ */
+ /**
+ * @brief Add a new frame to the parent
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
+ EAPI Evas_Object *elm_frame_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the frame label
+ *
+ * @param obj The frame object
+ * @param label The label of this frame object
+ *
+ * @deprecated use elm_object_text_set() instead.
+ */
+ EINA_DEPRECATED EAPI void elm_frame_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the frame label
+ *
+ * @param obj The frame object
+ *
+ * @return The label of this frame objet or NULL if unable to get frame
+ *
+ * @deprecated use elm_object_text_get() instead.
+ */
+ EINA_DEPRECATED EAPI const char *elm_frame_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the content of the frame widget
+ *
+ * Once the content object is set, a previously set one will be deleted.
+ * If you want to keep that old content object, use the
+ * elm_frame_content_unset() function.
+ *
+ * @param obj The frame object
+ * @param content The content will be filled in this frame object
+ */
+ EAPI void elm_frame_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the content of the frame widget
+ *
+ * Return the content object which is set for this widget
+ *
+ * @param obj The frame object
+ * @return The content that is being used
+ */
+ EAPI Evas_Object *elm_frame_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Unset the content of the frame widget
+ *
+ * Unparent and return the content object which was set for this widget
+ *
+ * @param obj The frame object
+ * @return The content that was being used
+ */
+ EAPI Evas_Object *elm_frame_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Table Table
+ *
+ * A container widget to arrange other widgets in a table where items can
+ * also span multiple columns or rows - even overlap (and then be raised or
+ * lowered accordingly to adjust stacking if they do overlap).
+ *
+ * The followin are examples of how to use a table:
+ * @li @ref tutorial_table_01
+ * @li @ref tutorial_table_02
+ *
+ * @{
+ */
+ /**
+ * @brief Add a new table to the parent
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
+ EAPI Evas_Object *elm_table_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the homogeneous layout in the table
+ *
+ * @param obj The layout object
+ * @param homogeneous A boolean to set if the layout is homogeneous in the
+ * table (EINA_TRUE = homogeneous, EINA_FALSE = no homogeneous)
+ */
+ EAPI void elm_table_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the current table homogeneous mode.
+ *
+ * @param obj The table object
+ * @return A boolean to indicating if the layout is homogeneous in the table
+ * (EINA_TRUE = homogeneous, EINA_FALSE = no homogeneous)
+ */
+ EAPI Eina_Bool elm_table_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @warning <b>Use elm_table_homogeneous_set() instead</b>
+ */
+ EINA_DEPRECATED EAPI void elm_table_homogenous_set(Evas_Object *obj, Eina_Bool homogenous) EINA_ARG_NONNULL(1);
+ /**
+ * @warning <b>Use elm_table_homogeneous_get() instead</b>
+ */
+ EINA_DEPRECATED EAPI Eina_Bool elm_table_homogenous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set padding between cells.
+ *
+ * @param obj The layout object.
+ * @param horizontal set the horizontal padding.
+ * @param vertical set the vertical padding.
+ *
+ * Default value is 0.
+ */
+ EAPI void elm_table_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get padding between cells.
+ *
+ * @param obj The layout object.
+ * @param horizontal set the horizontal padding.
+ * @param vertical set the vertical padding.
+ */
+ EAPI void elm_table_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Add a subobject on the table with the coordinates passed
+ *
+ * @param obj The table object
+ * @param subobj The subobject to be added to the table
+ * @param x Row number
+ * @param y Column number
+ * @param w rowspan
+ * @param h colspan
+ *
+ * @note All positioning inside the table is relative to rows and columns, so
+ * a value of 0 for x and y, means the top left cell of the table, and a
+ * value of 1 for w and h means @p subobj only takes that 1 cell.
+ */
+ EAPI void elm_table_pack(Evas_Object *obj, Evas_Object *subobj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Remove child from table.
+ *
+ * @param obj The table object
+ * @param subobj The subobject
+ */
+ EAPI void elm_table_unpack(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Faster way to remove all child objects from a table object.
+ *
+ * @param obj The table object
+ * @param clear If true, will delete children, else just remove from table.
+ */
+ EAPI void elm_table_clear(Evas_Object *obj, Eina_Bool clear) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the packing location of an existing child of the table
+ *
+ * @param subobj The subobject to be modified in the table
+ * @param x Row number
+ * @param y Column number
+ * @param w rowspan
+ * @param h colspan
+ *
+ * Modifies the position of an object already in the table.
+ *
+ * @note All positioning inside the table is relative to rows and columns, so
+ * a value of 0 for x and y, means the top left cell of the table, and a
+ * value of 1 for w and h means @p subobj only takes that 1 cell.
+ */
+ EAPI void elm_table_pack_set(Evas_Object *subobj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the packing location of an existing child of the table
+ *
+ * @param subobj The subobject to be modified in the table
+ * @param x Row number
+ * @param y Column number
+ * @param w rowspan
+ * @param h colspan
+ *
+ * @see elm_table_pack_set()
+ */
+ EAPI void elm_table_pack_get(Evas_Object *subobj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Gengrid Gengrid (Generic grid)
+ *
+ * This widget aims to position objects in a grid layout while
+ * actually creating and rendering only the visible ones, using the
+ * same idea as the @ref Genlist "genlist": the user defines a @b
+ * class for each item, specifying functions that will be called at
+ * object creation, deletion, etc. When those items are selected by
+ * the user, a callback function is issued. Users may interact with
+ * a gengrid via the mouse (by clicking on items to select them and
+ * clicking on the grid's viewport and swiping to pan the whole
+ * view) or via the keyboard, navigating through item with the
+ * arrow keys.
+ *
+ * @section Gengrid_Layouts Gengrid layouts
+ *
+ * Gengrids may layout its items in one of two possible layouts:
+ * - horizontal or
+ * - vertical.
+ *
+ * When in "horizontal mode", items will be placed in @b columns,
+ * from top to bottom and, when the space for a column is filled,
* another one is started on the right, thus expanding the grid
* horizontally, making for horizontal scrolling. When in "vertical
* mode" , though, items will be placed in @b rows, from left to
* started below, thus expanding the grid vertically (and making
* for vertical scrolling).
*
- * @section Gengrid_Items Gengrid items
+ * @section Gengrid_Items Gengrid items
+ *
+ * An item in a gengrid can have 0 or more text labels (they can be
+ * regular text or textblock Evas objects - that's up to the style
+ * to determine), 0 or more icons (which are simply objects
+ * swallowed into the gengrid item's theming Edje object) and 0 or
+ * more <b>boolean states</b>, which have the behavior left to the
+ * user to define. The Edje part names for each of these properties
+ * will be looked up, in the theme file for the gengrid, under the
+ * Edje (string) data items named @c "labels", @c "icons" and @c
+ * "states", respectively. For each of those properties, if more
+ * than one part is provided, they must have names listed separated
+ * by spaces in the data fields. For the default gengrid item
+ * theme, we have @b one label part (@c "elm.text"), @b two icon
+ * parts (@c "elm.swalllow.icon" and @c "elm.swallow.end") and @b
+ * no state parts.
+ *
+ * A gengrid item may be at one of several styles. Elementary
+ * provides one by default - "default", but this can be extended by
+ * system or application custom themes/overlays/extensions (see
+ * @ref Theme "themes" for more details).
+ *
+ * @section Gengrid_Item_Class Gengrid item classes
+ *
+ * In order to have the ability to add and delete items on the fly,
+ * gengrid implements a class (callback) system where the
+ * application provides a structure with information about that
+ * type of item (gengrid may contain multiple different items with
+ * different classes, states and styles). Gengrid will call the
+ * functions in this struct (methods) when an item is "realized"
+ * (i.e., created dynamically, while the user is scrolling the
+ * grid). All objects will simply be deleted when no longer needed
+ * with evas_object_del(). The #Elm_GenGrid_Item_Class structure
+ * contains the following members:
+ * - @c item_style - This is a constant string and simply defines
+ * the name of the item style. It @b must be specified and the
+ * default should be @c "default".
+ * - @c func.label_get - This function is called when an item
+ * object is actually created. The @c data parameter will point to
+ * the same data passed to elm_gengrid_item_append() and related
+ * item creation functions. The @c obj parameter is the gengrid
+ * object itself, while the @c part one is the name string of one
+ * of the existing text parts in the Edje group implementing the
+ * item's theme. This function @b must return a strdup'()ed string,
+ * as the caller will free() it when done. See
+ * #Elm_Gengrid_Item_Label_Get_Cb.
+ * - @c func.icon_get - This function is called when an item object
+ * is actually created. The @c data parameter will point to the
+ * same data passed to elm_gengrid_item_append() and related item
+ * creation functions. The @c obj parameter is the gengrid object
+ * itself, while the @c part one is the name string of one of the
+ * existing (icon) swallow parts in the Edje group implementing the
+ * item's theme. It must return @c NULL, when no icon is desired,
+ * or a valid object handle, otherwise. The object will be deleted
+ * by the gengrid on its deletion or when the item is "unrealized".
+ * See #Elm_Gengrid_Item_Icon_Get_Cb.
+ * - @c func.state_get - This function is called when an item
+ * object is actually created. The @c data parameter will point to
+ * the same data passed to elm_gengrid_item_append() and related
+ * item creation functions. The @c obj parameter is the gengrid
+ * object itself, while the @c part one is the name string of one
+ * of the state parts in the Edje group implementing the item's
+ * theme. Return @c EINA_FALSE for false/off or @c EINA_TRUE for
+ * true/on. Gengrids will emit a signal to its theming Edje object
+ * with @c "elm,state,XXX,active" and @c "elm" as "emission" and
+ * "source" arguments, respectively, when the state is true (the
+ * default is false), where @c XXX is the name of the (state) part.
+ * See #Elm_Gengrid_Item_State_Get_Cb.
+ * - @c func.del - This is called when elm_gengrid_item_del() is
+ * called on an item or elm_gengrid_clear() is called on the
+ * gengrid. This is intended for use when gengrid items are
+ * deleted, so any data attached to the item (e.g. its data
+ * parameter on creation) can be deleted. See #Elm_Gengrid_Item_Del_Cb.
+ *
+ * @section Gengrid_Usage_Hints Usage hints
+ *
+ * If the user wants to have multiple items selected at the same
+ * time, elm_gengrid_multi_select_set() will permit it. If the
+ * gengrid is single-selection only (the default), then
+ * elm_gengrid_select_item_get() will return the selected item or
+ * @c NULL, if none is selected. If the gengrid is under
+ * multi-selection, then elm_gengrid_selected_items_get() will
+ * return a list (that is only valid as long as no items are
+ * modified (added, deleted, selected or unselected) of child items
+ * on a gengrid.
+ *
+ * If an item changes (internal (boolean) state, label or icon
+ * changes), then use elm_gengrid_item_update() to have gengrid
+ * update the item with the new state. A gengrid will re-"realize"
+ * the item, thus calling the functions in the
+ * #Elm_Gengrid_Item_Class set for that item.
+ *
+ * To programmatically (un)select an item, use
+ * elm_gengrid_item_selected_set(). To get its selected state use
+ * elm_gengrid_item_selected_get(). To make an item disabled
+ * (unable to be selected and appear differently) use
+ * elm_gengrid_item_disabled_set() to set this and
+ * elm_gengrid_item_disabled_get() to get the disabled state.
+ *
+ * Grid cells will only have their selection smart callbacks called
+ * when firstly getting selected. Any further clicks will do
+ * nothing, unless you enable the "always select mode", with
+ * elm_gengrid_always_select_mode_set(), thus making every click to
+ * issue selection callbacks. elm_gengrid_no_select_mode_set() will
+ * turn off the ability to select items entirely in the widget and
+ * they will neither appear selected nor call the selection smart
+ * callbacks.
+ *
+ * Remember that you can create new styles and add your own theme
+ * augmentation per application with elm_theme_extension_add(). If
+ * you absolutely must have a specific style that overrides any
+ * theme the user or system sets up you can use
+ * elm_theme_overlay_add() to add such a file.
+ *
+ * @section Gengrid_Smart_Events Gengrid smart events
+ *
+ * Smart events that you can add callbacks for are:
+ * - @c "activated" - The user has double-clicked or pressed
+ * (enter|return|spacebar) on an item. The @c event_info parameter
+ * is the gengrid item that was activated.
+ * - @c "clicked,double" - The user has double-clicked an item.
+ * The @c event_info parameter is the gengrid item that was double-clicked.
+ * - @c "longpressed" - This is called when the item is pressed for a certain
+ * amount of time. By default it's 1 second.
+ * - @c "selected" - The user has made an item selected. The
+ * @c event_info parameter is the gengrid item that was selected.
+ * - @c "unselected" - The user has made an item unselected. The
+ * @c event_info parameter is the gengrid item that was unselected.
+ * - @c "realized" - This is called when the item in the gengrid
+ * has its implementing Evas object instantiated, de facto. @c
+ * event_info is the gengrid item that was created. The object
+ * may be deleted at any time, so it is highly advised to the
+ * caller @b not to use the object pointer returned from
+ * elm_gengrid_item_object_get(), because it may point to freed
+ * objects.
+ * - @c "unrealized" - This is called when the implementing Evas
+ * object for this item is deleted. @c event_info is the gengrid
+ * item that was deleted.
+ * - @c "changed" - Called when an item is added, removed, resized
+ * or moved and when the gengrid is resized or gets "horizontal"
+ * property changes.
+ * - @c "scroll,anim,start" - This is called when scrolling animation has
+ * started.
+ * - @c "scroll,anim,stop" - This is called when scrolling animation has
+ * stopped.
+ * - @c "drag,start,up" - Called when the item in the gengrid has
+ * been dragged (not scrolled) up.
+ * - @c "drag,start,down" - Called when the item in the gengrid has
+ * been dragged (not scrolled) down.
+ * - @c "drag,start,left" - Called when the item in the gengrid has
+ * been dragged (not scrolled) left.
+ * - @c "drag,start,right" - Called when the item in the gengrid has
+ * been dragged (not scrolled) right.
+ * - @c "drag,stop" - Called when the item in the gengrid has
+ * stopped being dragged.
+ * - @c "drag" - Called when the item in the gengrid is being
+ * dragged.
+ * - @c "scroll" - called when the content has been scrolled
+ * (moved).
+ * - @c "scroll,drag,start" - called when dragging the content has
+ * started.
+ * - @c "scroll,drag,stop" - called when dragging the content has
+ * stopped.
+ * - @c "scroll,edge,top" - This is called when the gengrid is scrolled until
+ * the top edge.
+ * - @c "scroll,edge,bottom" - This is called when the gengrid is scrolled
+ * until the bottom edge.
+ * - @c "scroll,edge,left" - This is called when the gengrid is scrolled
+ * until the left edge.
+ * - @c "scroll,edge,right" - This is called when the gengrid is scrolled
+ * until the right edge.
+ *
+ * List of gengrid examples:
+ * @li @ref gengrid_example
+ */
+
+ /**
+ * @addtogroup Gengrid
+ * @{
+ */
+
+ typedef struct _Elm_Gengrid_Item_Class Elm_Gengrid_Item_Class; /**< Gengrid item class definition structs */
+ typedef struct _Elm_Gengrid_Item_Class_Func Elm_Gengrid_Item_Class_Func; /**< Class functions for gengrid item classes. */
+ typedef struct _Elm_Gengrid_Item Elm_Gengrid_Item; /**< Gengrid item handles */
+ typedef char *(*Elm_Gengrid_Item_Label_Get_Cb) (void *data, Evas_Object *obj, const char *part); /**< Label fetching class function for gengrid item classes. */
+ typedef Evas_Object *(*Elm_Gengrid_Item_Icon_Get_Cb) (void *data, Evas_Object *obj, const char *part); /**< Icon fetching class function for gengrid item classes. */
+ typedef Eina_Bool (*Elm_Gengrid_Item_State_Get_Cb) (void *data, Evas_Object *obj, const char *part); /**< State fetching class function for gengrid item classes. */
+ typedef void (*Elm_Gengrid_Item_Del_Cb) (void *data, Evas_Object *obj); /**< Deletion class function for gengrid item classes. */
+
+ typedef char *(*GridItemLabelGetFunc) (void *data, Evas_Object *obj, const char *part) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Gengrid_Item_Label_Get_Cb. */
+ typedef Evas_Object *(*GridItemIconGetFunc) (void *data, Evas_Object *obj, const char *part) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Gengrid_Item_Icon_Get_Cb. */
+ typedef Eina_Bool (*GridItemStateGetFunc) (void *data, Evas_Object *obj, const char *part) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Gengrid_Item_State_Get_Cb. */
+ typedef void (*GridItemDelFunc) (void *data, Evas_Object *obj) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Gengrid_Item_Del_Cb. */
+
+ /**
+ * @struct _Elm_Gengrid_Item_Class
+ *
+ * Gengrid item class definition. See @ref Gengrid_Item_Class for
+ * field details.
+ */
+ struct _Elm_Gengrid_Item_Class
+ {
+ const char *item_style;
+ struct _Elm_Gengrid_Item_Class_Func
+ {
+ Elm_Gengrid_Item_Label_Get_Cb label_get;
+ Elm_Gengrid_Item_Icon_Get_Cb icon_get;
+ Elm_Gengrid_Item_State_Get_Cb state_get;
+ Elm_Gengrid_Item_Del_Cb del;
+ } func;
+ }; /**< #Elm_Gengrid_Item_Class member definitions */
+
+ /**
+ * Add a new gengrid widget to the given parent Elementary
+ * (container) object
+ *
+ * @param parent The parent object
+ * @return a new gengrid widget handle or @c NULL, on errors
+ *
+ * This function inserts a new gengrid widget on the canvas.
+ *
+ * @see elm_gengrid_item_size_set()
+ * @see elm_gengrid_group_item_size_set()
+ * @see elm_gengrid_horizontal_set()
+ * @see elm_gengrid_item_append()
+ * @see elm_gengrid_item_del()
+ * @see elm_gengrid_clear()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Evas_Object *elm_gengrid_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the size for the items of a given gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param w The items' width.
+ * @param h The items' height;
+ *
+ * A gengrid, after creation, has still no information on the size
+ * to give to each of its cells. So, you most probably will end up
+ * with squares one @ref Fingers "finger" wide, the default
+ * size. Use this function to force a custom size for you items,
+ * making them as big as you wish.
+ *
+ * @see elm_gengrid_item_size_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_item_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the size set for the items of a given gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param w Pointer to a variable where to store the items' width.
+ * @param h Pointer to a variable where to store the items' height.
+ *
+ * @note Use @c NULL pointers on the size values you're not
+ * interested in: they'll be ignored by the function.
+ *
+ * @see elm_gengrid_item_size_get() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_item_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the size for the group items of a given gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param w The group items' width.
+ * @param h The group items' height;
+ *
+ * A gengrid, after creation, has still no information on the size
+ * to give to each of its cells. So, you most probably will end up
+ * with squares one @ref Fingers "finger" wide, the default
+ * size. Use this function to force a custom size for you group items,
+ * making them as big as you wish.
+ *
+ * @see elm_gengrid_group_item_size_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_group_item_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the size set for the group items of a given gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param w Pointer to a variable where to store the group items' width.
+ * @param h Pointer to a variable where to store the group items' height.
+ *
+ * @note Use @c NULL pointers on the size values you're not
+ * interested in: they'll be ignored by the function.
+ *
+ * @see elm_gengrid_group_item_size_get() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_group_item_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the items grid's alignment within a given gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param align_x Alignment in the horizontal axis (0 <= align_x <= 1).
+ * @param align_y Alignment in the vertical axis (0 <= align_y <= 1).
+ *
+ * This sets the alignment of the whole grid of items of a gengrid
+ * within its given viewport. By default, those values are both
+ * 0.5, meaning that the gengrid will have its items grid placed
+ * exactly in the middle of its viewport.
+ *
+ * @note If given alignment values are out of the cited ranges,
+ * they'll be changed to the nearest boundary values on the valid
+ * ranges.
+ *
+ * @see elm_gengrid_align_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_align_set(Evas_Object *obj, double align_x, double align_y) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the items grid's alignment values within a given gengrid
+ * widget
+ *
+ * @param obj The gengrid object.
+ * @param align_x Pointer to a variable where to store the
+ * horizontal alignment.
+ * @param align_y Pointer to a variable where to store the vertical
+ * alignment.
+ *
+ * @note Use @c NULL pointers on the alignment values you're not
+ * interested in: they'll be ignored by the function.
+ *
+ * @see elm_gengrid_align_set() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_align_get(const Evas_Object *obj, double *align_x, double *align_y) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given gengrid widget is or not able have items
+ * @b reordered
+ *
+ * @param obj The gengrid object
+ * @param reorder_mode Use @c EINA_TRUE to turn reoderding on,
+ * @c EINA_FALSE to turn it off
+ *
+ * If a gengrid is set to allow reordering, a click held for more
+ * than 0.5 over a given item will highlight it specially,
+ * signalling the gengrid has entered the reordering state. From
+ * that time on, the user will be able to, while still holding the
+ * mouse button down, move the item freely in the gengrid's
+ * viewport, replacing to said item to the locations it goes to.
+ * The replacements will be animated and, whenever the user
+ * releases the mouse button, the item being replaced gets a new
+ * definitive place in the grid.
+ *
+ * @see elm_gengrid_reorder_mode_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given gengrid widget is or not able have items
+ * @b reordered
+ *
+ * @param obj The gengrid object
+ * @return @c EINA_TRUE, if reoderding is on, @c EINA_FALSE if it's
+ * off
+ *
+ * @see elm_gengrid_reorder_mode_set() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Eina_Bool elm_gengrid_reorder_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Append a new item in a given gengrid widget.
+ *
+ * @param obj The gengrid object.
+ * @param gic The item class for the item.
+ * @param data The item data.
+ * @param func Convenience function called when the item is
+ * selected.
+ * @param func_data Data to be passed to @p func.
+ * @return A handle to the item added or @c NULL, on errors.
+ *
+ * This adds an item to the beginning of the gengrid.
+ *
+ * @see elm_gengrid_item_prepend()
+ * @see elm_gengrid_item_insert_before()
+ * @see elm_gengrid_item_insert_after()
+ * @see elm_gengrid_item_del()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_append(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+
+ /**
+ * Prepend a new item in a given gengrid widget.
+ *
+ * @param obj The gengrid object.
+ * @param gic The item class for the item.
+ * @param data The item data.
+ * @param func Convenience function called when the item is
+ * selected.
+ * @param func_data Data to be passed to @p func.
+ * @return A handle to the item added or @c NULL, on errors.
+ *
+ * This adds an item to the end of the gengrid.
+ *
+ * @see elm_gengrid_item_append()
+ * @see elm_gengrid_item_insert_before()
+ * @see elm_gengrid_item_insert_after()
+ * @see elm_gengrid_item_del()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_prepend(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+
+ /**
+ * Insert an item before another in a gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param gic The item class for the item.
+ * @param data The item data.
+ * @param relative The item to place this new one before.
+ * @param func Convenience function called when the item is
+ * selected.
+ * @param func_data Data to be passed to @p func.
+ * @return A handle to the item added or @c NULL, on errors.
+ *
+ * This inserts an item before another in the gengrid.
+ *
+ * @see elm_gengrid_item_append()
+ * @see elm_gengrid_item_prepend()
+ * @see elm_gengrid_item_insert_after()
+ * @see elm_gengrid_item_del()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_insert_before(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Elm_Gengrid_Item *relative, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+
+ /**
+ * Insert an item after another in a gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param gic The item class for the item.
+ * @param data The item data.
+ * @param relative The item to place this new one after.
+ * @param func Convenience function called when the item is
+ * selected.
+ * @param func_data Data to be passed to @p func.
+ * @return A handle to the item added or @c NULL, on errors.
+ *
+ * This inserts an item after another in the gengrid.
+ *
+ * @see elm_gengrid_item_append()
+ * @see elm_gengrid_item_prepend()
+ * @see elm_gengrid_item_insert_after()
+ * @see elm_gengrid_item_del()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_insert_after(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Elm_Gengrid_Item *relative, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_sorted_insert(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_direct_sorted_insert(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data);
+
+ /**
+ * Set whether items on a given gengrid widget are to get their
+ * selection callbacks issued for @b every subsequent selection
+ * click on them or just for the first click.
+ *
+ * @param obj The gengrid object
+ * @param always_select @c EINA_TRUE to make items "always
+ * selected", @c EINA_FALSE, otherwise
+ *
+ * By default, grid items will only call their selection callback
+ * function when firstly getting selected, any subsequent further
+ * clicks will do nothing. With this call, you make those
+ * subsequent clicks also to issue the selection callbacks.
+ *
+ * @note <b>Double clicks</b> will @b always be reported on items.
+ *
+ * @see elm_gengrid_always_select_mode_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether items on a given gengrid widget have their selection
+ * callbacks issued for @b every subsequent selection click on them
+ * or just for the first click.
+ *
+ * @param obj The gengrid object.
+ * @return @c EINA_TRUE if the gengrid items are "always selected",
+ * @c EINA_FALSE, otherwise
+ *
+ * @see elm_gengrid_always_select_mode_set() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Eina_Bool elm_gengrid_always_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether items on a given gengrid widget can be selected or not.
+ *
+ * @param obj The gengrid object
+ * @param no_select @c EINA_TRUE to make items selectable,
+ * @c EINA_FALSE otherwise
+ *
+ * This will make items in @p obj selectable or not. In the latter
+ * case, any user interaction on the gengrid items will neither make
+ * them appear selected nor them call their selection callback
+ * functions.
+ *
+ * @see elm_gengrid_no_select_mode_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_no_select_mode_set(Evas_Object *obj, Eina_Bool no_select) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether items on a given gengrid widget can be selected or
+ * not.
+ *
+ * @param obj The gengrid object
+ * @return @c EINA_TRUE, if items are selectable, @c EINA_FALSE
+ * otherwise
+ *
+ * @see elm_gengrid_no_select_mode_set() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Eina_Bool elm_gengrid_no_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable or disable multi-selection in a given gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @param multi @c EINA_TRUE, to enable multi-selection,
+ * @c EINA_FALSE to disable it.
+ *
+ * Multi-selection is the ability for one to have @b more than one
+ * item selected, on a given gengrid, simultaneously. When it is
+ * enabled, a sequence of clicks on different items will make them
+ * all selected, progressively. A click on an already selected item
+ * will unselect it. If interecting via the keyboard,
+ * multi-selection is enabled while holding the "Shift" key.
+ *
+ * @note By default, multi-selection is @b disabled on gengrids
+ *
+ * @see elm_gengrid_multi_select_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_multi_select_set(Evas_Object *obj, Eina_Bool multi) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether multi-selection is enabled or disabled for a given
+ * gengrid widget
+ *
+ * @param obj The gengrid object.
+ * @return @c EINA_TRUE, if multi-selection is enabled, @c
+ * EINA_FALSE otherwise
+ *
+ * @see elm_gengrid_multi_select_set() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Eina_Bool elm_gengrid_multi_select_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable or disable bouncing effect for a given gengrid widget
+ *
+ * @param obj The gengrid object
+ * @param h_bounce @c EINA_TRUE, to enable @b horizontal bouncing,
+ * @c EINA_FALSE to disable it
+ * @param v_bounce @c EINA_TRUE, to enable @b vertical bouncing,
+ * @c EINA_FALSE to disable it
+ *
+ * The bouncing effect occurs whenever one reaches the gengrid's
+ * edge's while panning it -- it will scroll past its limits a
+ * little bit and return to the edge again, in a animated for,
+ * automatically.
+ *
+ * @note By default, gengrids have bouncing enabled on both axis
+ *
+ * @see elm_gengrid_bounce_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether bouncing effects are enabled or disabled, for a
+ * given gengrid widget, on each axis
+ *
+ * @param obj The gengrid object
+ * @param h_bounce Pointer to a variable where to store the
+ * horizontal bouncing flag.
+ * @param v_bounce Pointer to a variable where to store the
+ * vertical bouncing flag.
+ *
+ * @see elm_gengrid_bounce_set() for more details
*
- * An item in a gengrid can have 0 or more text labels (they can be
- * regular text or textblock Evas objects - that's up to the style
- * to determine), 0 or more icons (which are simply objects
- * swallowed into the gengrid item's theming Edje object) and 0 or
- * more <b>boolean states</b>, which have the behavior left to the
- * user to define. The Edje part names for each of these properties
- * will be looked up, in the theme file for the gengrid, under the
- * Edje (string) data items named @c "labels", @c "icons" and @c
- * "states", respectively. For each of those properties, if more
- * than one part is provided, they must have names listed separated
- * by spaces in the data fields. For the default gengrid item
- * theme, we have @b one label part (@c "elm.text"), @b two icon
- * parts (@c "elm.swalllow.icon" and @c "elm.swallow.end") and @b
- * no state parts.
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set a given gengrid widget's scrolling page size, relative to
+ * its viewport size.
+ *
+ * @param obj The gengrid object
+ * @param h_pagerel The horizontal page (relative) size
+ * @param v_pagerel The vertical page (relative) size
+ *
+ * The gengrid's scroller is capable of binding scrolling by the
+ * user to "pages". It means that, while scrolling and, specially
+ * after releasing the mouse button, the grid will @b snap to the
+ * nearest displaying page's area. When page sizes are set, the
+ * grid's continuous content area is split into (equal) page sized
+ * pieces.
+ *
+ * This function sets the size of a page <b>relatively to the
+ * viewport dimensions</b> of the gengrid, for each axis. A value
+ * @c 1.0 means "the exact viewport's size", in that axis, while @c
+ * 0.0 turns paging off in that axis. Likewise, @c 0.5 means "half
+ * a viewport". Sane usable values are, than, between @c 0.0 and @c
+ * 1.0. Values beyond those will make it behave behave
+ * inconsistently. If you only want one axis to snap to pages, use
+ * the value @c 0.0 for the other one.
+ *
+ * There is a function setting page size values in @b absolute
+ * values, too -- elm_gengrid_page_size_set(). Naturally, its use
+ * is mutually exclusive to this one.
+ *
+ * @see elm_gengrid_page_relative_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get a given gengrid widget's scrolling page size, relative to
+ * its viewport size.
+ *
+ * @param obj The gengrid object
+ * @param h_pagerel Pointer to a variable where to store the
+ * horizontal page (relative) size
+ * @param v_pagerel Pointer to a variable where to store the
+ * vertical page (relative) size
+ *
+ * @see elm_gengrid_page_relative_set() for more details
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_page_relative_get(const Evas_Object *obj, double *h_pagerel, double *v_pagerel) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set a given gengrid widget's scrolling page size
+ *
+ * @param obj The gengrid object
+ * @param h_pagerel The horizontal page size, in pixels
+ * @param v_pagerel The vertical page size, in pixels
+ *
+ * The gengrid's scroller is capable of binding scrolling by the
+ * user to "pages". It means that, while scrolling and, specially
+ * after releasing the mouse button, the grid will @b snap to the
+ * nearest displaying page's area. When page sizes are set, the
+ * grid's continuous content area is split into (equal) page sized
+ * pieces.
+ *
+ * This function sets the size of a page of the gengrid, in pixels,
+ * for each axis. Sane usable values are, between @c 0 and the
+ * dimensions of @p obj, for each axis. Values beyond those will
+ * make it behave behave inconsistently. If you only want one axis
+ * to snap to pages, use the value @c 0 for the other one.
+ *
+ * There is a function setting page size values in @b relative
+ * values, too -- elm_gengrid_page_relative_set(). Naturally, its
+ * use is mutually exclusive to this one.
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize) EINA_ARG_NONNULL(1);
+
+ /**
+ * @brief Get gengrid current page number.
+ *
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * The page number starts from 0. 0 is the first page.
+ * Current page means the page which meet the top-left of the viewport.
+ * If there are two or more pages in the viewport, it returns the number of page
+ * which meet the top-left of the viewport.
+ *
+ * @see elm_gengrid_last_page_get()
+ * @see elm_gengrid_page_show()
+ * @see elm_gengrid_page_brint_in()
+ */
+ EAPI void elm_gengrid_current_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber) EINA_ARG_NONNULL(1);
+
+ /**
+ * @brief Get scroll last page number.
+ *
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * The page number starts from 0. 0 is the first page.
+ * This returns the last page number among the pages.
+ *
+ * @see elm_gengrid_current_page_get()
+ * @see elm_gengrid_page_show()
+ * @see elm_gengrid_page_brint_in()
+ */
+ EAPI void elm_gengrid_last_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber) EINA_ARG_NONNULL(1);
+
+ /**
+ * Show a specific virtual region within the gengrid content object by page number.
+ *
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * 0, 0 of the indicated page is located at the top-left of the viewport.
+ * This will jump to the page directly without animation.
+ *
+ * Example of usage:
+ *
+ * @code
+ * sc = elm_gengrid_add(win);
+ * elm_gengrid_content_set(sc, content);
+ * elm_gengrid_page_relative_set(sc, 1, 0);
+ * elm_gengrid_current_page_get(sc, &h_page, &v_page);
+ * elm_gengrid_page_show(sc, h_page + 1, v_page);
+ * @endcode
+ *
+ * @see elm_gengrid_page_bring_in()
+ */
+ EAPI void elm_gengrid_page_show(const Evas_Object *obj, int h_pagenumber, int v_pagenumber) EINA_ARG_NONNULL(1);
+
+ /**
+ * Show a specific virtual region within the gengrid content object by page number.
+ *
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
+ *
+ * 0, 0 of the indicated page is located at the top-left of the viewport.
+ * This will slide to the page with animation.
+ *
+ * Example of usage:
+ *
+ * @code
+ * sc = elm_gengrid_add(win);
+ * elm_gengrid_content_set(sc, content);
+ * elm_gengrid_page_relative_set(sc, 1, 0);
+ * elm_gengrid_last_page_get(sc, &h_page, &v_page);
+ * elm_gengrid_page_bring_in(sc, h_page, v_page);
+ * @endcode
+ *
+ * @see elm_gengrid_page_show()
+ */
+ EAPI void elm_gengrid_page_bring_in(const Evas_Object *obj, int h_pagenumber, int v_pagenumber) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set for what direction a given gengrid widget will expand while
+ * placing its items.
+ *
+ * @param obj The gengrid object.
+ * @param setting @c EINA_TRUE to make the gengrid expand
+ * horizontally, @c EINA_FALSE to expand vertically.
+ *
+ * When in "horizontal mode" (@c EINA_TRUE), items will be placed
+ * in @b columns, from top to bottom and, when the space for a
+ * column is filled, another one is started on the right, thus
+ * expanding the grid horizontally. When in "vertical mode"
+ * (@c EINA_FALSE), though, items will be placed in @b rows, from left
+ * to right and, when the space for a row is filled, another one is
+ * started below, thus expanding the grid vertically.
+ *
+ * @see elm_gengrid_horizontal_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_horizontal_set(Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get for what direction a given gengrid widget will expand while
+ * placing its items.
+ *
+ * @param obj The gengrid object.
+ * @return @c EINA_TRUE, if @p obj is set to expand horizontally,
+ * @c EINA_FALSE if it's set to expand vertically.
+ *
+ * @see elm_gengrid_horizontal_set() for more detais
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Eina_Bool elm_gengrid_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the first item in a given gengrid widget
+ *
+ * @param obj The gengrid object
+ * @return The first item's handle or @c NULL, if there are no
+ * items in @p obj (and on errors)
+ *
+ * This returns the first item in the @p obj's internal list of
+ * items.
+ *
+ * @see elm_gengrid_last_item_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the last item in a given gengrid widget
+ *
+ * @param obj The gengrid object
+ * @return The last item's handle or @c NULL, if there are no
+ * items in @p obj (and on errors)
+ *
+ * This returns the last item in the @p obj's internal list of
+ * items.
+ *
+ * @see elm_gengrid_first_item_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the @b next item in a gengrid widget's internal list of items,
+ * given a handle to one of those items.
+ *
+ * @param item The gengrid item to fetch next from
+ * @return The item after @p item, or @c NULL if there's none (and
+ * on errors)
+ *
+ * This returns the item placed after the @p item, on the container
+ * gengrid.
+ *
+ * @see elm_gengrid_item_prev_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_next_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the @b previous item in a gengrid widget's internal list of items,
+ * given a handle to one of those items.
+ *
+ * @param item The gengrid item to fetch previous from
+ * @return The item before @p item, or @c NULL if there's none (and
+ * on errors)
+ *
+ * This returns the item placed before the @p item, on the container
+ * gengrid.
+ *
+ * @see elm_gengrid_item_next_get()
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Elm_Gengrid_Item *elm_gengrid_item_prev_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the gengrid object's handle which contains a given gengrid
+ * item
+ *
+ * @param item The item to fetch the container from
+ * @return The gengrid (parent) object
+ *
+ * This returns the gengrid object itself that an item belongs to.
+ *
+ * @ingroup Gengrid
+ */
+ EAPI Evas_Object *elm_gengrid_item_gengrid_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Remove a gengrid item from the its parent, deleting it.
+ *
+ * @param item The item to be removed.
+ * @return @c EINA_TRUE on success or @c EINA_FALSE, otherwise.
*
- * A gengrid item may be at one of several styles. Elementary
- * provides one by default - "default", but this can be extended by
- * system or application custom themes/overlays/extensions (see
- * @ref Theme "themes" for more details).
+ * @see elm_gengrid_clear(), to remove all items in a gengrid at
+ * once.
*
- * @section Gengrid_Item_Class Gengrid item classes
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_item_del(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Update the contents of a given gengrid item
*
- * In order to have the ability to add and delete items on the fly,
- * gengrid implements a class (callback) system where the
- * application provides a structure with information about that
- * type of item (gengrid may contain multiple different items with
- * different classes, states and styles). Gengrid will call the
- * functions in this struct (methods) when an item is "realized"
- * (i.e., created dynamically, while the user is scrolling the
- * grid). All objects will simply be deleted when no longer needed
- * with evas_object_del(). The #Elm_GenGrid_Item_Class structure
- * contains the following members:
- * - @c item_style - This is a constant string and simply defines
- * the name of the item style. It @b must be specified and the
- * default should be @c "default".
- * - @c func.label_get - This function is called when an item
- * object is actually created. The @c data parameter will point to
- * the same data passed to elm_gengrid_item_append() and related
- * item creation functions. The @c obj parameter is the gengrid
- * object itself, while the @c part one is the name string of one
- * of the existing text parts in the Edje group implementing the
- * item's theme. This function @b must return a strdup'()ed string,
- * as the caller will free() it when done. See
- * #GridItemLabelGetFunc.
- * - @c func.icon_get - This function is called when an item object
- * is actually created. The @c data parameter will point to the
- * same data passed to elm_gengrid_item_append() and related item
- * creation functions. The @c obj parameter is the gengrid object
- * itself, while the @c part one is the name string of one of the
- * existing (icon) swallow parts in the Edje group implementing the
- * item's theme. It must return @c NULL, when no icon is desired,
- * or a valid object handle, otherwise. The object will be deleted
- * by the gengrid on its deletion or when the item is "unrealized".
- * See #GridItemIconGetFunc.
- * - @c func.state_get - This function is called when an item
- * object is actually created. The @c data parameter will point to
- * the same data passed to elm_gengrid_item_append() and related
- * item creation functions. The @c obj parameter is the gengrid
- * object itself, while the @c part one is the name string of one
- * of the state parts in the Edje group implementing the item's
- * theme. Return @c EINA_FALSE for false/off or @c EINA_TRUE for
- * true/on. Gengrids will emit a signal to its theming Edje object
- * with @c "elm,state,XXX,active" and @c "elm" as "emission" and
- * "source" arguments, respectively, when the state is true (the
- * default is false), where @c XXX is the name of the (state) part.
- * See #GridItemStateGetFunc.
- * - @c func.del - This is called when elm_gengrid_item_del() is
- * called on an item or elm_gengrid_clear() is called on the
- * gengrid. This is intended for use when gengrid items are
- * deleted, so any data attached to the item (e.g. its data
- * parameter on creation) can be deleted. See #GridItemDelFunc.
+ * @param item The gengrid item
*
- * @section Gengrid_Usage_Hints Usage hints
+ * This updates an item by calling all the item class functions
+ * again to get the icons, labels and states. Use this when the
+ * original item data has changed and you want thta changes to be
+ * reflected.
*
- * If the user wants to have multiple items selected at the same
- * time, elm_gengrid_multi_select_set() will permit it. If the
- * gengrid is single-selection only (the default), then
- * elm_gengrid_select_item_get() will return the selected item or
- * @c NULL, if none is selected. If the gengrid is under
- * multi-selection, then elm_gengrid_selected_items_get() will
- * return a list (that is only valid as long as no items are
- * modified (added, deleted, selected or unselected) of child items
- * on a gengrid.
+ * @ingroup Gengrid
+ */
+ EAPI void elm_gengrid_item_update(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI const Elm_Gengrid_Item_Class *elm_gengrid_item_item_class_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_item_class_set(Elm_Gengrid_Item *item, const Elm_Gengrid_Item_Class *gic) EINA_ARG_NONNULL(1, 2);
+
+ /**
+ * Return the data associated to a given gengrid item
*
- * If an item changes (internal (boolean) state, label or icon
- * changes), then use elm_gengrid_item_update() to have gengrid
- * update the item with the new state. A gengrid will re-"realize"
- * the item, thus calling the functions in the
- * #Elm_Gengrid_Item_Class set for that item.
+ * @param item The gengrid item.
+ * @return the data associated to this item.
*
- * To programmatically (un)select an item, use
- * elm_gengrid_item_selected_set(). To get its selected state use
- * elm_gengrid_item_selected_get(). To make an item disabled
- * (unable to be selected and appear differently) use
- * elm_gengrid_item_disabled_set() to set this and
- * elm_gengrid_item_disabled_get() to get the disabled state.
+ * This returns the @c data value passed on the
+ * elm_gengrid_item_append() and related item addition calls.
*
- * Grid cells will only have their selection smart callbacks called
- * when firstly getting selected. Any further clicks will do
- * nothing, unless you enable the "always select mode", with
- * elm_gengrid_always_select_mode_set(), thus making every click to
- * issue selection callbacks. elm_gengrid_no_select_mode_set() will
- * turn off the ability to select items entirely in the widget and
- * they will neither appear selected nor call the selection smart
- * callbacks.
+ * @see elm_gengrid_item_append()
+ * @see elm_gengrid_item_data_set()
*
- * Remember that you can create new styles and add your own theme
- * augmentation per application with elm_theme_extension_add(). If
- * you absolutely must have a specific style that overrides any
- * theme the user or system sets up you can use
- * elm_theme_overlay_add() to add such a file.
+ * @ingroup Gengrid
+ */
+ EAPI void *elm_gengrid_item_data_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the data associated to a given gengrid item
*
- * @section Gengrid_Smart_Events Gengrid smart events
+ * @param item The gengrid item
+ * @param data The new data pointer to set on it
*
- * Smart events that you can add callbacks for are:
- * - @c "activated" - The user has double-clicked or pressed
- * (enter|return|spacebar) on an item. The @c event_info parameter
- * is the gengrid item that was activated.
- * - @c "clicked,double" - The user has double-clicked an item.
- * The @c event_info parameter is the gengrid item that was double-clicked.
- * - @c "selected" - The user has made an item selected. The
- * @c event_info parameter is the gengrid item that was selected.
- * - @c "unselected" - The user has made an item unselected. The
- * @c event_info parameter is the gengrid item that was unselected.
- * - @c "realized" - This is called when the item in the gengrid
- * has its implementing Evas object instantiated, de facto. @c
- * event_info is the gengrid item that was created. The object
- * may be deleted at any time, so it is highly advised to the
- * caller @b not to use the object pointer returned from
- * elm_gengrid_item_object_get(), because it may point to freed
- * objects.
- * - @c "unrealized" - This is called when the implementing Evas
- * object for this item is deleted. @c event_info is the gengrid
- * item that was deleted.
- * - @c "changed" - Called when an item is added, removed, resized
- * or moved and when the gengrid is resized or gets "horizontal"
- * property changes.
- * - @c "drag,start,up" - Called when the item in the gengrid has
- * been dragged (not scrolled) up.
- * - @c "drag,start,down" - Called when the item in the gengrid has
- * been dragged (not scrolled) down.
- * - @c "drag,start,left" - Called when the item in the gengrid has
- * been dragged (not scrolled) left.
- * - @c "drag,start,right" - Called when the item in the gengrid has
- * been dragged (not scrolled) right.
- * - @c "drag,stop" - Called when the item in the gengrid has
- * stopped being dragged.
- * - @c "drag" - Called when the item in the gengrid is being
- * dragged.
- * - @c "scroll" - called when the content has been scrolled
- * (moved).
- * - @c "scroll,drag,start" - called when dragging the content has
- * started.
- * - @c "scroll,drag,stop" - called when dragging the content has
- * stopped.
+ * This @b overrides the @c data value passed on the
+ * elm_gengrid_item_append() and related item addition calls. This
+ * function @b won't call elm_gengrid_item_update() automatically,
+ * so you'd issue it afterwards if you want to hove the item
+ * updated to reflect the that new data.
*
- * List of gendrid examples:
- * @li @ref gengrid_example
+ * @see elm_gengrid_item_data_get()
+ *
+ * @ingroup Gengrid
*/
+ EAPI void elm_gengrid_item_data_set(Elm_Gengrid_Item *item, const void *data) EINA_ARG_NONNULL(1);
/**
- * @addtogroup Gengrid
- * @{
+ * Get a given gengrid item's position, relative to the whole
+ * gengrid's grid area.
+ *
+ * @param item The Gengrid item.
+ * @param x Pointer to variable where to store the item's <b>row
+ * number</b>.
+ * @param y Pointer to variable where to store the item's <b>column
+ * number</b>.
+ *
+ * This returns the "logical" position of the item whithin the
+ * gengrid. For example, @c (0, 1) would stand for first row,
+ * second column.
+ *
+ * @ingroup Gengrid
*/
-
- typedef struct _Elm_Gengrid_Item_Class Elm_Gengrid_Item_Class; /**< Gengrid item class definition structs */
- typedef struct _Elm_Gengrid_Item_Class_Func Elm_Gengrid_Item_Class_Func; /**< Class functions for gengrid item classes. */
- typedef struct _Elm_Gengrid_Item Elm_Gengrid_Item; /**< Gengrid item handles */
- typedef char *(*GridItemLabelGetFunc) (void *data, Evas_Object *obj, const char *part); /**< Label fetching class function for gengrid item classes. */
- typedef Evas_Object *(*GridItemIconGetFunc) (void *data, Evas_Object *obj, const char *part); /**< Icon fetching class function for gengrid item classes. */
- typedef Eina_Bool (*GridItemStateGetFunc) (void *data, Evas_Object *obj, const char *part); /**< State fetching class function for gengrid item classes. */
- typedef void (*GridItemDelFunc) (void *data, Evas_Object *obj); /**< Deletion class function for gengrid item classes. */
+ EAPI void elm_gengrid_item_pos_get(const Elm_Gengrid_Item *item, unsigned int *x, unsigned int *y) EINA_ARG_NONNULL(1);
/**
- * @struct _Elm_Gengrid_Item_Class
+ * Set whether a given gengrid item is selected or not
*
- * Gengrid item class definition. See @ref Gengrid_Item_Class for
- * field details.
+ * @param item The gengrid item
+ * @param selected Use @c EINA_TRUE, to make it selected, @c
+ * EINA_FALSE to make it unselected
+ *
+ * This sets the selected state of an item. If multi selection is
+ * not enabled on the containing gengrid and @p selected is @c
+ * EINA_TRUE, any other previously selected items will get
+ * unselected in favor of this new one.
+ *
+ * @see elm_gengrid_item_selected_get()
+ *
+ * @ingroup Gengrid
*/
- struct _Elm_Gengrid_Item_Class
- {
- const char *item_style;
- struct _Elm_Gengrid_Item_Class_Func
- {
- GridItemLabelGetFunc label_get;
- GridItemIconGetFunc icon_get;
- GridItemStateGetFunc state_get;
- GridItemDelFunc del;
- } func;
- }; /**< #Elm_Gengrid_Item_Class member definitions */
+ EAPI void elm_gengrid_item_selected_set(Elm_Gengrid_Item *item, Eina_Bool selected) EINA_ARG_NONNULL(1);
/**
- * Add a new gengrid widget to the given parent Elementary
- * (container) object
- *
- * @param parent The parent object
- * @return a new gengrid widget handle or @c NULL, on errors
+ * Get whether a given gengrid item is selected or not
*
- * This function inserts a new gengrid widget on the canvas.
+ * @param item The gengrid item
+ * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
*
- * @see elm_gengrid_item_size_set()
- * @see elm_gengrid_horizontal_set()
- * @see elm_gengrid_item_append()
- * @see elm_gengrid_item_del()
- * @see elm_gengrid_clear()
+ * @see elm_gengrid_item_selected_set() for more details
*
* @ingroup Gengrid
*/
- EAPI Evas_Object *elm_gengrid_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_gengrid_item_selected_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Set the size for the items of a given gengrid widget
+ * Get the real Evas object created to implement the view of a
+ * given gengrid item
*
- * @param obj The gengrid object.
- * @param w The items' width.
- * @param h The items' height;
+ * @param item The gengrid item.
+ * @return the Evas object implementing this item's view.
*
- * A gengrid, after creation, has still no information on the size
- * to give to each of its cells. So, you most probably will end up
- * with squares one @ref Fingers "finger" wide, the default
- * size. Use this function to force a custom size for you items,
- * making them as big as you wish.
+ * This returns the actual Evas object used to implement the
+ * specified gengrid item's view. This may be @c NULL, as it may
+ * not have been created or may have been deleted, at any time, by
+ * the gengrid. <b>Do not modify this object</b> (move, resize,
+ * show, hide, etc.), as the gengrid is controlling it. This
+ * function is for querying, emitting custom signals or hooking
+ * lower level callbacks for events on that object. Do not delete
+ * this object under any circumstances.
*
- * @see elm_gengrid_item_size_get()
+ * @see elm_gengrid_item_data_get()
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_item_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+ EAPI const Evas_Object *elm_gengrid_item_object_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Get the size set for the items of a given gengrid widget
+ * Show the portion of a gengrid's internal grid containing a given
+ * item, @b immediately.
*
- * @param obj The gengrid object.
- * @param w Pointer to a variable where to store the items' width.
- * @param h Pointer to a variable where to store the items' height.
+ * @param item The item to display
*
- * @note Use @c NULL pointers on the size values you're not
- * interested in: they'll be ignored by the function.
+ * This causes gengrid to @b redraw its viewport's contents to the
+ * region contining the given @p item item, if it is not fully
+ * visible.
*
- * @see elm_gengrid_item_size_get() for more details
+ * @see elm_gengrid_item_bring_in()
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_item_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_show(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Set the items grid's alignment within a given gengrid widget
- *
- * @param obj The gengrid object.
- * @param align_x Alignment in the horizontal axis (0 <= align_x <= 1).
- * @param align_y Alignment in the vertical axis (0 <= align_y <= 1).
+ * Animatedly bring in, to the visible are of a gengrid, a given
+ * item on it.
*
- * This sets the alignment of the whole grid of items of a gengrid
- * within its given viewport. By default, those values are both
- * 0.5, meaning that the gengrid will have its items grid placed
- * exactly in the middle of its viewport.
+ * @param item The gengrid item to display
*
- * @note If given alignment values are out of the cited ranges,
- * they'll be changed to the nearest boundary values on the valid
- * ranges.
+ * This causes gengrig to jump to the given @p item item and show
+ * it (by scrolling), if it is not fully visible. This will use
+ * animation to do so and take a period of time to complete.
*
- * @see elm_gengrid_align_get()
+ * @see elm_gengrid_item_show()
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_align_set(Evas_Object *obj, double align_x, double align_y) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_bring_in(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Get the items grid's alignment values within a given gengrid
- * widget
+ * Set whether a given gengrid item is disabled or not.
*
- * @param obj The gengrid object.
- * @param align_x Pointer to a variable where to store the
- * horizontal alignment.
- * @param align_y Pointer to a variable where to store the vertical
- * alignment.
+ * @param item The gengrid item
+ * @param disabled Use @c EINA_TRUE, true disable it, @c EINA_FALSE
+ * to enable it back.
*
- * @note Use @c NULL pointers on the alignment values you're not
- * interested in: they'll be ignored by the function.
+ * A disabled item cannot be selected or unselected. It will also
+ * change its appearance, to signal the user it's disabled.
*
- * @see elm_gengrid_align_set() for more details
+ * @see elm_gengrid_item_disabled_get()
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_align_get(const Evas_Object *obj, double *align_x, double *align_y) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_disabled_set(Elm_Gengrid_Item *item, Eina_Bool disabled) EINA_ARG_NONNULL(1);
/**
- * Set whether a given gengrid widget is or not able have items
- * @b reordered
- *
- * @param obj The gengrid object
- * @param reorder_mode Use @c EINA_TRUE to turn reoderding on,
- * @c EINA_FALSE to turn it off
+ * Get whether a given gengrid item is disabled or not.
*
- * If a gengrid is set to allow reordering, a click held for more
- * than 0.5 over a given item will highlight it specially,
- * signalling the gengrid has entered the reordering state. From
- * that time on, the user will be able to, while still holding the
- * mouse button down, move the item freely in the gengrid's
- * viewport, replacing to said item to the locations it goes to.
- * The replacements will be animated and, whenever the user
- * releases the mouse button, the item being replaced gets a new
- * definitive place in the grid.
+ * @param item The gengrid item
+ * @return @c EINA_TRUE, if it's disabled, @c EINA_FALSE otherwise
+ * (and on errors).
*
- * @see elm_gengrid_reorder_mode_get()
+ * @see elm_gengrid_item_disabled_set() for more details
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_gengrid_item_disabled_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Get whether a given gengrid widget is or not able have items
- * @b reordered
+ * Set the text to be shown in a given gengrid item's tooltips.
*
- * @param obj The gengrid object
- * @return @c EINA_TRUE, if reoderding is on, @c EINA_FALSE if it's
- * off
+ * @param item The gengrid item
+ * @param text The text to set in the content
*
- * @see elm_gengrid_reorder_mode_set() for more details
+ * This call will setup the text to be used as tooltip to that item
+ * (analogous to elm_object_tooltip_text_set(), but being item
+ * tooltips with higher precedence than object tooltips). It can
+ * have only one tooltip at a time, so any previous tooltip data
+ * will get removed.
*
* @ingroup Gengrid
*/
- EAPI Eina_Bool elm_gengrid_reorder_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_tooltip_text_set(Elm_Gengrid_Item *item, const char *text) EINA_ARG_NONNULL(1);
/**
- * Append a new item in a given gengrid widget.
- *
- * @param obj The gengrid object.
- * @param gic The item class for the item.
- * @param data The item data.
- * @param func Convenience function called when the item is
- * selected.
- * @param func_data Data to be passed to @p func.
- * @return A handle to the item added or @c NULL, on errors.
+ * Set the content to be shown in a given gengrid item's tooltips
*
- * This adds an item to the beginning of the gengrid.
+ * @param item The gengrid item.
+ * @param func The function returning the tooltip contents.
+ * @param data What to provide to @a func as callback data/context.
+ * @param del_cb Called when data is not needed anymore, either when
+ * another callback replaces @p func, the tooltip is unset with
+ * elm_gengrid_item_tooltip_unset() or the owner @p item
+ * dies. This callback receives as its first parameter the
+ * given @p data, being @c event_info the item handle.
*
- * @see elm_gengrid_item_prepend()
- * @see elm_gengrid_item_insert_before()
- * @see elm_gengrid_item_insert_after()
- * @see elm_gengrid_item_del()
+ * This call will setup the tooltip's contents to @p item
+ * (analogous to elm_object_tooltip_content_cb_set(), but being
+ * item tooltips with higher precedence than object tooltips). It
+ * can have only one tooltip at a time, so any previous tooltip
+ * content will get removed. @p func (with @p data) will be called
+ * every time Elementary needs to show the tooltip and it should
+ * return a valid Evas object, which will be fully managed by the
+ * tooltip system, getting deleted when the tooltip is gone.
*
* @ingroup Gengrid
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_item_append(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_tooltip_content_cb_set(Elm_Gengrid_Item *item, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb) EINA_ARG_NONNULL(1);
/**
- * Prepend a new item in a given gengrid widget.
+ * Unset a tooltip from a given gengrid item
*
- * @param obj The gengrid object.
- * @param gic The item class for the item.
- * @param data The item data.
- * @param func Convenience function called when the item is
- * selected.
- * @param func_data Data to be passed to @p func.
- * @return A handle to the item added or @c NULL, on errors.
+ * @param item gengrid item to remove a previously set tooltip from.
*
- * This adds an item to the end of the gengrid.
+ * This call removes any tooltip set on @p item. The callback
+ * provided as @c del_cb to
+ * elm_gengrid_item_tooltip_content_cb_set() will be called to
+ * notify it is not used anymore (and have resources cleaned, if
+ * need be).
*
- * @see elm_gengrid_item_append()
- * @see elm_gengrid_item_insert_before()
- * @see elm_gengrid_item_insert_after()
- * @see elm_gengrid_item_del()
+ * @see elm_gengrid_item_tooltip_content_cb_set()
*
* @ingroup Gengrid
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_item_prepend(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_tooltip_unset(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Insert an item before another in a gengrid widget
+ * Set a different @b style for a given gengrid item's tooltip.
*
- * @param obj The gengrid object.
- * @param gic The item class for the item.
- * @param data The item data.
- * @param relative The item to place this new one before.
- * @param func Convenience function called when the item is
- * selected.
- * @param func_data Data to be passed to @p func.
- * @return A handle to the item added or @c NULL, on errors.
+ * @param item gengrid item with tooltip set
+ * @param style the <b>theme style</b> to use on tooltips (e.g. @c
+ * "default", @c "transparent", etc)
*
- * This inserts an item before another in the gengrid.
+ * Tooltips can have <b>alternate styles</b> to be displayed on,
+ * which are defined by the theme set on Elementary. This function
+ * works analogously as elm_object_tooltip_style_set(), but here
+ * applied only to gengrid item objects. The default style for
+ * tooltips is @c "default".
*
- * @see elm_gengrid_item_append()
- * @see elm_gengrid_item_prepend()
- * @see elm_gengrid_item_insert_after()
- * @see elm_gengrid_item_del()
+ * @note before you set a style you should define a tooltip with
+ * elm_gengrid_item_tooltip_content_cb_set() or
+ * elm_gengrid_item_tooltip_text_set()
+ *
+ * @see elm_gengrid_item_tooltip_style_get()
*
* @ingroup Gengrid
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_item_insert_before(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Elm_Gengrid_Item *relative, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_tooltip_style_set(Elm_Gengrid_Item *item, const char *style) EINA_ARG_NONNULL(1);
/**
- * Insert an item after another in a gengrid widget
- *
- * @param obj The gengrid object.
- * @param gic The item class for the item.
- * @param data The item data.
- * @param relative The item to place this new one after.
- * @param func Convenience function called when the item is
- * selected.
- * @param func_data Data to be passed to @p func.
- * @return A handle to the item added or @c NULL, on errors.
+ * Get the style set a given gengrid item's tooltip.
*
- * This inserts an item after another in the gengrid.
+ * @param item gengrid item with tooltip already set on.
+ * @return style the theme style in use, which defaults to
+ * "default". If the object does not have a tooltip set,
+ * then @c NULL is returned.
*
- * @see elm_gengrid_item_append()
- * @see elm_gengrid_item_prepend()
- * @see elm_gengrid_item_insert_after()
- * @see elm_gengrid_item_del()
+ * @see elm_gengrid_item_tooltip_style_set() for more details
*
* @ingroup Gengrid
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_item_insert_after(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Elm_Gengrid_Item *relative, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
-
- EAPI Elm_Gengrid_Item *elm_gengrid_item_sorted_insert(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
-
- EAPI Elm_Gengrid_Item *elm_gengrid_item_direct_sorted_insert(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data);
-
+ EAPI const char *elm_gengrid_item_tooltip_style_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Set whether items on a given gengrid widget are to get their
- * selection callbacks issued for @b every subsequent selection
- * click on them or just for the first click.
- *
- * @param obj The gengrid object
- * @param always_select @c EINA_TRUE to make items "always
- * selected", @c EINA_FALSE, otherwise
- *
- * By default, grid items will only call their selection callback
- * function when firstly getting selected, any subsequent further
- * clicks will do nothing. With this call, you make those
- * subsequent clicks also to issue the selection callbacks.
- *
- * @note <b>Double clicks</b> will @b always be reported on items.
+ * @brief Disable size restrictions on an object's tooltip
+ * @param item The tooltip's anchor object
+ * @param disable If EINA_TRUE, size restrictions are disabled
+ * @return EINA_FALSE on failure, EINA_TRUE on success
*
- * @see elm_gengrid_always_select_mode_get()
+ * This function allows a tooltip to expand beyond its parant window's canvas.
+ * It will instead be limited only by the size of the display.
+ */
+ EAPI Eina_Bool elm_gengrid_item_tooltip_size_restrict_disable(Elm_Gengrid_Item *item, Eina_Bool disable);
+ /**
+ * @brief Retrieve size restriction state of an object's tooltip
+ * @param item The tooltip's anchor object
+ * @return If EINA_TRUE, size restrictions are disabled
*
- * @ingroup Gengrid
+ * This function returns whether a tooltip is allowed to expand beyond
+ * its parant window's canvas.
+ * It will instead be limited only by the size of the display.
*/
- EAPI void elm_gengrid_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_gengrid_item_tooltip_size_restrict_disabled_get(const Elm_Gengrid_Item *item);
/**
- * Get whether items on a given gengrid widget have their selection
- * callbacks issued for @b every subsequent selection click on them
- * or just for the first click.
+ * Set the type of mouse pointer/cursor decoration to be shown,
+ * when the mouse pointer is over the given gengrid widget item
+ *
+ * @param item gengrid item to customize cursor on
+ * @param cursor the cursor type's name
*
- * @param obj The gengrid object.
- * @return @c EINA_TRUE if the gengrid items are "always selected",
- * @c EINA_FALSE, otherwise
+ * This function works analogously as elm_object_cursor_set(), but
+ * here the cursor's changing area is restricted to the item's
+ * area, and not the whole widget's. Note that that item cursors
+ * have precedence over widget cursors, so that a mouse over @p
+ * item will always show cursor @p type.
*
- * @see elm_gengrid_always_select_mode_set() for more details
+ * If this function is called twice for an object, a previously set
+ * cursor will be unset on the second call.
+ *
+ * @see elm_object_cursor_set()
+ * @see elm_gengrid_item_cursor_get()
+ * @see elm_gengrid_item_cursor_unset()
*
* @ingroup Gengrid
*/
- EAPI Eina_Bool elm_gengrid_always_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_cursor_set(Elm_Gengrid_Item *item, const char *cursor) EINA_ARG_NONNULL(1);
/**
- * Set whether items on a given gengrid widget can be selected or not.
- *
- * @param obj The gengrid object
- * @param no_select @c EINA_TRUE to make items selectable,
- * @c EINA_FALSE otherwise
+ * Get the type of mouse pointer/cursor decoration set to be shown,
+ * when the mouse pointer is over the given gengrid widget item
*
- * This will make items in @p obj selectable or not. In the latter
- * case, any user interacion on the gendrid items will neither make
- * them appear selected nor them call their selection callback
- * functions.
+ * @param item gengrid item with custom cursor set
+ * @return the cursor type's name or @c NULL, if no custom cursors
+ * were set to @p item (and on errors)
*
- * @see elm_gengrid_no_select_mode_get()
+ * @see elm_object_cursor_get()
+ * @see elm_gengrid_item_cursor_set() for more details
+ * @see elm_gengrid_item_cursor_unset()
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_no_select_mode_set(Evas_Object *obj, Eina_Bool no_select) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_gengrid_item_cursor_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Get whether items on a given gengrid widget can be selected or
- * not.
+ * Unset any custom mouse pointer/cursor decoration set to be
+ * shown, when the mouse pointer is over the given gengrid widget
+ * item, thus making it show the @b default cursor again.
*
- * @param obj The gengrid object
- * @return @c EINA_TRUE, if items are selectable, @c EINA_FALSE
- * otherwise
+ * @param item a gengrid item
*
- * @see elm_gengrid_no_select_mode_set() for more details
+ * Use this call to undo any custom settings on this item's cursor
+ * decoration, bringing it back to defaults (no custom style set).
+ *
+ * @see elm_object_cursor_unset()
+ * @see elm_gengrid_item_cursor_set() for more details
*
* @ingroup Gengrid
*/
- EAPI Eina_Bool elm_gengrid_no_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_cursor_unset(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Enable or disable multi-selection in a given gengrid widget
+ * Set a different @b style for a given custom cursor set for a
+ * gengrid item.
*
- * @param obj The gengrid object.
- * @param multi @c EINA_TRUE, to enable multi-selection,
- * @c EINA_FALSE to disable it.
+ * @param item gengrid item with custom cursor set
+ * @param style the <b>theme style</b> to use (e.g. @c "default",
+ * @c "transparent", etc)
*
- * Multi-selection is the ability for one to have @b more than one
- * item selected, on a given gengrid, simultaneously. When it is
- * enabled, a sequence of clicks on different items will make them
- * all selected, progressively. A click on an already selected item
- * will unselect it. If interecting via the keyboard,
- * multi-selection is enabled while holding the "Shift" key.
+ * This function only makes sense when one is using custom mouse
+ * cursor decorations <b>defined in a theme file</b> , which can
+ * have, given a cursor name/type, <b>alternate styles</b> on
+ * it. It works analogously as elm_object_cursor_style_set(), but
+ * here applied only to gengrid item objects.
*
- * @note By default, multi-selection is @b disabled on gengrids
+ * @warning Before you set a cursor style you should have defined a
+ * custom cursor previously on the item, with
+ * elm_gengrid_item_cursor_set()
*
- * @see elm_gengrid_multi_select_get()
+ * @see elm_gengrid_item_cursor_engine_only_set()
+ * @see elm_gengrid_item_cursor_style_get()
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_multi_select_set(Evas_Object *obj, Eina_Bool multi) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_cursor_style_set(Elm_Gengrid_Item *item, const char *style) EINA_ARG_NONNULL(1);
/**
- * Get whether multi-selection is enabled or disabled for a given
- * gengrid widget
+ * Get the current @b style set for a given gengrid item's custom
+ * cursor
*
- * @param obj The gengrid object.
- * @return @c EINA_TRUE, if multi-selection is enabled, @c
- * EINA_FALSE otherwise
+ * @param item gengrid item with custom cursor set.
+ * @return style the cursor style in use. If the object does not
+ * have a cursor set, then @c NULL is returned.
*
- * @see elm_gengrid_multi_select_set() for more details
+ * @see elm_gengrid_item_cursor_style_set() for more details
*
* @ingroup Gengrid
*/
- EAPI Eina_Bool elm_gengrid_multi_select_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_gengrid_item_cursor_style_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Enable or disable bouncing effect for a given gengrid widget
- *
- * @param obj The gengrid object
- * @param h_bounce @c EINA_TRUE, to enable @b horizontal bouncing,
- * @c EINA_FALSE to disable it
- * @param v_bounce @c EINA_TRUE, to enable @b vertical bouncing,
- * @c EINA_FALSE to disable it
+ * Set if the (custom) cursor for a given gengrid item should be
+ * searched in its theme, also, or should only rely on the
+ * rendering engine.
*
- * The bouncing effect occurs whenever one reaches the gengrid's
- * edge's while panning it -- it will scroll past its limits a
- * little bit and return to the edge again, in a animated for,
- * automatically.
+ * @param item item with custom (custom) cursor already set on
+ * @param engine_only Use @c EINA_TRUE to have cursors looked for
+ * only on those provided by the rendering engine, @c EINA_FALSE to
+ * have them searched on the widget's theme, as well.
*
- * @note By default, gengrids have bouncing enabled on both axis
+ * @note This call is of use only if you've set a custom cursor
+ * for gengrid items, with elm_gengrid_item_cursor_set().
*
- * @see elm_gengrid_bounce_get()
+ * @note By default, cursors will only be looked for between those
+ * provided by the rendering engine.
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_item_cursor_engine_only_set(Elm_Gengrid_Item *item, Eina_Bool engine_only) EINA_ARG_NONNULL(1);
/**
- * Get whether bouncing effects are enabled or disabled, for a
- * given gengrid widget, on each axis
+ * Get if the (custom) cursor for a given gengrid item is being
+ * searched in its theme, also, or is only relying on the rendering
+ * engine.
*
- * @param obj The gengrid object
- * @param h_bounce Pointer to a variable where to store the
- * horizontal bouncing flag.
- * @param v_bounce Pointer to a variable where to store the
- * vertical bouncing flag.
+ * @param item a gengrid item
+ * @return @c EINA_TRUE, if cursors are being looked for only on
+ * those provided by the rendering engine, @c EINA_FALSE if they
+ * are being searched on the widget's theme, as well.
*
- * @see elm_gengrid_bounce_set() for more details
+ * @see elm_gengrid_item_cursor_engine_only_set(), for more details
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_gengrid_item_cursor_engine_only_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
/**
- * Set a given gengrid widget's scrolling page size, relative to
- * its viewport size.
- *
- * @param obj The gengrid object
- * @param h_pagerel The horizontal page (relative) size
- * @param v_pagerel The vertical page (relative) size
- *
- * The gengrid's scroller is capable of binding scrolling by the
- * user to "pages". It means that, while scrolling and, specially
- * after releasing the mouse button, the grid will @b snap to the
- * nearest displaying page's area. When page sizes are set, the
- * grid's continuous content area is split into (equal) page sized
- * pieces.
+ * Remove all items from a given gengrid widget
*
- * This function sets the size of a page <b>relatively to the
- * viewport dimensions</b> of the gengrid, for each axis. A value
- * @c 1.0 means "the exact viewport's size", in that axis, while @c
- * 0.0 turns paging off in that axis. Likewise, @c 0.5 means "half
- * a viewport". Sane usable values are, than, between @c 0.0 and @c
- * 1.0. Values beyond those will make it behave behave
- * inconsistently. If you only want one axis to snap to pages, use
- * the value @c 0.0 for the other one.
+ * @param obj The gengrid object.
*
- * There is a function setting page size values in @b absolute
- * values, too -- elm_gengrid_page_size_set(). Naturally, its use
- * is mutually exclusive to this one.
+ * This removes (and deletes) all items in @p obj, leaving it
+ * empty.
*
- * @see elm_gengrid_page_relative_get()
+ * @see elm_gengrid_item_del(), to remove just one item.
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel) EINA_ARG_NONNULL(1);
+ EAPI void elm_gengrid_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get a given gengrid widget's scrolling page size, relative to
- * its viewport size.
+ * Get the selected item in a given gengrid widget
*
- * @param obj The gengrid object
- * @param h_pagerel Pointer to a variable where to store the
- * horizontal page (relative) size
- * @param v_pagerel Pointer to a variable where to store the
- * vertical page (relative) size
+ * @param obj The gengrid object.
+ * @return The selected item's handleor @c NULL, if none is
+ * selected at the moment (and on errors)
*
- * @see elm_gengrid_page_relative_set() for more details
+ * This returns the selected item in @p obj. If multi selection is
+ * enabled on @p obj (@see elm_gengrid_multi_select_set()), only
+ * the first item in the list is selected, which might not be very
+ * useful. For that case, see elm_gengrid_selected_items_get().
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_page_relative_get(const Evas_Object *obj, double *h_pagerel, double *v_pagerel) EINA_ARG_NONNULL(1);
+ EAPI Elm_Gengrid_Item *elm_gengrid_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set a given gengrid widget's scrolling page size
- *
- * @param obj The gengrid object
- * @param h_pagerel The horizontal page size, in pixels
- * @param v_pagerel The vertical page size, in pixels
+ * Get <b>a list</b> of selected items in a given gengrid
*
- * The gengrid's scroller is capable of binding scrolling by the
- * user to "pages". It means that, while scrolling and, specially
- * after releasing the mouse button, the grid will @b snap to the
- * nearest displaying page's area. When page sizes are set, the
- * grid's continuous content area is split into (equal) page sized
- * pieces.
+ * @param obj The gengrid object.
+ * @return The list of selected items or @c NULL, if none is
+ * selected at the moment (and on errors)
*
- * This function sets the size of a page of the gengrid, in pixels,
- * for each axis. Sane usable values are, between @c 0 and the
- * dimensions of @p obj, for each axis. Values beyond those will
- * make it behave behave inconsistently. If you only want one axis
- * to snap to pages, use the value @c 0 for the other one.
+ * This returns a list of the selected items, in the order that
+ * they appear in the grid. This list is only valid as long as no
+ * more items are selected or unselected (or unselected implictly
+ * by deletion). The list contains #Elm_Gengrid_Item pointers as
+ * data, naturally.
*
- * There is a function setting page size values in @b relative
- * values, too -- elm_gengrid_page_relative_set(). Naturally, its
- * use is mutually exclusive to this one.
+ * @see elm_gengrid_selected_item_get()
*
* @ingroup Gengrid
*/
- EAPI void elm_gengrid_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize) EINA_ARG_NONNULL(1);
+ EAPI const Eina_List *elm_gengrid_selected_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set for what direction a given gengrid widget will expand while
- * placing its items.
+ * @}
+ */
+
+ /**
+ * @defgroup Clock Clock
*
- * @param obj The gengrid object.
- * @param setting @c EINA_TRUE to make the gengrid expand
- * horizontally, @c EINA_FALSE to expand vertically.
+ * @image html img/widget/clock/preview-00.png
+ * @image latex img/widget/clock/preview-00.eps
*
- * When in "horizontal mode" (@c EINA_TRUE), items will be placed
- * in @b columns, from top to bottom and, when the space for a
- * column is filled, another one is started on the right, thus
- * expanding the grid horizontally. When in "vertical mode"
- * (@c EINA_FALSE), though, items will be placed in @b rows, from left
- * to right and, when the space for a row is filled, another one is
- * started below, thus expanding the grid vertically.
+ * This is a @b digital clock widget. In its default theme, it has a
+ * vintage "flipping numbers clock" appearance, which will animate
+ * sheets of individual algarisms individually as time goes by.
+ *
+ * A newly created clock will fetch system's time (already
+ * considering local time adjustments) to start with, and will tick
+ * accondingly. It may or may not show seconds.
+ *
+ * Clocks have an @b edition mode. When in it, the sheets will
+ * display extra arrow indications on the top and bottom and the
+ * user may click on them to raise or lower the time values. After
+ * it's told to exit edition mode, it will keep ticking with that
+ * new time set (it keeps the difference from local time).
+ *
+ * Also, when under edition mode, user clicks on the cited arrows
+ * which are @b held for some time will make the clock to flip the
+ * sheet, thus editing the time, continuosly and automatically for
+ * the user. The interval between sheet flips will keep growing in
+ * time, so that it helps the user to reach a time which is distant
+ * from the one set.
*
- * @see elm_gengrid_horizontal_get()
+ * The time display is, by default, in military mode (24h), but an
+ * am/pm indicator may be optionally shown, too, when it will
+ * switch to 12h.
*
- * @ingroup Gengrid
+ * Smart callbacks one can register to:
+ * - "changed" - the clock's user changed the time
+ *
+ * Here is an example on its usage:
+ * @li @ref clock_example
*/
- EAPI void elm_gengrid_horizontal_set(Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
/**
- * Get for what direction a given gengrid widget will expand while
- * placing its items.
- *
- * @param obj The gengrid object.
- * @return @c EINA_TRUE, if @p obj is set to expand horizontally,
- * @c EINA_FALSE if it's set to expand vertically.
- *
- * @see elm_gengrid_horizontal_set() for more detais
- *
- * @ingroup Gengrid
+ * @addtogroup Clock
+ * @{
*/
- EAPI Eina_Bool elm_gengrid_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the first item in a given gengrid widget
+ * Identifiers for which clock digits should be editable, when a
+ * clock widget is in edition mode. Values may be ORed together to
+ * make a mask, naturally.
*
- * @param obj The gengrid object
- * @return The first item's handle or @c NULL, if there are no
- * items in @p obj (and on errors)
+ * @see elm_clock_edit_set()
+ * @see elm_clock_digit_edit_set()
+ */
+ typedef enum _Elm_Clock_Digedit
+ {
+ ELM_CLOCK_NONE = 0, /**< Default value. Means that all digits are editable, when in edition mode. */
+ ELM_CLOCK_HOUR_DECIMAL = 1 << 0, /**< Decimal algarism of hours value should be editable */
+ ELM_CLOCK_HOUR_UNIT = 1 << 1, /**< Unit algarism of hours value should be editable */
+ ELM_CLOCK_MIN_DECIMAL = 1 << 2, /**< Decimal algarism of minutes value should be editable */
+ ELM_CLOCK_MIN_UNIT = 1 << 3, /**< Unit algarism of minutes value should be editable */
+ ELM_CLOCK_SEC_DECIMAL = 1 << 4, /**< Decimal algarism of seconds value should be editable */
+ ELM_CLOCK_SEC_UNIT = 1 << 5, /**< Unit algarism of seconds value should be editable */
+ ELM_CLOCK_ALL = (1 << 6) - 1 /**< All digits should be editable */
+ } Elm_Clock_Digedit;
+
+ /**
+ * Add a new clock widget to the given parent Elementary
+ * (container) object
*
- * This returns the first item in the @p obj's internal list of
- * items.
+ * @param parent The parent object
+ * @return a new clock widget handle or @c NULL, on errors
*
- * @see elm_gengrid_last_item_get()
+ * This function inserts a new clock widget on the canvas.
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_clock_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * Get the last item in a given gengrid widget
+ * Set a clock widget's time, programmatically
*
- * @param obj The gengrid object
- * @return The last item's handle or @c NULL, if there are no
- * items in @p obj (and on errors)
+ * @param obj The clock widget object
+ * @param hrs The hours to set
+ * @param min The minutes to set
+ * @param sec The secondes to set
*
- * This returns the last item in the @p obj's internal list of
- * items.
+ * This function updates the time that is showed by the clock
+ * widget.
*
- * @see elm_gengrid_first_item_get()
+ * Values @b must be set within the following ranges:
+ * - 0 - 23, for hours
+ * - 0 - 59, for minutes
+ * - 0 - 59, for seconds,
*
- * @ingroup Gengrid
+ * even if the clock is not in "military" mode.
+ *
+ * @warning The behavior for values set out of those ranges is @b
+ * indefined.
+ *
+ * @ingroup Clock
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_clock_time_set(Evas_Object *obj, int hrs, int min, int sec) EINA_ARG_NONNULL(1);
/**
- * Get the @b next item in a gengrid widget's internal list of items,
- * given a handle to one of those items.
+ * Get a clock widget's time values
*
- * @param item The gengrid item to fetch next from
- * @return The item after @p item, or @c NULL if there's none (and
- * on errors)
+ * @param obj The clock object
+ * @param[out] hrs Pointer to the variable to get the hours value
+ * @param[out] min Pointer to the variable to get the minutes value
+ * @param[out] sec Pointer to the variable to get the seconds value
*
- * This returns the item placed after the @p item, on the container
- * gengrid.
+ * This function gets the time set for @p obj, returning
+ * it on the variables passed as the arguments to function
*
- * @see elm_gengrid_item_prev_get()
+ * @note Use @c NULL pointers on the time values you're not
+ * interested in: they'll be ignored by the function.
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_item_next_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI void elm_clock_time_get(const Evas_Object *obj, int *hrs, int *min, int *sec) EINA_ARG_NONNULL(1);
/**
- * Get the @b previous item in a gengrid widget's internal list of items,
- * given a handle to one of those items.
+ * Set whether a given clock widget is under <b>edition mode</b> or
+ * under (default) displaying-only mode.
*
- * @param item The gengrid item to fetch previous from
- * @return The item before @p item, or @c NULL if there's none (and
- * on errors)
+ * @param obj The clock object
+ * @param edit @c EINA_TRUE to put it in edition, @c EINA_FALSE to
+ * put it back to "displaying only" mode
*
- * This returns the item placed before the @p item, on the container
- * gengrid.
+ * This function makes a clock's time to be editable or not <b>by
+ * user interaction</b>. When in edition mode, clocks @b stop
+ * ticking, until one brings them back to canonical mode. The
+ * elm_clock_digit_edit_set() function will influence which digits
+ * of the clock will be editable. By default, all of them will be
+ * (#ELM_CLOCK_NONE).
*
- * @see elm_gengrid_item_next_get()
+ * @note am/pm sheets, if being shown, will @b always be editable
+ * under edition mode.
*
- * @ingroup Gengrid
+ * @see elm_clock_edit_get()
+ *
+ * @ingroup Clock
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_item_prev_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI void elm_clock_edit_set(Evas_Object *obj, Eina_Bool edit) EINA_ARG_NONNULL(1);
/**
- * Get the gengrid object's handle which contains a given gengrid
- * item
+ * Retrieve whether a given clock widget is under <b>edition
+ * mode</b> or under (default) displaying-only mode.
*
- * @param item The item to fetch the container from
- * @return The gengrid (parent) object
+ * @param obj The clock object
+ * @param edit @c EINA_TRUE, if it's in edition mode, @c EINA_FALSE
+ * otherwise
*
- * This returns the gengrid object itself that an item belongs to.
+ * This function retrieves whether the clock's time can be edited
+ * or not by user interaction.
*
- * @ingroup Gengrid
+ * @see elm_clock_edit_set() for more details
+ *
+ * @ingroup Clock
*/
- EAPI Evas_Object *elm_gengrid_item_gengrid_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_clock_edit_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Remove a gengrid item from the its parent, deleting it.
+ * Set what digits of the given clock widget should be editable
+ * when in edition mode.
*
- * @param item The item to be removed.
- * @return @c EINA_TRUE on success or @c EINA_FALSE, otherwise.
+ * @param obj The clock object
+ * @param digedit Bit mask indicating the digits to be editable
+ * (values in #Elm_Clock_Digedit).
*
- * @see elm_gengrid_clear(), to remove all items in a gengrid at
- * once.
+ * If the @p digedit param is #ELM_CLOCK_NONE, editing will be
+ * disabled on @p obj (same effect as elm_clock_edit_set(), with @c
+ * EINA_FALSE).
*
- * @ingroup Gengrid
+ * @see elm_clock_digit_edit_get()
+ *
+ * @ingroup Clock
*/
- EAPI void elm_gengrid_item_del(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI void elm_clock_digit_edit_set(Evas_Object *obj, Elm_Clock_Digedit digedit) EINA_ARG_NONNULL(1);
/**
- * Update the contents of a given gengrid item
+ * Retrieve what digits of the given clock widget should be
+ * editable when in edition mode.
*
- * @param item The gengrid item
+ * @param obj The clock object
+ * @return Bit mask indicating the digits to be editable
+ * (values in #Elm_Clock_Digedit).
*
- * This updates an item by calling all the item class functions
- * again to get the icons, labels and states. Use this when the
- * original item data has changed and you want thta changes to be
- * reflected.
+ * @see elm_clock_digit_edit_set() for more details
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI void elm_gengrid_item_update(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
- EAPI const Elm_Gengrid_Item_Class *elm_gengrid_item_item_class_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
- EAPI void elm_gengrid_item_item_class_set(Elm_Gengrid_Item *item, const Elm_Gengrid_Item_Class *gic) EINA_ARG_NONNULL(1, 2);
+ EAPI Elm_Clock_Digedit elm_clock_digit_edit_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Return the data associated to a given gengrid item
+ * Set if the given clock widget must show hours in military or
+ * am/pm mode
*
- * @param item The gengrid item.
- * @return the data associated to this item.
+ * @param obj The clock object
+ * @param am_pm @c EINA_TRUE to put it in am/pm mode, @c EINA_FALSE
+ * to military mode
*
- * This returns the @c data value passed on the
- * elm_gengrid_item_append() and related item addition calls.
+ * This function sets if the clock must show hours in military or
+ * am/pm mode. In some countries like Brazil the military mode
+ * (00-24h-format) is used, in opposition to the USA, where the
+ * am/pm mode is more commonly used.
*
- * @see elm_gengrid_item_append()
- * @see elm_gengrid_item_data_set()
+ * @see elm_clock_show_am_pm_get()
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI void *elm_gengrid_item_data_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI void elm_clock_show_am_pm_set(Evas_Object *obj, Eina_Bool am_pm) EINA_ARG_NONNULL(1);
/**
- * Set the data associated to a given gengrid item
+ * Get if the given clock widget shows hours in military or am/pm
+ * mode
*
- * @param item The gengrid item
- * @param data The new data pointer to set on it
+ * @param obj The clock object
+ * @return @c EINA_TRUE, if in am/pm mode, @c EINA_FALSE if in
+ * military
*
- * This @b overrides the @c data value passed on the
- * elm_gengrid_item_append() and related item addition calls. This
- * function @b won't call elm_gengrid_item_update() automatically,
- * so you'd issue it afterwards if you want to hove the item
- * updated to reflect the that new data.
+ * This function gets if the clock shows hours in military or am/pm
+ * mode.
*
- * @see elm_gengrid_item_data_get()
+ * @see elm_clock_show_am_pm_set() for more details
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI void elm_gengrid_item_data_set(Elm_Gengrid_Item *item, const void *data) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_clock_show_am_pm_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get a given gengrid item's position, relative to the whole
- * gengrid's grid area.
+ * Set if the given clock widget must show time with seconds or not
*
- * @param item The Gengrid item.
- * @param x Pointer to variable where to store the item's <b>row
- * number</b>.
- * @param y Pointer to variable where to store the item's <b>column
- * number</b>.
+ * @param obj The clock object
+ * @param seconds @c EINA_TRUE to show seconds, @c EINA_FALSE otherwise
*
- * This returns the "logical" position of the item whithin the
- * gengrid. For example, @c (0, 1) would stand for first row,
- * second column.
+ * This function sets if the given clock must show or not elapsed
+ * seconds. By default, they are @b not shown.
*
- * @ingroup Gengrid
+ * @see elm_clock_show_seconds_get()
+ *
+ * @ingroup Clock
*/
- EAPI void elm_gengrid_item_pos_get(const Elm_Gengrid_Item *item, unsigned int *x, unsigned int *y) EINA_ARG_NONNULL(1);
+ EAPI void elm_clock_show_seconds_set(Evas_Object *obj, Eina_Bool seconds) EINA_ARG_NONNULL(1);
/**
- * Set whether a given gengrid item is selected or not
+ * Get whether the given clock widget is showing time with seconds
+ * or not
*
- * @param item The gengrid item
- * @param selected Use @c EINA_TRUE, to make it selected, @c
- * EINA_FALSE to make it unselected
+ * @param obj The clock object
+ * @return @c EINA_TRUE if it's showing seconds, @c EINA_FALSE otherwise
*
- * This sets the selected state of an item. If multi selection is
- * not enabled on the containing gengrid and @p selected is @c
- * EINA_TRUE, any other previously selected items will get
- * unselected in favor of this new one.
+ * This function gets whether @p obj is showing or not the elapsed
+ * seconds.
*
- * @see elm_gengrid_item_selected_get()
+ * @see elm_clock_show_seconds_set()
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI void elm_gengrid_item_selected_set(Elm_Gengrid_Item *item, Eina_Bool selected) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_clock_show_seconds_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get whether a given gengrid item is selected or not
+ * Set the interval on time updates for an user mouse button hold
+ * on clock widgets' time edition.
*
- * @param item The gengrid item
- * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
+ * @param obj The clock object
+ * @param interval The (first) interval value in seconds
*
- * @see elm_gengrid_item_selected_set() for more details
+ * This interval value is @b decreased while the user holds the
+ * mouse pointer either incrementing or decrementing a given the
+ * clock digit's value.
*
- * @ingroup Gengrid
- */
- EAPI Eina_Bool elm_gengrid_item_selected_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
- /**
- * Get the real Evas object created to implement the view of a
- * given gengrid item
+ * This helps the user to get to a given time distant from the
+ * current one easier/faster, as it will start to flip quicker and
+ * quicker on mouse button holds.
*
- * @param item The gengrid item.
- * @return the Evas object implementing this item's view.
+ * The calculation for the next flip interval value, starting from
+ * the one set with this call, is the previous interval divided by
+ * 1.05, so it decreases a little bit.
*
- * This returns the actual Evas object used to implement the
- * specified gengrid item's view. This may be @c NULL, as it may
- * not have been created or may have been deleted, at any time, by
- * the gengrid. <b>Do not modify this object</b> (move, resize,
- * show, hide, etc.), as the gengrid is controlling it. This
- * function is for querying, emitting custom signals or hooking
- * lower level callbacks for events on that object. Do not delete
- * this object under any circumstances.
+ * The default starting interval value for automatic flips is
+ * @b 0.85 seconds.
*
- * @see elm_gengrid_item_data_get()
+ * @see elm_clock_interval_get()
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI const Evas_Object *elm_gengrid_item_object_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI void elm_clock_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
/**
- * Show the portion of a gengrid's internal grid containing a given
- * item, @b immediately.
- *
- * @param item The item to display
+ * Get the interval on time updates for an user mouse button hold
+ * on clock widgets' time edition.
*
- * This causes gengrid to @b redraw its viewport's contents to the
- * region contining the given @p item item, if it is not fully
- * visible.
+ * @param obj The clock object
+ * @return The (first) interval value, in seconds, set on it
*
- * @see elm_gengrid_item_bring_in()
+ * @see elm_clock_interval_set() for more details
*
- * @ingroup Gengrid
+ * @ingroup Clock
*/
- EAPI void elm_gengrid_item_show(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI double elm_clock_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Animatedly bring in, to the visible are of a gengrid, a given
- * item on it.
+ * @}
+ */
+
+ /**
+ * @defgroup Layout Layout
*
- * @param item The gengrid item to display
+ * @image html img/widget/layout/preview-00.png
+ * @image latex img/widget/layout/preview-00.eps width=\textwidth
*
- * This causes gengrig to jump to the given @p item item and show
- * it (by scrolling), if it is not fully visible. This will use
- * animation to do so and take a period of time to complete.
+ * @image html img/layout-predefined.png
+ * @image latex img/layout-predefined.eps width=\textwidth
*
- * @see elm_gengrid_item_show()
+ * This is a container widget that takes a standard Edje design file and
+ * wraps it very thinly in a widget.
*
- * @ingroup Gengrid
- */
- EAPI void elm_gengrid_item_bring_in(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
- /**
- * Set whether a given gengrid item is disabled or not.
+ * An Edje design (theme) file has a very wide range of possibilities to
+ * describe the behavior of elements added to the Layout. Check out the Edje
+ * documentation and the EDC reference to get more information about what can
+ * be done with Edje.
*
- * @param item The gengrid item
- * @param disabled Use @c EINA_TRUE, true disable it, @c EINA_FALSE
- * to enable it back.
+ * Just like @ref List, @ref Box, and other container widgets, any
+ * object added to the Layout will become its child, meaning that it will be
+ * deleted if the Layout is deleted, move if the Layout is moved, and so on.
*
- * A disabled item cannot be selected or unselected. It will also
- * change its appearance, to signal the user it's disabled.
+ * The Layout widget can contain as many Contents, Boxes or Tables as
+ * described in its theme file. For instance, objects can be added to
+ * different Tables by specifying the respective Table part names. The same
+ * is valid for Content and Box.
*
- * @see elm_gengrid_item_disabled_get()
+ * The objects added as child of the Layout will behave as described in the
+ * part description where they were added. There are 3 possible types of
+ * parts where a child can be added:
*
- * @ingroup Gengrid
- */
- EAPI void elm_gengrid_item_disabled_set(Elm_Gengrid_Item *item, Eina_Bool disabled) EINA_ARG_NONNULL(1);
-
- /**
- * Get whether a given gengrid item is disabled or not.
+ * @section secContent Content (SWALLOW part)
*
- * @param item The gengrid item
- * @return @c EINA_TRUE, if it's disabled, @c EINA_FALSE otherwise
- * (and on errors).
+ * Only one object can be added to the @c SWALLOW part (but you still can
+ * have many @c SWALLOW parts and one object on each of them). Use the @c
+ * elm_layout_content_* set of functions to set, retrieve and unset objects
+ * as content of the @c SWALLOW. After being set to this part, the object
+ * size, position, visibility, clipping and other description properties
+ * will be totally controled by the description of the given part (inside
+ * the Edje theme file).
*
- * @see elm_gengrid_item_disabled_set() for more details
+ * One can use @c evas_object_size_hint_* functions on the child to have some
+ * kind of control over its behavior, but the resulting behavior will still
+ * depend heavily on the @c SWALLOW part description.
*
- * @ingroup Gengrid
- */
- EAPI Eina_Bool elm_gengrid_item_disabled_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
- /**
- * Set the text to be shown in a given gengrid item's tooltips.
+ * The Edje theme also can change the part description, based on signals or
+ * scripts running inside the theme. This change can also be animated. All of
+ * this will affect the child object set as content accordingly. The object
+ * size will be changed if the part size is changed, it will animate move if
+ * the part is moving, and so on.
*
- * @param item The gengrid item
- * @param text The text to set in the content
+ * The following picture demonstrates a Layout widget with a child object
+ * added to its @c SWALLOW:
*
- * This call will setup the text to be used as tooltip to that item
- * (analogous to elm_object_tooltip_text_set(), but being item
- * tooltips with higher precedence than object tooltips). It can
- * have only one tooltip at a time, so any previous tooltip data
- * will get removed.
+ * @image html layout_swallow.png
+ * @image latex layout_swallow.eps width=\textwidth
*
- * @ingroup Gengrid
- */
- EAPI void elm_gengrid_item_tooltip_text_set(Elm_Gengrid_Item *item, const char *text) EINA_ARG_NONNULL(1);
-
- /**
- * Set the content to be shown in a given gengrid item's tooltips
+ * @section secBox Box (BOX part)
*
- * @param item The gengrid item.
- * @param func The function returning the tooltip contents.
- * @param data What to provide to @a func as callback data/context.
- * @param del_cb Called when data is not needed anymore, either when
- * another callback replaces @p func, the tooltip is unset with
- * elm_gengrid_item_tooltip_unset() or the owner @p item
- * dies. This callback receives as its first parameter the
- * given @p data, being @c event_info the item handle.
+ * An Edje @c BOX part is very similar to the Elementary @ref Box widget. It
+ * allows one to add objects to the box and have them distributed along its
+ * area, accordingly to the specified @a layout property (now by @a layout we
+ * mean the chosen layouting design of the Box, not the Layout widget
+ * itself).
*
- * This call will setup the tooltip's contents to @p item
- * (analogous to elm_object_tooltip_content_cb_set(), but being
- * item tooltips with higher precedence than object tooltips). It
- * can have only one tooltip at a time, so any previous tooltip
- * content will get removed. @p func (with @p data) will be called
- * every time Elementary needs to show the tooltip and it should
- * return a valid Evas object, which will be fully managed by the
- * tooltip system, getting deleted when the tooltip is gone.
+ * A similar effect for having a box with its position, size and other things
+ * controled by the Layout theme would be to create an Elementary @ref Box
+ * widget and add it as a Content in the @c SWALLOW part.
*
- * @ingroup Gengrid
- */
- EAPI void elm_gengrid_item_tooltip_content_cb_set(Elm_Gengrid_Item *item, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb) EINA_ARG_NONNULL(1);
-
- /**
- * Unset a tooltip from a given gengrid item
+ * The main difference of using the Layout Box is that its behavior, the box
+ * properties like layouting format, padding, align, etc. will be all
+ * controled by the theme. This means, for example, that a signal could be
+ * sent to the Layout theme (with elm_object_signal_emit()) and the theme
+ * handled the signal by changing the box padding, or align, or both. Using
+ * the Elementary @ref Box widget is not necessarily harder or easier, it
+ * just depends on the circunstances and requirements.
*
- * @param item gengrid item to remove a previously set tooltip from.
+ * The Layout Box can be used through the @c elm_layout_box_* set of
+ * functions.
*
- * This call removes any tooltip set on @p item. The callback
- * provided as @c del_cb to
- * elm_gengrid_item_tooltip_content_cb_set() will be called to
- * notify it is not used anymore (and have resources cleaned, if
- * need be).
+ * The following picture demonstrates a Layout widget with many child objects
+ * added to its @c BOX part:
*
- * @see elm_gengrid_item_tooltip_content_cb_set()
+ * @image html layout_box.png
+ * @image latex layout_box.eps width=\textwidth
*
- * @ingroup Gengrid
- */
- EAPI void elm_gengrid_item_tooltip_unset(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
- /**
- * Set a different @b style for a given gengrid item's tooltip.
+ * @section secTable Table (TABLE part)
+ *
+ * Just like the @ref secBox, the Layout Table is very similar to the
+ * Elementary @ref Table widget. It allows one to add objects to the Table
+ * specifying the row and column where the object should be added, and any
+ * column or row span if necessary.
+ *
+ * Again, we could have this design by adding a @ref Table widget to the @c
+ * SWALLOW part using elm_layout_content_set(). The same difference happens
+ * here when choosing to use the Layout Table (a @c TABLE part) instead of
+ * the @ref Table plus @c SWALLOW part. It's just a matter of convenience.
+ *
+ * The Layout Table can be used through the @c elm_layout_table_* set of
+ * functions.
+ *
+ * The following picture demonstrates a Layout widget with many child objects
+ * added to its @c TABLE part:
+ *
+ * @image html layout_table.png
+ * @image latex layout_table.eps width=\textwidth
+ *
+ * @section secPredef Predefined Layouts
+ *
+ * Another interesting thing about the Layout widget is that it offers some
+ * predefined themes that come with the default Elementary theme. These
+ * themes can be set by the call elm_layout_theme_set(), and provide some
+ * basic functionality depending on the theme used.
*
- * @param item gengrid item with tooltip set
- * @param style the <b>theme style</b> to use on tooltips (e.g. @c
- * "default", @c "transparent", etc)
+ * Most of them already send some signals, some already provide a toolbar or
+ * back and next buttons.
*
- * Tooltips can have <b>alternate styles</b> to be displayed on,
- * which are defined by the theme set on Elementary. This function
- * works analogously as elm_object_tooltip_style_set(), but here
- * applied only to gengrid item objects. The default style for
- * tooltips is @c "default".
+ * These are available predefined theme layouts. All of them have class = @c
+ * layout, group = @c application, and style = one of the following options:
*
- * @note before you set a style you should define a tooltip with
- * elm_gengrid_item_tooltip_content_cb_set() or
- * elm_gengrid_item_tooltip_text_set()
+ * @li @c toolbar-content - application with toolbar and main content area
+ * @li @c toolbar-content-back - application with toolbar and main content
+ * area with a back button and title area
+ * @li @c toolbar-content-back-next - application with toolbar and main
+ * content area with a back and next buttons and title area
+ * @li @c content-back - application with a main content area with a back
+ * button and title area
+ * @li @c content-back-next - application with a main content area with a
+ * back and next buttons and title area
+ * @li @c toolbar-vbox - application with toolbar and main content area as a
+ * vertical box
+ * @li @c toolbar-table - application with toolbar and main content area as a
+ * table
*
- * @see elm_gengrid_item_tooltip_style_get()
+ * @section secExamples Examples
+ *
+ * Some examples of the Layout widget can be found here:
+ * @li @ref layout_example_01
+ * @li @ref layout_example_02
+ * @li @ref layout_example_03
+ * @li @ref layout_example_edc
*
- * @ingroup Gengrid
*/
- EAPI void elm_gengrid_item_tooltip_style_set(Elm_Gengrid_Item *item, const char *style) EINA_ARG_NONNULL(1);
/**
- * Get the style set a given gengrid item's tooltip.
+ * Add a new layout to the parent
*
- * @param item gengrid item with tooltip already set on.
- * @return style the theme style in use, which defaults to
- * "default". If the object does not have a tooltip set,
- * then @c NULL is returned.
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*
- * @see elm_gengrid_item_tooltip_style_set() for more details
+ * @see elm_layout_file_set()
+ * @see elm_layout_theme_set()
*
- * @ingroup Gengrid
+ * @ingroup Layout
*/
- EAPI const char *elm_gengrid_item_tooltip_style_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_layout_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * @brief Disable size restrictions on an object's tooltip
- * @param item The tooltip's anchor object
- * @param disable If EINA_TRUE, size restrictions are disabled
- * @return EINA_FALSE on failure, EINA_TRUE on success
+ * Set the file that will be used as layout
*
- * This function allows a tooltip to expand beyond its parant window's canvas.
- * It will instead be limited only by the size of the display.
- */
- EAPI Eina_Bool elm_gengrid_item_tooltip_size_restrict_disable(Elm_Gengrid_Item *item, Eina_Bool disable);
- /**
- * @brief Retrieve size restriction state of an object's tooltip
- * @param item The tooltip's anchor object
- * @return If EINA_TRUE, size restrictions are disabled
+ * @param obj The layout object
+ * @param file The path to file (edj) that will be used as layout
+ * @param group The group that the layout belongs in edje file
*
- * This function returns whether a tooltip is allowed to expand beyond
- * its parant window's canvas.
- * It will instead be limited only by the size of the display.
+ * @return (1 = success, 0 = error)
+ *
+ * @ingroup Layout
*/
- EAPI Eina_Bool elm_gengrid_item_tooltip_size_restrict_disabled_get(const Elm_Gengrid_Item *item);
+ EAPI Eina_Bool elm_layout_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1);
/**
- * Set the type of mouse pointer/cursor decoration to be shown,
- * when the mouse pointer is over the given gengrid widget item
- *
- * @param item gengrid item to customize cursor on
- * @param cursor the cursor type's name
- *
- * This function works analogously as elm_object_cursor_set(), but
- * here the cursor's changing area is restricted to the item's
- * area, and not the whole widget's. Note that that item cursors
- * have precedence over widget cursors, so that a mouse over @p
- * item will always show cursor @p type.
+ * Set the edje group from the elementary theme that will be used as layout
*
- * If this function is called twice for an object, a previously set
- * cursor will be unset on the second call.
+ * @param obj The layout object
+ * @param clas the clas of the group
+ * @param group the group
+ * @param style the style to used
*
- * @see elm_object_cursor_set()
- * @see elm_gengrid_item_cursor_get()
- * @see elm_gengrid_item_cursor_unset()
+ * @return (1 = success, 0 = error)
*
- * @ingroup Gengrid
+ * @ingroup Layout
*/
- EAPI void elm_gengrid_item_cursor_set(Elm_Gengrid_Item *item, const char *cursor) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_layout_theme_set(Evas_Object *obj, const char *clas, const char *group, const char *style) EINA_ARG_NONNULL(1);
/**
- * Get the type of mouse pointer/cursor decoration set to be shown,
- * when the mouse pointer is over the given gengrid widget item
+ * Set the layout content.
*
- * @param item gengrid item with custom cursor set
- * @return the cursor type's name or @c NULL, if no custom cursors
- * were set to @p item (and on errors)
+ * @param obj The layout object
+ * @param swallow The swallow part name in the edje file
+ * @param content The child that will be added in this layout object
*
- * @see elm_object_cursor_get()
- * @see elm_gengrid_item_cursor_set() for more details
- * @see elm_gengrid_item_cursor_unset()
+ * Once the content object is set, a previously set one will be deleted.
+ * If you want to keep that old content object, use the
+ * elm_layout_content_unset() function.
*
- * @ingroup Gengrid
+ * @note In an Edje theme, the part used as a content container is called @c
+ * SWALLOW. This is why the parameter name is called @p swallow, but it is
+ * expected to be a part name just like the second parameter of
+ * elm_layout_box_append().
+ *
+ * @see elm_layout_box_append()
+ * @see elm_layout_content_get()
+ * @see elm_layout_content_unset()
+ * @see @ref secBox
+ *
+ * @ingroup Layout
*/
- EAPI const char *elm_gengrid_item_cursor_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_layout_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
/**
- * Unset any custom mouse pointer/cursor decoration set to be
- * shown, when the mouse pointer is over the given gengrid widget
- * item, thus making it show the @b default cursor again.
+ * Get the child object in the given content part.
*
- * @param item a gengrid item
+ * @param obj The layout object
+ * @param swallow The SWALLOW part to get its content
*
- * Use this call to undo any custom settings on this item's cursor
- * decoration, bringing it back to defaults (no custom style set).
+ * @return The swallowed object or NULL if none or an error occurred
*
- * @see elm_object_cursor_unset()
- * @see elm_gengrid_item_cursor_set() for more details
+ * @see elm_layout_content_set()
*
- * @ingroup Gengrid
+ * @ingroup Layout
*/
- EAPI void elm_gengrid_item_cursor_unset(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
+ EAPI Evas_Object *elm_layout_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
/**
- * Set a different @b style for a given custom cursor set for a
- * gengrid item.
- *
- * @param item gengrid item with custom cursor set
- * @param style the <b>theme style</b> to use (e.g. @c "default",
- * @c "transparent", etc)
+ * Unset the layout content.
*
- * This function only makes sense when one is using custom mouse
- * cursor decorations <b>defined in a theme file</b> , which can
- * have, given a cursor name/type, <b>alternate styles</b> on
- * it. It works analogously as elm_object_cursor_style_set(), but
- * here applied only to gengrid item objects.
+ * @param obj The layout object
+ * @param swallow The swallow part name in the edje file
+ * @return The content that was being used
*
- * @warning Before you set a cursor style you should have defined a
- * custom cursor previously on the item, with
- * elm_gengrid_item_cursor_set()
+ * Unparent and return the content object which was set for this part.
*
- * @see elm_gengrid_item_cursor_engine_only_set()
- * @see elm_gengrid_item_cursor_style_get()
+ * @see elm_layout_content_set()
*
- * @ingroup Gengrid
+ * @ingroup Layout
*/
- EAPI void elm_gengrid_item_cursor_style_set(Elm_Gengrid_Item *item, const char *style) EINA_ARG_NONNULL(1);
-
+ EAPI Evas_Object *elm_layout_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
/**
- * Get the current @b style set for a given gengrid item's custom
- * cursor
- *
- * @param item gengrid item with custom cursor set.
- * @return style the cursor style in use. If the object does not
- * have a cursor set, then @c NULL is returned.
+ * Set the text of the given part
*
- * @see elm_gengrid_item_cursor_style_set() for more details
+ * @param obj The layout object
+ * @param part The TEXT part where to set the text
+ * @param text The text to set
*
- * @ingroup Gengrid
+ * @ingroup Layout
+ * @deprecated use elm_object_text_* instead.
*/
- EAPI const char *elm_gengrid_item_cursor_style_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
+ EINA_DEPRECATED EAPI void elm_layout_text_set(Evas_Object *obj, const char *part, const char *text) EINA_ARG_NONNULL(1);
/**
- * Set if the (custom) cursor for a given gengrid item should be
- * searched in its theme, also, or should only rely on the
- * rendering engine.
- *
- * @param item item with custom (custom) cursor already set on
- * @param engine_only Use @c EINA_TRUE to have cursors looked for
- * only on those provided by the rendering engine, @c EINA_FALSE to
- * have them searched on the widget's theme, as well.
+ * Get the text set in the given part
*
- * @note This call is of use only if you've set a custom cursor
- * for gengrid items, with elm_gengrid_item_cursor_set().
+ * @param obj The layout object
+ * @param part The TEXT part to retrieve the text off
*
- * @note By default, cursors will only be looked for between those
- * provided by the rendering engine.
+ * @return The text set in @p part
*
- * @ingroup Gengrid
+ * @ingroup Layout
+ * @deprecated use elm_object_text_* instead.
*/
- EAPI void elm_gengrid_item_cursor_engine_only_set(Elm_Gengrid_Item *item, Eina_Bool engine_only) EINA_ARG_NONNULL(1);
-
+ EINA_DEPRECATED EAPI const char *elm_layout_text_get(const Evas_Object *obj, const char *part) EINA_ARG_NONNULL(1);
/**
- * Get if the (custom) cursor for a given gengrid item is being
- * searched in its theme, also, or is only relying on the rendering
- * engine.
+ * Append child to layout box part.
*
- * @param item a gengrid item
- * @return @c EINA_TRUE, if cursors are being looked for only on
- * those provided by the rendering engine, @c EINA_FALSE if they
- * are being searched on the widget's theme, as well.
+ * @param obj the layout object
+ * @param part the box part to which the object will be appended.
+ * @param child the child object to append to box.
*
- * @see elm_gengrid_item_cursor_engine_only_set(), for more details
+ * Once the object is appended, it will become child of the layout. Its
+ * lifetime will be bound to the layout, whenever the layout dies the child
+ * will be deleted automatically. One should use elm_layout_box_remove() to
+ * make this layout forget about the object.
*
- * @ingroup Gengrid
+ * @see elm_layout_box_prepend()
+ * @see elm_layout_box_insert_before()
+ * @see elm_layout_box_insert_at()
+ * @see elm_layout_box_remove()
+ *
+ * @ingroup Layout
*/
- EAPI Eina_Bool elm_gengrid_item_cursor_engine_only_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_layout_box_append(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
/**
- * Remove all items from a given gengrid widget
+ * Prepend child to layout box part.
*
- * @param obj The gengrid object.
+ * @param obj the layout object
+ * @param part the box part to prepend.
+ * @param child the child object to prepend to box.
*
- * This removes (and deletes) all items in @p obj, leaving it
- * empty.
+ * Once the object is prepended, it will become child of the layout. Its
+ * lifetime will be bound to the layout, whenever the layout dies the child
+ * will be deleted automatically. One should use elm_layout_box_remove() to
+ * make this layout forget about the object.
*
- * @see elm_gengrid_item_del(), to remove just one item.
+ * @see elm_layout_box_append()
+ * @see elm_layout_box_insert_before()
+ * @see elm_layout_box_insert_at()
+ * @see elm_layout_box_remove()
*
- * @ingroup Gengrid
+ * @ingroup Layout
*/
- EAPI void elm_gengrid_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_layout_box_prepend(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
/**
- * Get the selected item in a given gengrid widget
+ * Insert child to layout box part before a reference object.
*
- * @param obj The gengrid object.
- * @return The selected item's handleor @c NULL, if none is
- * selected at the moment (and on errors)
+ * @param obj the layout object
+ * @param part the box part to insert.
+ * @param child the child object to insert into box.
+ * @param reference another reference object to insert before in box.
*
- * This returns the selected item in @p obj. If multi selection is
- * enabled on @p obj (@see elm_gengrid_multi_select_set()), only
- * the first item in the list is selected, which might not be very
- * useful. For that case, see elm_gengrid_selected_items_get().
+ * Once the object is inserted, it will become child of the layout. Its
+ * lifetime will be bound to the layout, whenever the layout dies the child
+ * will be deleted automatically. One should use elm_layout_box_remove() to
+ * make this layout forget about the object.
*
- * @ingroup Gengrid
+ * @see elm_layout_box_append()
+ * @see elm_layout_box_prepend()
+ * @see elm_layout_box_insert_before()
+ * @see elm_layout_box_remove()
+ *
+ * @ingroup Layout
*/
- EAPI Elm_Gengrid_Item *elm_gengrid_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_layout_box_insert_before(Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1);
/**
- * Get <b>a list</b> of selected items in a given gengrid
+ * Insert child to layout box part at a given position.
*
- * @param obj The gengrid object.
- * @return The list of selected items or @c NULL, if none is
- * selected at the moment (and on errors)
+ * @param obj the layout object
+ * @param part the box part to insert.
+ * @param child the child object to insert into box.
+ * @param pos the numeric position >=0 to insert the child.
*
- * This returns a list of the selected items, in the order that
- * they appear in the grid. This list is only valid as long as no
- * more items are selected or unselected (or unselected implictly
- * by deletion). The list contains #Elm_Gengrid_Item pointers as
- * data, naturally.
+ * Once the object is inserted, it will become child of the layout. Its
+ * lifetime will be bound to the layout, whenever the layout dies the child
+ * will be deleted automatically. One should use elm_layout_box_remove() to
+ * make this layout forget about the object.
*
- * @see elm_gengrid_selected_item_get()
+ * @see elm_layout_box_append()
+ * @see elm_layout_box_prepend()
+ * @see elm_layout_box_insert_before()
+ * @see elm_layout_box_remove()
*
- * @ingroup Gengrid
- */
- EAPI const Eina_List *elm_gengrid_selected_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * @}
+ * @ingroup Layout
*/
-
+ EAPI void elm_layout_box_insert_at(Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1);
/**
- * @defgroup Clock Clock
+ * Remove a child of the given part box.
*
- * @image html img/widget/clock/preview-00.png
- * @image latex img/widget/clock/preview-00.eps
+ * @param obj The layout object
+ * @param part The box part name to remove child.
+ * @param child The object to remove from box.
+ * @return The object that was being used, or NULL if not found.
*
- * This is a @b digital clock widget. In its default theme, it has a
- * vintage "flipping numbers clock" appearance, which will animate
- * sheets of individual algarisms individually as time goes by.
+ * The object will be removed from the box part and its lifetime will
+ * not be handled by the layout anymore. This is equivalent to
+ * elm_layout_content_unset() for box.
*
- * A newly created clock will fetch system's time (already
- * considering local time adjustments) to start with, and will tick
- * accondingly. It may or may not show seconds.
+ * @see elm_layout_box_append()
+ * @see elm_layout_box_remove_all()
*
- * Clocks have an @b edition mode. When in it, the sheets will
- * display extra arrow indications on the top and bottom and the
- * user may click on them to raise or lower the time values. After
- * it's told to exit edition mode, it will keep ticking with that
- * new time set (it keeps the difference from local time).
+ * @ingroup Layout
+ */
+ EAPI Evas_Object *elm_layout_box_remove(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1, 2, 3);
+ /**
+ * Remove all child of the given part box.
*
- * Also, when under edition mode, user clicks on the cited arrows
- * which are @b held for some time will make the clock to flip the
- * sheet, thus editing the time, continuosly and automatically for
- * the user. The interval between sheet flips will keep growing in
- * time, so that it helps the user to reach a time which is distant
- * from the one set.
+ * @param obj The layout object
+ * @param part The box part name to remove child.
+ * @param clear If EINA_TRUE, then all objects will be deleted as
+ * well, otherwise they will just be removed and will be
+ * dangling on the canvas.
*
- * The time display is, by default, in military mode (24h), but an
- * am/pm indicator may be optionally shown, too, when it will
- * switch to 12h.
+ * The objects will be removed from the box part and their lifetime will
+ * not be handled by the layout anymore. This is equivalent to
+ * elm_layout_box_remove() for all box children.
*
- * Smart callbacks one can register to:
- * - "changed" - the clock's user changed the time
+ * @see elm_layout_box_append()
+ * @see elm_layout_box_remove()
*
- * Here is an example on its usage:
- * @li @ref clock_example
- */
-
- /**
- * @addtogroup Clock
- * @{
+ * @ingroup Layout
*/
-
+ EAPI void elm_layout_box_remove_all(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
/**
- * Identifiers for which clock digits should be editable, when a
- * clock widget is in edition mode. Values may be ORed together to
- * make a mask, naturally.
+ * Insert child to layout table part.
*
- * @see elm_clock_edit_set()
- * @see elm_clock_digit_edit_set()
- */
- typedef enum _Elm_Clock_Digedit
- {
- ELM_CLOCK_NONE = 0, /**< Default value. Means that all digits are editable, when in edition mode. */
- ELM_CLOCK_HOUR_DECIMAL = 1 << 0, /**< Decimal algarism of hours value should be editable */
- ELM_CLOCK_HOUR_UNIT = 1 << 1, /**< Unit algarism of hours value should be editable */
- ELM_CLOCK_MIN_DECIMAL = 1 << 2, /**< Decimal algarism of minutes value should be editable */
- ELM_CLOCK_MIN_UNIT = 1 << 3, /**< Unit algarism of minutes value should be editable */
- ELM_CLOCK_SEC_DECIMAL = 1 << 4, /**< Decimal algarism of seconds value should be editable */
- ELM_CLOCK_SEC_UNIT = 1 << 5, /**< Unit algarism of seconds value should be editable */
- ELM_CLOCK_ALL = (1 << 6) - 1 /**< All digits should be editable */
- } Elm_Clock_Digedit;
-
- /**
- * Add a new clock widget to the given parent Elementary
- * (container) object
+ * @param obj the layout object
+ * @param part the box part to pack child.
+ * @param child_obj the child object to pack into table.
+ * @param col the column to which the child should be added. (>= 0)
+ * @param row the row to which the child should be added. (>= 0)
+ * @param colspan how many columns should be used to store this object. (>=
+ * 1)
+ * @param rowspan how many rows should be used to store this object. (>= 1)
*
- * @param parent The parent object
- * @return a new clock widget handle or @c NULL, on errors
+ * Once the object is inserted, it will become child of the table. Its
+ * lifetime will be bound to the layout, and whenever the layout dies the
+ * child will be deleted automatically. One should use
+ * elm_layout_table_remove() to make this layout forget about the object.
*
- * This function inserts a new clock widget on the canvas.
+ * If @p colspan or @p rowspan are bigger than 1, that object will occupy
+ * more space than a single cell. For instance, the following code:
+ * @code
+ * elm_layout_table_pack(layout, "table_part", child, 0, 1, 3, 1);
+ * @endcode
*
- * @ingroup Clock
- */
- EAPI Evas_Object *elm_clock_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
-
- /**
- * Set a clock widget's time, programmatically
+ * Would result in an object being added like the following picture:
*
- * @param obj The clock widget object
- * @param hrs The hours to set
- * @param min The minutes to set
- * @param sec The secondes to set
+ * @image html layout_colspan.png
+ * @image latex layout_colspan.eps width=\textwidth
*
- * This function updates the time that is showed by the clock
- * widget.
+ * @see elm_layout_table_unpack()
+ * @see elm_layout_table_clear()
*
- * Values @b must be set within the following ranges:
- * - 0 - 23, for hours
- * - 0 - 59, for minutes
- * - 0 - 59, for seconds,
+ * @ingroup Layout
+ */
+ EAPI void elm_layout_table_pack(Evas_Object *obj, const char *part, Evas_Object *child_obj, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan) EINA_ARG_NONNULL(1);
+ /**
+ * Unpack (remove) a child of the given part table.
*
- * even if the clock is not in "military" mode.
+ * @param obj The layout object
+ * @param part The table part name to remove child.
+ * @param child_obj The object to remove from table.
+ * @return The object that was being used, or NULL if not found.
*
- * @warning The behavior for values set out of those ranges is @b
- * indefined.
+ * The object will be unpacked from the table part and its lifetime
+ * will not be handled by the layout anymore. This is equivalent to
+ * elm_layout_content_unset() for table.
*
- * @ingroup Clock
+ * @see elm_layout_table_pack()
+ * @see elm_layout_table_clear()
+ *
+ * @ingroup Layout
*/
- EAPI void elm_clock_time_set(Evas_Object *obj, int hrs, int min, int sec) EINA_ARG_NONNULL(1);
-
+ EAPI Evas_Object *elm_layout_table_unpack(Evas_Object *obj, const char *part, Evas_Object *child_obj) EINA_ARG_NONNULL(1, 2, 3);
/**
- * Get a clock widget's time values
+ * Remove all child of the given part table.
*
- * @param obj The clock object
- * @param[out] hrs Pointer to the variable to get the hours value
- * @param[out] min Pointer to the variable to get the minutes value
- * @param[out] sec Pointer to the variable to get the seconds value
+ * @param obj The layout object
+ * @param part The table part name to remove child.
+ * @param clear If EINA_TRUE, then all objects will be deleted as
+ * well, otherwise they will just be removed and will be
+ * dangling on the canvas.
*
- * This function gets the time set for @p obj, returning
- * it on the variables passed as the arguments to function
+ * The objects will be removed from the table part and their lifetime will
+ * not be handled by the layout anymore. This is equivalent to
+ * elm_layout_table_unpack() for all table children.
*
- * @note Use @c NULL pointers on the time values you're not
- * interested in: they'll be ignored by the function.
+ * @see elm_layout_table_pack()
+ * @see elm_layout_table_unpack()
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI void elm_clock_time_get(const Evas_Object *obj, int *hrs, int *min, int *sec) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_layout_table_clear(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
/**
- * Set whether a given clock widget is under <b>edition mode</b> or
- * under (default) displaying-only mode.
+ * Get the edje layout
*
- * @param obj The clock object
- * @param edit @c EINA_TRUE to put it in edition, @c EINA_FALSE to
- * put it back to "displaying only" mode
+ * @param obj The layout object
*
- * This function makes a clock's time to be editable or not <b>by
- * user interaction</b>. When in edition mode, clocks @b stop
- * ticking, until one brings them back to canonical mode. The
- * elm_clock_digit_edit_set() function will influence which digits
- * of the clock will be editable. By default, all of them will be
- * (#ELM_CLOCK_NONE).
+ * @return A Evas_Object with the edje layout settings loaded
+ * with function elm_layout_file_set
+ *
+ * This returns the edje object. It is not expected to be used to then
+ * swallow objects via edje_object_part_swallow() for example. Use
+ * elm_layout_content_set() instead so child object handling and sizing is
+ * done properly.
*
- * @note am/pm sheets, if being shown, will @b always be editable
- * under edition mode.
+ * @note This function should only be used if you really need to call some
+ * low level Edje function on this edje object. All the common stuff (setting
+ * text, emitting signals, hooking callbacks to signals, etc.) can be done
+ * with proper elementary functions.
*
- * @see elm_clock_edit_get()
+ * @see elm_object_signal_callback_add()
+ * @see elm_object_signal_emit()
+ * @see elm_object_text_part_set()
+ * @see elm_layout_content_set()
+ * @see elm_layout_box_append()
+ * @see elm_layout_table_pack()
+ * @see elm_layout_data_get()
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI void elm_clock_edit_set(Evas_Object *obj, Eina_Bool edit) EINA_ARG_NONNULL(1);
-
+ EAPI Evas_Object *elm_layout_edje_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Retrieve whether a given clock widget is under <b>edition
- * mode</b> or under (default) displaying-only mode.
+ * Get the edje data from the given layout
*
- * @param obj The clock object
- * @param edit @c EINA_TRUE, if it's in edition mode, @c EINA_FALSE
- * otherwise
+ * @param obj The layout object
+ * @param key The data key
*
- * This function retrieves whether the clock's time can be edited
- * or not by user interaction.
+ * @return The edje data string
*
- * @see elm_clock_edit_set() for more details
+ * This function fetches data specified inside the edje theme of this layout.
+ * This function return NULL if data is not found.
*
- * @ingroup Clock
+ * In EDC this comes from a data block within the group block that @p
+ * obj was loaded from. E.g.
+ *
+ * @code
+ * collections {
+ * group {
+ * name: "a_group";
+ * data {
+ * item: "key1" "value1";
+ * item: "key2" "value2";
+ * }
+ * }
+ * }
+ * @endcode
+ *
+ * @ingroup Layout
*/
- EAPI Eina_Bool elm_clock_edit_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI const char *elm_layout_data_get(const Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
/**
- * Set what digits of the given clock widget should be editable
- * when in edition mode.
+ * Eval sizing
*
- * @param obj The clock object
- * @param digedit Bit mask indicating the digits to be editable
- * (values in #Elm_Clock_Digedit).
+ * @param obj The layout object
*
- * If the @p digedit param is #ELM_CLOCK_NONE, editing will be
- * disabled on @p obj (same effect as elm_clock_edit_set(), with @c
- * EINA_FALSE).
+ * Manually forces a sizing re-evaluation. This is useful when the minimum
+ * size required by the edje theme of this layout has changed. The change on
+ * the minimum size required by the edje theme is not immediately reported to
+ * the elementary layout, so one needs to call this function in order to tell
+ * the widget (layout) that it needs to reevaluate its own size.
*
- * @see elm_clock_digit_edit_get()
+ * The minimum size of the theme is calculated based on minimum size of
+ * parts, the size of elements inside containers like box and table, etc. All
+ * of this can change due to state changes, and that's when this function
+ * should be called.
*
- * @ingroup Clock
+ * Also note that a standard signal of "size,eval" "elm" emitted from the
+ * edje object will cause this to happen too.
+ *
+ * @ingroup Layout
*/
- EAPI void elm_clock_digit_edit_set(Evas_Object *obj, Elm_Clock_Digedit digedit) EINA_ARG_NONNULL(1);
+ EAPI void elm_layout_sizing_eval(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Retrieve what digits of the given clock widget should be
- * editable when in edition mode.
+ * Sets a specific cursor for an edje part.
*
- * @param obj The clock object
- * @return Bit mask indicating the digits to be editable
- * (values in #Elm_Clock_Digedit).
+ * @param obj The layout object.
+ * @param part_name a part from loaded edje group.
+ * @param cursor cursor name to use, see Elementary_Cursor.h
*
- * @see elm_clock_digit_edit_set() for more details
+ * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
+ * part not exists or it has "mouse_events: 0".
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI Elm_Clock_Digedit elm_clock_digit_edit_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_layout_part_cursor_set(Evas_Object *obj, const char *part_name, const char *cursor) EINA_ARG_NONNULL(1, 2);
/**
- * Set if the given clock widget must show hours in military or
- * am/pm mode
- *
- * @param obj The clock object
- * @param am_pm @c EINA_TRUE to put it in am/pm mode, @c EINA_FALSE
- * to military mode
- *
- * This function sets if the clock must show hours in military or
- * am/pm mode. In some countries like Brazil the military mode
- * (00-24h-format) is used, in opposition to the USA, where the
- * am/pm mode is more commonly used.
+ * Get the cursor to be shown when mouse is over an edje part
*
- * @see elm_clock_show_am_pm_get()
+ * @param obj The layout object.
+ * @param part_name a part from loaded edje group.
+ * @return the cursor name.
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI void elm_clock_show_am_pm_set(Evas_Object *obj, Eina_Bool am_pm) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_layout_part_cursor_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
/**
- * Get if the given clock widget shows hours in military or am/pm
- * mode
- *
- * @param obj The clock object
- * @return @c EINA_TRUE, if in am/pm mode, @c EINA_FALSE if in
- * military
- *
- * This function gets if the clock shows hours in military or am/pm
- * mode.
+ * Unsets a cursor previously set with elm_layout_part_cursor_set().
*
- * @see elm_clock_show_am_pm_set() for more details
+ * @param obj The layout object.
+ * @param part_name a part from loaded edje group, that had a cursor set
+ * with elm_layout_part_cursor_set().
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI Eina_Bool elm_clock_show_am_pm_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_layout_part_cursor_unset(Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
/**
- * Set if the given clock widget must show time with seconds or not
- *
- * @param obj The clock object
- * @param seconds @c EINA_TRUE to show seconds, @c EINA_FALSE otherwise
+ * Sets a specific cursor style for an edje part.
*
- * This function sets if the given clock must show or not elapsed
- * seconds. By default, they are @b not shown.
+ * @param obj The layout object.
+ * @param part_name a part from loaded edje group.
+ * @param style the theme style to use (default, transparent, ...)
*
- * @see elm_clock_show_seconds_get()
+ * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
+ * part not exists or it did not had a cursor set.
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI void elm_clock_show_seconds_set(Evas_Object *obj, Eina_Bool seconds) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_layout_part_cursor_style_set(Evas_Object *obj, const char *part_name, const char *style) EINA_ARG_NONNULL(1, 2);
/**
- * Get whether the given clock widget is showing time with seconds
- * or not
- *
- * @param obj The clock object
- * @return @c EINA_TRUE if it's showing seconds, @c EINA_FALSE otherwise
+ * Gets a specific cursor style for an edje part.
*
- * This function gets whether @p obj is showing or not the elapsed
- * seconds.
+ * @param obj The layout object.
+ * @param part_name a part from loaded edje group.
*
- * @see elm_clock_show_seconds_set()
+ * @return the theme style in use, defaults to "default". If the
+ * object does not have a cursor set, then NULL is returned.
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI Eina_Bool elm_clock_show_seconds_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_layout_part_cursor_style_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
/**
- * Set the interval on time updates for an user mouse button hold
- * on clock widgets' time edition.
- *
- * @param obj The clock object
- * @param interval The (first) interval value in seconds
- *
- * This interval value is @b decreased while the user holds the
- * mouse pointer either incrementing or decrementing a given the
- * clock digit's value.
- *
- * This helps the user to get to a given time distant from the
- * current one easier/faster, as it will start to flip quicker and
- * quicker on mouse button holds.
+ * Sets if the cursor set should be searched on the theme or should use
+ * the provided by the engine, only.
*
- * The calculation for the next flip interval value, starting from
- * the one set with this call, is the previous interval divided by
- * 1.05, so it decreases a little bit.
+ * @note before you set if should look on theme you should define a
+ * cursor with elm_layout_part_cursor_set(). By default it will only
+ * look for cursors provided by the engine.
*
- * The default starting interval value for automatic flips is
- * @b 0.85 seconds.
+ * @param obj The layout object.
+ * @param part_name a part from loaded edje group.
+ * @param engine_only if cursors should be just provided by the engine
+ * or should also search on widget's theme as well
*
- * @see elm_clock_interval_get()
+ * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
+ * part not exists or it did not had a cursor set.
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI void elm_clock_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_layout_part_cursor_engine_only_set(Evas_Object *obj, const char *part_name, Eina_Bool engine_only) EINA_ARG_NONNULL(1, 2);
/**
- * Get the interval on time updates for an user mouse button hold
- * on clock widgets' time edition.
+ * Gets a specific cursor engine_only for an edje part.
*
- * @param obj The clock object
- * @return The (first) interval value, in seconds, set on it
+ * @param obj The layout object.
+ * @param part_name a part from loaded edje group.
*
- * @see elm_clock_interval_set() for more details
+ * @return whenever the cursor is just provided by engine or also from theme.
*
- * @ingroup Clock
+ * @ingroup Layout
*/
- EAPI double elm_clock_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_layout_part_cursor_engine_only_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @def elm_layout_icon_set
+ * Convienience macro to set the icon object in a layout that follows the
+ * Elementary naming convention for its parts.
+ *
+ * @ingroup Layout
+ */
+#define elm_layout_icon_set(_ly, _obj) \
+ do { \
+ const char *sig; \
+ elm_layout_content_set((_ly), "elm.swallow.icon", (_obj)); \
+ if ((_obj)) sig = "elm,state,icon,visible"; \
+ else sig = "elm,state,icon,hidden"; \
+ elm_object_signal_emit((_ly), sig, "elm"); \
+ } while (0)
+
+/**
+ * @def elm_layout_icon_get
+ * Convienience macro to get the icon object from a layout that follows the
+ * Elementary naming convention for its parts.
+ *
+ * @ingroup Layout
+ */
+#define elm_layout_icon_get(_ly) \
+ elm_layout_content_get((_ly), "elm.swallow.icon")
+
+/**
+ * @def elm_layout_end_set
+ * Convienience macro to set the end object in a layout that follows the
+ * Elementary naming convention for its parts.
+ *
+ * @ingroup Layout
+ */
+#define elm_layout_end_set(_ly, _obj) \
+ do { \
+ const char *sig; \
+ elm_layout_content_set((_ly), "elm.swallow.end", (_obj)); \
+ if ((_obj)) sig = "elm,state,end,visible"; \
+ else sig = "elm,state,end,hidden"; \
+ elm_object_signal_emit((_ly), sig, "elm"); \
+ } while (0)
+
+/**
+ * @def elm_layout_end_get
+ * Convienience macro to get the end object in a layout that follows the
+ * Elementary naming convention for its parts.
+ *
+ * @ingroup Layout
+ */
+#define elm_layout_end_get(_ly) \
+ elm_layout_content_get((_ly), "elm.swallow.end")
+
+/**
+ * @def elm_layout_label_set
+ * Convienience macro to set the label in a layout that follows the
+ * Elementary naming convention for its parts.
+ *
+ * @ingroup Layout
+ * @deprecated use elm_object_text_* instead.
+ */
+#define elm_layout_label_set(_ly, _txt) \
+ elm_layout_text_set((_ly), "elm.text", (_txt))
+
+/**
+ * @def elm_layout_label_get
+ * Convienience macro to get the label in a layout that follows the
+ * Elementary naming convention for its parts.
+ *
+ * @ingroup Layout
+ * @deprecated use elm_object_text_* instead.
+ */
+#define elm_layout_label_get(_ly) \
+ elm_layout_text_get((_ly), "elm.text")
- /**
- * @}
+ /* smart callbacks called:
+ * "theme,changed" - when elm theme is changed.
*/
/**
- * @defgroup Layout Layout
- *
- * @image html img/widget/layout/preview-00.png
- * @image latex img/widget/layout/preview-00.eps width=\textwidth
- *
- * @image html img/layout-predefined.png
- * @image latex img/layout-predefined.eps width=\textwidth
- *
- * This is a container widget that takes a standard Edje design file and
- * wraps it very thinly in a widget.
- *
- * An Edje design (theme) file has a very wide range of possibilities to
- * describe the behavior of elements added to the Layout. Check out the Edje
- * documentation and the EDC reference to get more information about what can
- * be done with Edje.
- *
- * Just like @ref List, @ref Box, and other container widgets, any
- * object added to the Layout will become its child, meaning that it will be
- * deleted if the Layout is deleted, move if the Layout is moved, and so on.
- *
- * The Layout widget can contain as many Contents, Boxes or Tables as
- * described in its theme file. For instance, objects can be added to
- * different Tables by specifying the respective Table part names. The same
- * is valid for Content and Box.
- *
- * The objects added as child of the Layout will behave as described in the
- * part description where they were added. There are 3 possible types of
- * parts where a child can be added:
- *
- * @section secContent Content (SWALLOW part)
+ * @defgroup Notify Notify
*
- * Only one object can be added to the @c SWALLOW part (but you still can
- * have many @c SWALLOW parts and one object on each of them). Use the @c
- * elm_layout_content_* set of functions to set, retrieve and unset objects
- * as content of the @c SWALLOW. After being set to this part, the object
- * size, position, visibility, clipping and other description properties
- * will be totally controled by the description of the given part (inside
- * the Edje theme file).
+ * @image html img/widget/notify/preview-00.png
+ * @image latex img/widget/notify/preview-00.eps
*
- * One can use @c evas_object_size_hint_* functions on the child to have some
- * kind of control over its behavior, but the resulting behavior will still
- * depend heavily on the @c SWALLOW part description.
+ * Display a container in a particular region of the parent(top, bottom,
+ * etc. A timeout can be set to automatically hide the notify. This is so
+ * that, after an evas_object_show() on a notify object, if a timeout was set
+ * on it, it will @b automatically get hidden after that time.
*
- * The Edje theme also can change the part description, based on signals or
- * scripts running inside the theme. This change can also be animated. All of
- * this will affect the child object set as content accordingly. The object
- * size will be changed if the part size is changed, it will animate move if
- * the part is moving, and so on.
+ * Signals that you can add callbacks for are:
+ * @li "timeout" - when timeout happens on notify and it's hidden
+ * @li "block,clicked" - when a click outside of the notify happens
*
- * The following picture demonstrates a Layout widget with a child object
- * added to its @c SWALLOW:
+ * @ref tutorial_notify show usage of the API.
*
- * @image html layout_swallow.png
- * @image latex layout_swallow.eps width=\textwidth
+ * @{
+ */
+ /**
+ * @brief Possible orient values for notify.
*
- * @section secBox Box (BOX part)
+ * This values should be used in conjunction to elm_notify_orient_set() to
+ * set the position in which the notify should appear(relative to its parent)
+ * and in conjunction with elm_notify_orient_get() to know where the notify
+ * is appearing.
+ */
+ typedef enum _Elm_Notify_Orient
+ {
+ ELM_NOTIFY_ORIENT_TOP, /**< Notify should appear in the top of parent, default */
+ ELM_NOTIFY_ORIENT_CENTER, /**< Notify should appear in the center of parent */
+ ELM_NOTIFY_ORIENT_BOTTOM, /**< Notify should appear in the bottom of parent */
+ ELM_NOTIFY_ORIENT_LEFT, /**< Notify should appear in the left of parent */
+ ELM_NOTIFY_ORIENT_RIGHT, /**< Notify should appear in the right of parent */
+ ELM_NOTIFY_ORIENT_TOP_LEFT, /**< Notify should appear in the top left of parent */
+ ELM_NOTIFY_ORIENT_TOP_RIGHT, /**< Notify should appear in the top right of parent */
+ ELM_NOTIFY_ORIENT_BOTTOM_LEFT, /**< Notify should appear in the bottom left of parent */
+ ELM_NOTIFY_ORIENT_BOTTOM_RIGHT, /**< Notify should appear in the bottom right of parent */
+ ELM_NOTIFY_ORIENT_LAST /**< Sentinel value, @b don't use */
+ } Elm_Notify_Orient;
+ /**
+ * @brief Add a new notify to the parent
*
- * An Edje @c BOX part is very similar to the Elementary @ref Box widget. It
- * allows one to add objects to the box and have them distributed along its
- * area, accordingly to the specified @a layout property (now by @a layout we
- * mean the chosen layouting design of the Box, not the Layout widget
- * itself).
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
+ EAPI Evas_Object *elm_notify_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the content of the notify widget
*
- * A similar effect for having a box with its position, size and other things
- * controled by the Layout theme would be to create an Elementary @ref Box
- * widget and add it as a Content in the @c SWALLOW part.
+ * @param obj The notify object
+ * @param content The content will be filled in this notify object
*
- * The main difference of using the Layout Box is that its behavior, the box
- * properties like layouting format, padding, align, etc. will be all
- * controled by the theme. This means, for example, that a signal could be
- * sent to the Layout theme (with elm_object_signal_emit()) and the theme
- * handled the signal by changing the box padding, or align, or both. Using
- * the Elementary @ref Box widget is not necessarily harder or easier, it
- * just depends on the circunstances and requirements.
+ * Once the content object is set, a previously set one will be deleted. If
+ * you want to keep that old content object, use the
+ * elm_notify_content_unset() function.
+ */
+ EAPI void elm_notify_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Unset the content of the notify widget
*
- * The Layout Box can be used through the @c elm_layout_box_* set of
- * functions.
+ * @param obj The notify object
+ * @return The content that was being used
*
- * The following picture demonstrates a Layout widget with many child objects
- * added to its @c BOX part:
+ * Unparent and return the content object which was set for this widget
*
- * @image html layout_box.png
- * @image latex layout_box.eps width=\textwidth
+ * @see elm_notify_content_set()
+ */
+ EAPI Evas_Object *elm_notify_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Return the content of the notify widget
*
- * @section secTable Table (TABLE part)
+ * @param obj The notify object
+ * @return The content that is being used
*
- * Just like the @ref secBox, the Layout Table is very similar to the
- * Elementary @ref Table widget. It allows one to add objects to the Table
- * specifying the row and column where the object should be added, and any
- * column or row span if necessary.
+ * @see elm_notify_content_set()
+ */
+ EAPI Evas_Object *elm_notify_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the notify parent
*
- * Again, we could have this design by adding a @ref Table widget to the @c
- * SWALLOW part using elm_layout_content_set(). The same difference happens
- * here when choosing to use the Layout Table (a @c TABLE part) instead of
- * the @ref Table plus @c SWALLOW part. It's just a matter of convenience.
+ * @param obj The notify object
+ * @param content The new parent
*
- * The Layout Table can be used through the @c elm_layout_table_* set of
- * functions.
+ * Once the parent object is set, a previously set one will be disconnected
+ * and replaced.
+ */
+ EAPI void elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the notify parent
*
- * The following picture demonstrates a Layout widget with many child objects
- * added to its @c TABLE part:
+ * @param obj The notify object
+ * @return The parent
*
- * @image html layout_table.png
- * @image latex layout_table.eps width=\textwidth
+ * @see elm_notify_parent_set()
+ */
+ EAPI Evas_Object *elm_notify_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the orientation
*
- * @section secPredef Predefined Layouts
+ * @param obj The notify object
+ * @param orient The new orientation
*
- * Another interesting thing about the Layout widget is that it offers some
- * predefined themes that come with the default Elementary theme. These
- * themes can be set by the call elm_layout_theme_set(), and provide some
- * basic functionality depending on the theme used.
+ * Sets the position in which the notify will appear in its parent.
*
- * Most of them already send some signals, some already provide a toolbar or
- * back and next buttons.
+ * @see @ref Elm_Notify_Orient for possible values.
+ */
+ EAPI void elm_notify_orient_set(Evas_Object *obj, Elm_Notify_Orient orient) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Return the orientation
+ * @param obj The notify object
+ * @return The orientation of the notification
*
- * These are available predefined theme layouts. All of them have class = @c
- * layout, group = @c application, and style = one of the following options:
+ * @see elm_notify_orient_set()
+ * @see Elm_Notify_Orient
+ */
+ EAPI Elm_Notify_Orient elm_notify_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the time interval after which the notify window is going to be
+ * hidden.
*
- * @li @c toolbar-content - application with toolbar and main content area
- * @li @c toolbar-content-back - application with toolbar and main content
- * area with a back button and title area
- * @li @c toolbar-content-back-next - application with toolbar and main
- * content area with a back and next buttons and title area
- * @li @c content-back - application with a main content area with a back
- * button and title area
- * @li @c content-back-next - application with a main content area with a
- * back and next buttons and title area
- * @li @c toolbar-vbox - application with toolbar and main content area as a
- * vertical box
- * @li @c toolbar-table - application with toolbar and main content area as a
- * table
+ * @param obj The notify object
+ * @param time The timeout in seconds
*
- * @section secExamples Examples
+ * This function sets a timeout and starts the timer controlling when the
+ * notify is hidden. Since calling evas_object_show() on a notify restarts
+ * the timer controlling when the notify is hidden, setting this before the
+ * notify is shown will in effect mean starting the timer when the notify is
+ * shown.
*
- * Some examples of the Layout widget can be found here:
- * @li @ref layout_example_01
- * @li @ref layout_example_02
- * @li @ref layout_example_03
- * @li @ref layout_example_edc
+ * @note Set a value <= 0.0 to disable a running timer.
*
+ * @note If the value > 0.0 and the notify is previously visible, the
+ * timer will be started with this value, canceling any running timer.
*/
-
+ EAPI void elm_notify_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
/**
- * Add a new layout to the parent
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @see elm_layout_file_set()
- * @see elm_layout_theme_set()
+ * @brief Return the timeout value (in seconds)
+ * @param obj the notify object
*
- * @ingroup Layout
+ * @see elm_notify_timeout_set()
*/
- EAPI Evas_Object *elm_layout_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI double elm_notify_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the file that will be used as layout
+ * @brief Sets whether events should be passed to by a click outside
+ * its area.
*
- * @param obj The layout object
- * @param file The path to file (edj) that will be used as layout
- * @param group The group that the layout belongs in edje file
+ * @param obj The notify object
+ * @param repeats EINA_TRUE Events are repeats, else no
*
- * @return (1 = success, 0 = error)
+ * When true if the user clicks outside the window the events will be caught
+ * by the others widgets, else the events are blocked.
*
- * @ingroup Layout
+ * @note The default value is EINA_TRUE.
*/
- EAPI Eina_Bool elm_layout_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1);
+ EAPI void elm_notify_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
/**
- * Set the edje group from the elementary theme that will be used as layout
- *
- * @param obj The layout object
- * @param clas the clas of the group
- * @param group the group
- * @param style the style to used
- *
- * @return (1 = success, 0 = error)
+ * @brief Return true if events are repeat below the notify object
+ * @param obj the notify object
*
- * @ingroup Layout
+ * @see elm_notify_repeat_events_set()
*/
- EAPI Eina_Bool elm_layout_theme_set(Evas_Object *obj, const char *clas, const char *group, const char *style) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_notify_repeat_events_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the layout content.
+ * @}
+ */
+
+ /**
+ * @defgroup Hover Hover
*
- * @param obj The layout object
- * @param swallow The swallow part name in the edje file
- * @param content The child that will be added in this layout object
+ * @image html img/widget/hover/preview-00.png
+ * @image latex img/widget/hover/preview-00.eps
*
- * Once the content object is set, a previously set one will be deleted.
- * If you want to keep that old content object, use the
- * elm_layout_content_unset() function.
+ * A Hover object will hover over its @p parent object at the @p target
+ * location. Anything in the background will be given a darker coloring to
+ * indicate that the hover object is on top (at the default theme). When the
+ * hover is clicked it is dismissed(hidden), if the contents of the hover are
+ * clicked that @b doesn't cause the hover to be dismissed.
*
- * @note In an Edje theme, the part used as a content container is called @c
- * SWALLOW. This is why the parameter name is called @p swallow, but it is
- * expected to be a part name just like the second parameter of
- * elm_layout_box_append().
+ * @note The hover object will take up the entire space of @p target
+ * object.
*
- * @see elm_layout_box_append()
- * @see elm_layout_content_get()
- * @see elm_layout_content_unset()
- * @see @ref secBox
+ * Elementary has the following styles for the hover widget:
+ * @li default
+ * @li popout
+ * @li menu
+ * @li hoversel_vertical
*
- * @ingroup Layout
- */
- EAPI void elm_layout_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
- /**
- * Get the child object in the given content part.
+ * The following are the available position for content:
+ * @li left
+ * @li top-left
+ * @li top
+ * @li top-right
+ * @li right
+ * @li bottom-right
+ * @li bottom
+ * @li bottom-left
+ * @li middle
+ * @li smart
*
- * @param obj The layout object
- * @param swallow The SWALLOW part to get its content
+ * Signals that you can add callbacks for are:
+ * @li "clicked" - the user clicked the empty space in the hover to dismiss
+ * @li "smart,changed" - a content object placed under the "smart"
+ * policy was replaced to a new slot direction.
*
- * @return The swallowed object or NULL if none or an error occurred
+ * See @ref tutorial_hover for more information.
*
- * @see elm_layout_content_set()
+ * @{
+ */
+ typedef enum _Elm_Hover_Axis
+ {
+ ELM_HOVER_AXIS_NONE, /**< ELM_HOVER_AXIS_NONE -- no prefered orientation */
+ ELM_HOVER_AXIS_HORIZONTAL, /**< ELM_HOVER_AXIS_HORIZONTAL -- horizontal */
+ ELM_HOVER_AXIS_VERTICAL, /**< ELM_HOVER_AXIS_VERTICAL -- vertical */
+ ELM_HOVER_AXIS_BOTH /**< ELM_HOVER_AXIS_BOTH -- both */
+ } Elm_Hover_Axis;
+ /**
+ * @brief Adds a hover object to @p parent
*
- * @ingroup Layout
+ * @param parent The parent object
+ * @return The hover object or NULL if one could not be created
*/
- EAPI Evas_Object *elm_layout_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_hover_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * Unset the layout content.
+ * @brief Sets the target object for the hover.
*
- * @param obj The layout object
- * @param swallow The swallow part name in the edje file
- * @return The content that was being used
+ * @param obj The hover object
+ * @param target The object to center the hover onto. The hover
*
- * Unparent and return the content object which was set for this part.
+ * This function will cause the hover to be centered on the target object.
+ */
+ EAPI void elm_hover_target_set(Evas_Object *obj, Evas_Object *target) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Gets the target object for the hover.
*
- * @see elm_layout_content_set()
+ * @param obj The hover object
+ * @param parent The object to locate the hover over.
*
- * @ingroup Layout
+ * @see elm_hover_target_set()
*/
- EAPI Evas_Object *elm_layout_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_hover_target_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Set the text of the given part
+ * @brief Sets the parent object for the hover.
*
- * @param obj The layout object
- * @param part The TEXT part where to set the text
- * @param text The text to set
+ * @param obj The hover object
+ * @param parent The object to locate the hover over.
*
- * @ingroup Layout
- * @deprecated use elm_object_text_* instead.
+ * This function will cause the hover to take up the entire space that the
+ * parent object fills.
*/
- EINA_DEPRECATED EAPI void elm_layout_text_set(Evas_Object *obj, const char *part, const char *text) EINA_ARG_NONNULL(1);
+ EAPI void elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * Get the text set in the given part
- *
- * @param obj The layout object
- * @param part The TEXT part to retrieve the text off
+ * @brief Gets the parent object for the hover.
*
- * @return The text set in @p part
+ * @param obj The hover object
+ * @return The parent object to locate the hover over.
*
- * @ingroup Layout
- * @deprecated use elm_object_text_* instead.
+ * @see elm_hover_parent_set()
*/
- EINA_DEPRECATED EAPI const char *elm_layout_text_get(const Evas_Object *obj, const char *part) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Append child to layout box part.
- *
- * @param obj the layout object
- * @param part the box part to which the object will be appended.
- * @param child the child object to append to box.
+ * @brief Sets the content of the hover object and the direction in which it
+ * will pop out.
*
- * Once the object is appended, it will become child of the layout. Its
- * lifetime will be bound to the layout, whenever the layout dies the child
- * will be deleted automatically. One should use elm_layout_box_remove() to
- * make this layout forget about the object.
+ * @param obj The hover object
+ * @param swallow The direction that the object will be displayed
+ * at. Accepted values are "left", "top-left", "top", "top-right",
+ * "right", "bottom-right", "bottom", "bottom-left", "middle" and
+ * "smart".
+ * @param content The content to place at @p swallow
*
- * @see elm_layout_box_prepend()
- * @see elm_layout_box_insert_before()
- * @see elm_layout_box_insert_at()
- * @see elm_layout_box_remove()
+ * Once the content object is set for a given direction, a previously
+ * set one (on the same direction) will be deleted. If you want to
+ * keep that old content object, use the elm_hover_content_unset()
+ * function.
*
- * @ingroup Layout
+ * All directions may have contents at the same time, except for
+ * "smart". This is a special placement hint and its use case
+ * independs of the calculations coming from
+ * elm_hover_best_content_location_get(). Its use is for cases when
+ * one desires only one hover content, but with a dinamic special
+ * placement within the hover area. The content's geometry, whenever
+ * it changes, will be used to decide on a best location not
+ * extrapolating the hover's parent object view to show it in (still
+ * being the hover's target determinant of its medium part -- move and
+ * resize it to simulate finger sizes, for example). If one of the
+ * directions other than "smart" are used, a previously content set
+ * using it will be deleted, and vice-versa.
*/
- EAPI void elm_layout_box_append(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
+ EAPI void elm_hover_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
/**
- * Prepend child to layout box part.
- *
- * @param obj the layout object
- * @param part the box part to prepend.
- * @param child the child object to prepend to box.
+ * @brief Get the content of the hover object, in a given direction.
*
- * Once the object is prepended, it will become child of the layout. Its
- * lifetime will be bound to the layout, whenever the layout dies the child
- * will be deleted automatically. One should use elm_layout_box_remove() to
- * make this layout forget about the object.
+ * Return the content object which was set for this widget in the
+ * @p swallow direction.
*
- * @see elm_layout_box_append()
- * @see elm_layout_box_insert_before()
- * @see elm_layout_box_insert_at()
- * @see elm_layout_box_remove()
+ * @param obj The hover object
+ * @param swallow The direction that the object was display at.
+ * @return The content that was being used
*
- * @ingroup Layout
+ * @see elm_hover_content_set()
*/
- EAPI void elm_layout_box_prepend(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_hover_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
/**
- * Insert child to layout box part before a reference object.
- *
- * @param obj the layout object
- * @param part the box part to insert.
- * @param child the child object to insert into box.
- * @param reference another reference object to insert before in box.
+ * @brief Unset the content of the hover object, in a given direction.
*
- * Once the object is inserted, it will become child of the layout. Its
- * lifetime will be bound to the layout, whenever the layout dies the child
- * will be deleted automatically. One should use elm_layout_box_remove() to
- * make this layout forget about the object.
+ * Unparent and return the content object set at @p swallow direction.
*
- * @see elm_layout_box_append()
- * @see elm_layout_box_prepend()
- * @see elm_layout_box_insert_before()
- * @see elm_layout_box_remove()
+ * @param obj The hover object
+ * @param swallow The direction that the object was display at.
+ * @return The content that was being used.
*
- * @ingroup Layout
+ * @see elm_hover_content_set()
*/
- EAPI void elm_layout_box_insert_before(Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_hover_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
/**
- * Insert child to layout box part at a given position.
+ * @brief Returns the best swallow location for content in the hover.
*
- * @param obj the layout object
- * @param part the box part to insert.
- * @param child the child object to insert into box.
- * @param pos the numeric position >=0 to insert the child.
+ * @param obj The hover object
+ * @param pref_axis The preferred orientation axis for the hover object to use
+ * @return The edje location to place content into the hover or @c
+ * NULL, on errors.
*
- * Once the object is inserted, it will become child of the layout. Its
- * lifetime will be bound to the layout, whenever the layout dies the child
- * will be deleted automatically. One should use elm_layout_box_remove() to
- * make this layout forget about the object.
+ * Best is defined here as the location at which there is the most available
+ * space.
*
- * @see elm_layout_box_append()
- * @see elm_layout_box_prepend()
- * @see elm_layout_box_insert_before()
- * @see elm_layout_box_remove()
+ * @p pref_axis may be one of
+ * - @c ELM_HOVER_AXIS_NONE -- no prefered orientation
+ * - @c ELM_HOVER_AXIS_HORIZONTAL -- horizontal
+ * - @c ELM_HOVER_AXIS_VERTICAL -- vertical
+ * - @c ELM_HOVER_AXIS_BOTH -- both
+ *
+ * If ELM_HOVER_AXIS_HORIZONTAL is choosen the returned position will
+ * nescessarily be along the horizontal axis("left" or "right"). If
+ * ELM_HOVER_AXIS_VERTICAL is choosen the returned position will nescessarily
+ * be along the vertical axis("top" or "bottom"). Chossing
+ * ELM_HOVER_AXIS_BOTH or ELM_HOVER_AXIS_NONE has the same effect and the
+ * returned position may be in either axis.
*
- * @ingroup Layout
+ * @see elm_hover_content_set()
*/
- EAPI void elm_layout_box_insert_at(Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis) EINA_ARG_NONNULL(1);
/**
- * Remove a child of the given part box.
+ * @}
+ */
+
+ /* entry */
+ /**
+ * @defgroup Entry Entry
*
- * @param obj The layout object
- * @param part The box part name to remove child.
- * @param child The object to remove from box.
- * @return The object that was being used, or NULL if not found.
+ * @image html img/widget/entry/preview-00.png
+ * @image latex img/widget/entry/preview-00.eps width=\textwidth
+ * @image html img/widget/entry/preview-01.png
+ * @image latex img/widget/entry/preview-01.eps width=\textwidth
+ * @image html img/widget/entry/preview-02.png
+ * @image latex img/widget/entry/preview-02.eps width=\textwidth
+ * @image html img/widget/entry/preview-03.png
+ * @image latex img/widget/entry/preview-03.eps width=\textwidth
*
- * The object will be removed from the box part and its lifetime will
- * not be handled by the layout anymore. This is equivalent to
- * elm_layout_content_unset() for box.
+ * An entry is a convenience widget which shows a box that the user can
+ * enter text into. Entries by default don't scroll, so they grow to
+ * accomodate the entire text, resizing the parent window as needed. This
+ * can be changed with the elm_entry_scrollable_set() function.
*
- * @see elm_layout_box_append()
- * @see elm_layout_box_remove_all()
+ * They can also be single line or multi line (the default) and when set
+ * to multi line mode they support text wrapping in any of the modes
+ * indicated by #Elm_Wrap_Type.
*
- * @ingroup Layout
- */
- EAPI Evas_Object *elm_layout_box_remove(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1, 2, 3);
- /**
- * Remove all child of the given part box.
+ * Other features include password mode, filtering of inserted text with
+ * elm_entry_text_filter_append() and related functions, inline "items" and
+ * formatted markup text.
*
- * @param obj The layout object
- * @param part The box part name to remove child.
- * @param clear If EINA_TRUE, then all objects will be deleted as
- * well, otherwise they will just be removed and will be
- * dangling on the canvas.
+ * @section entry-markup Formatted text
*
- * The objects will be removed from the box part and their lifetime will
- * not be handled by the layout anymore. This is equivalent to
- * elm_layout_box_remove() for all box children.
+ * The markup tags supported by the Entry are defined by the theme, but
+ * even when writing new themes or extensions it's a good idea to stick to
+ * a sane default, to maintain coherency and avoid application breakages.
+ * Currently defined by the default theme are the following tags:
+ * @li \<br\>: Inserts a line break.
+ * @li \<ps\>: Inserts a paragraph separator. This is preferred over line
+ * breaks.
+ * @li \<tab\>: Inserts a tab.
+ * @li \<em\>...\</em\>: Emphasis. Sets the @em oblique style for the
+ * enclosed text.
+ * @li \<b\>...\</b\>: Sets the @b bold style for the enclosed text.
+ * @li \<link\>...\</link\>: Underlines the enclosed text.
+ * @li \<hilight\>...\</hilight\>: Hilights the enclosed text.
*
- * @see elm_layout_box_append()
- * @see elm_layout_box_remove()
+ * @section entry-special Special markups
*
- * @ingroup Layout
- */
- EAPI void elm_layout_box_remove_all(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
- /**
- * Insert child to layout table part.
+ * Besides those used to format text, entries support two special markup
+ * tags used to insert clickable portions of text or items inlined within
+ * the text.
*
- * @param obj the layout object
- * @param part the box part to pack child.
- * @param child_obj the child object to pack into table.
- * @param col the column to which the child should be added. (>= 0)
- * @param row the row to which the child should be added. (>= 0)
- * @param colspan how many columns should be used to store this object. (>=
- * 1)
- * @param rowspan how many rows should be used to store this object. (>= 1)
+ * @subsection entry-anchors Anchors
*
- * Once the object is inserted, it will become child of the table. Its
- * lifetime will be bound to the layout, and whenever the layout dies the
- * child will be deleted automatically. One should use
- * elm_layout_table_remove() to make this layout forget about the object.
+ * Anchors are similar to HTML anchors. Text can be surrounded by \<a\> and
+ * \</a\> tags and an event will be generated when this text is clicked,
+ * like this:
*
- * If @p colspan or @p rowspan are bigger than 1, that object will occupy
- * more space than a single cell. For instance, the following code:
* @code
- * elm_layout_table_pack(layout, "table_part", child, 0, 1, 3, 1);
+ * This text is outside <a href=anc-01>but this one is an anchor</a>
* @endcode
*
- * Would result in an object being added like the following picture:
- *
- * @image html layout_colspan.png
- * @image latex layout_colspan.eps width=\textwidth
- *
- * @see elm_layout_table_unpack()
- * @see elm_layout_table_clear()
- *
- * @ingroup Layout
- */
- EAPI void elm_layout_table_pack(Evas_Object *obj, const char *part, Evas_Object *child_obj, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan) EINA_ARG_NONNULL(1);
- /**
- * Unpack (remove) a child of the given part table.
+ * The @c href attribute in the opening tag gives the name that will be
+ * used to identify the anchor and it can be any valid utf8 string.
*
- * @param obj The layout object
- * @param part The table part name to remove child.
- * @param child_obj The object to remove from table.
- * @return The object that was being used, or NULL if not found.
+ * When an anchor is clicked, an @c "anchor,clicked" signal is emitted with
+ * an #Elm_Entry_Anchor_Info in the @c event_info parameter for the
+ * callback function. The same applies for "anchor,in" (mouse in), "anchor,out"
+ * (mouse out), "anchor,down" (mouse down), and "anchor,up" (mouse up) events on
+ * an anchor.
*
- * The object will be unpacked from the table part and its lifetime
- * will not be handled by the layout anymore. This is equivalent to
- * elm_layout_content_unset() for table.
+ * @subsection entry-items Items
*
- * @see elm_layout_table_pack()
- * @see elm_layout_table_clear()
+ * Inlined in the text, any other @c Evas_Object can be inserted by using
+ * \<item\> tags this way:
*
- * @ingroup Layout
- */
- EAPI Evas_Object *elm_layout_table_unpack(Evas_Object *obj, const char *part, Evas_Object *child_obj) EINA_ARG_NONNULL(1, 2, 3);
- /**
- * Remove all child of the given part table.
+ * @code
+ * <item size=16x16 vsize=full href=emoticon/haha></item>
+ * @endcode
*
- * @param obj The layout object
- * @param part The table part name to remove child.
- * @param clear If EINA_TRUE, then all objects will be deleted as
- * well, otherwise they will just be removed and will be
- * dangling on the canvas.
+ * Just like with anchors, the @c href identifies each item, but these need,
+ * in addition, to indicate their size, which is done using any one of
+ * @c size, @c absize or @c relsize attributes. These attributes take their
+ * value in the WxH format, where W is the width and H the height of the
+ * item.
*
- * The objects will be removed from the table part and their lifetime will
- * not be handled by the layout anymore. This is equivalent to
- * elm_layout_table_unpack() for all table children.
+ * @li absize: Absolute pixel size for the item. Whatever value is set will
+ * be the item's size regardless of any scale value the object may have
+ * been set to. The final line height will be adjusted to fit larger items.
+ * @li size: Similar to @c absize, but it's adjusted to the scale value set
+ * for the object.
+ * @li relsize: Size is adjusted for the item to fit within the current
+ * line height.
*
- * @see elm_layout_table_pack()
- * @see elm_layout_table_unpack()
+ * Besides their size, items are specificed a @c vsize value that affects
+ * how their final size and position are calculated. The possible values
+ * are:
+ * @li ascent: Item will be placed within the line's baseline and its
+ * ascent. That is, the height between the line where all characters are
+ * positioned and the highest point in the line. For @c size and @c absize
+ * items, the descent value will be added to the total line height to make
+ * them fit. @c relsize items will be adjusted to fit within this space.
+ * @li full: Items will be placed between the descent and ascent, or the
+ * lowest point in the line and its highest.
*
- * @ingroup Layout
- */
- EAPI void elm_layout_table_clear(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
- /**
- * Get the edje layout
+ * The next image shows different configurations of items and how they
+ * are the previously mentioned options affect their sizes. In all cases,
+ * the green line indicates the ascent, blue for the baseline and red for
+ * the descent.
*
- * @param obj The layout object
+ * @image html entry_item.png
+ * @image latex entry_item.eps width=\textwidth
*
- * @return A Evas_Object with the edje layout settings loaded
- * with function elm_layout_file_set
+ * And another one to show how size differs from absize. In the first one,
+ * the scale value is set to 1.0, while the second one is using one of 2.0.
*
- * This returns the edje object. It is not expected to be used to then
- * swallow objects via edje_object_part_swallow() for example. Use
- * elm_layout_content_set() instead so child object handling and sizing is
- * done properly.
+ * @image html entry_item_scale.png
+ * @image latex entry_item_scale.eps width=\textwidth
*
- * @note This function should only be used if you really need to call some
- * low level Edje function on this edje object. All the common stuff (setting
- * text, emitting signals, hooking callbacks to signals, etc.) can be done
- * with proper elementary functions.
+ * After the size for an item is calculated, the entry will request an
+ * object to place in its space. For this, the functions set with
+ * elm_entry_item_provider_append() and related functions will be called
+ * in order until one of them returns a @c non-NULL value. If no providers
+ * are available, or all of them return @c NULL, then the entry falls back
+ * to one of the internal defaults, provided the name matches with one of
+ * them.
*
- * @see elm_object_signal_callback_add()
- * @see elm_object_signal_emit()
- * @see elm_object_text_part_set()
- * @see elm_layout_content_set()
- * @see elm_layout_box_append()
- * @see elm_layout_table_pack()
- * @see elm_layout_data_get()
+ * All of the following are currently supported:
*
- * @ingroup Layout
- */
- EAPI Evas_Object *elm_layout_edje_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Get the edje data from the given layout
+ * - emoticon/angry
+ * - emoticon/angry-shout
+ * - emoticon/crazy-laugh
+ * - emoticon/evil-laugh
+ * - emoticon/evil
+ * - emoticon/goggle-smile
+ * - emoticon/grumpy
+ * - emoticon/grumpy-smile
+ * - emoticon/guilty
+ * - emoticon/guilty-smile
+ * - emoticon/haha
+ * - emoticon/half-smile
+ * - emoticon/happy-panting
+ * - emoticon/happy
+ * - emoticon/indifferent
+ * - emoticon/kiss
+ * - emoticon/knowing-grin
+ * - emoticon/laugh
+ * - emoticon/little-bit-sorry
+ * - emoticon/love-lots
+ * - emoticon/love
+ * - emoticon/minimal-smile
+ * - emoticon/not-happy
+ * - emoticon/not-impressed
+ * - emoticon/omg
+ * - emoticon/opensmile
+ * - emoticon/smile
+ * - emoticon/sorry
+ * - emoticon/squint-laugh
+ * - emoticon/surprised
+ * - emoticon/suspicious
+ * - emoticon/tongue-dangling
+ * - emoticon/tongue-poke
+ * - emoticon/uh
+ * - emoticon/unhappy
+ * - emoticon/very-sorry
+ * - emoticon/what
+ * - emoticon/wink
+ * - emoticon/worried
+ * - emoticon/wtf
*
- * @param obj The layout object
- * @param key The data key
+ * Alternatively, an item may reference an image by its path, using
+ * the URI form @c file:///path/to/an/image.png and the entry will then
+ * use that image for the item.
*
- * @return The edje data string
+ * @section entry-files Loading and saving files
*
- * This function fetches data specified inside the edje theme of this layout.
- * This function return NULL if data is not found.
+ * Entries have convinience functions to load text from a file and save
+ * changes back to it after a short delay. The automatic saving is enabled
+ * by default, but can be disabled with elm_entry_autosave_set() and files
+ * can be loaded directly as plain text or have any markup in them
+ * recognized. See elm_entry_file_set() for more details.
*
- * In EDC this comes from a data block within the group block that @p
- * obj was loaded from. E.g.
+ * @section entry-signals Emitted signals
*
- * @code
- * collections {
- * group {
- * name: "a_group";
- * data {
- * item: "key1" "value1";
- * item: "key2" "value2";
- * }
- * }
- * }
- * @endcode
+ * This widget emits the following signals:
*
- * @ingroup Layout
- */
- EAPI const char *elm_layout_data_get(const Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
- /**
- * Eval sizing
+ * @li "changed": The text within the entry was changed.
+ * @li "changed,user": The text within the entry was changed because of user interaction.
+ * @li "activated": The enter key was pressed on a single line entry.
+ * @li "press": A mouse button has been pressed on the entry.
+ * @li "longpressed": A mouse button has been pressed and held for a couple
+ * seconds.
+ * @li "clicked": The entry has been clicked (mouse press and release).
+ * @li "clicked,double": The entry has been double clicked.
+ * @li "clicked,triple": The entry has been triple clicked.
+ * @li "focused": The entry has received focus.
+ * @li "unfocused": The entry has lost focus.
+ * @li "selection,paste": A paste of the clipboard contents was requested.
+ * @li "selection,copy": A copy of the selected text into the clipboard was
+ * requested.
+ * @li "selection,cut": A cut of the selected text into the clipboard was
+ * requested.
+ * @li "selection,start": A selection has begun and no previous selection
+ * existed.
+ * @li "selection,changed": The current selection has changed.
+ * @li "selection,cleared": The current selection has been cleared.
+ * @li "cursor,changed": The cursor has changed position.
+ * @li "anchor,clicked": An anchor has been clicked. The event_info
+ * parameter for the callback will be an #Elm_Entry_Anchor_Info.
+ * @li "anchor,in": Mouse cursor has moved into an anchor. The event_info
+ * parameter for the callback will be an #Elm_Entry_Anchor_Info.
+ * @li "anchor,out": Mouse cursor has moved out of an anchor. The event_info
+ * parameter for the callback will be an #Elm_Entry_Anchor_Info.
+ * @li "anchor,up": Mouse button has been unpressed on an anchor. The event_info
+ * parameter for the callback will be an #Elm_Entry_Anchor_Info.
+ * @li "anchor,down": Mouse button has been pressed on an anchor. The event_info
+ * parameter for the callback will be an #Elm_Entry_Anchor_Info.
+ * @li "preedit,changed": The preedit string has changed.
*
- * @param obj The layout object
+ * @section entry-examples
*
- * Manually forces a sizing re-evaluation. This is useful when the minimum
- * size required by the edje theme of this layout has changed. The change on
- * the minimum size required by the edje theme is not immediately reported to
- * the elementary layout, so one needs to call this function in order to tell
- * the widget (layout) that it needs to reevaluate its own size.
+ * An overview of the Entry API can be seen in @ref entry_example_01
*
- * The minimum size of the theme is calculated based on minimum size of
- * parts, the size of elements inside containers like box and table, etc. All
- * of this can change due to state changes, and that's when this function
- * should be called.
+ * @{
+ */
+ /**
+ * @typedef Elm_Entry_Anchor_Info
*
- * Also note that a standard signal of "size,eval" "elm" emitted from the
- * edje object will cause this to happen too.
+ * The info sent in the callback for the "anchor,clicked" signals emitted
+ * by entries.
+ */
+ typedef struct _Elm_Entry_Anchor_Info Elm_Entry_Anchor_Info;
+ /**
+ * @struct _Elm_Entry_Anchor_Info
*
- * @ingroup Layout
+ * The info sent in the callback for the "anchor,clicked" signals emitted
+ * by entries.
*/
- EAPI void elm_layout_sizing_eval(Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_layout_part_cursor_set(Evas_Object *obj, const char *part_name, const char *cursor) EINA_ARG_NONNULL(1, 2);
- EAPI const char *elm_layout_part_cursor_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
- EAPI void elm_layout_part_cursor_unset(Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
- EAPI Eina_Bool elm_layout_part_cursor_style_set(Evas_Object *obj, const char *part_name, const char *style) EINA_ARG_NONNULL(1, 2);
- EAPI const char *elm_layout_part_cursor_style_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
- EAPI Eina_Bool elm_layout_part_cursor_engine_only_set(Evas_Object *obj, const char *part_name, Eina_Bool engine_only) EINA_ARG_NONNULL(1, 2);
- EAPI Eina_Bool elm_layout_part_cursor_engine_only_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
-/**
- * @def elm_layout_icon_set
- * Convienience macro to set the icon object in a layout that follows the
- * Elementary naming convention for its parts.
- *
- * @ingroup Layout
- */
-#define elm_layout_icon_set(_ly, _obj) \
- do { \
- const char *sig; \
- elm_layout_content_set((_ly), "elm.swallow.icon", (_obj)); \
- if ((_obj)) sig = "elm,state,icon,visible"; \
- else sig = "elm,state,icon,hidden"; \
- elm_object_signal_emit((_ly), sig, "elm"); \
- } while (0)
-
-/**
- * @def elm_layout_icon_get
- * Convienience macro to get the icon object from a layout that follows the
- * Elementary naming convention for its parts.
- *
- * @ingroup Layout
- */
-#define elm_layout_icon_get(_ly) \
- elm_layout_content_get((_ly), "elm.swallow.icon")
-
-/**
- * @def elm_layout_end_set
- * Convienience macro to set the end object in a layout that follows the
- * Elementary naming convention for its parts.
- *
- * @ingroup Layout
- */
-#define elm_layout_end_set(_ly, _obj) \
- do { \
- const char *sig; \
- elm_layout_content_set((_ly), "elm.swallow.end", (_obj)); \
- if ((_obj)) sig = "elm,state,end,visible"; \
- else sig = "elm,state,end,hidden"; \
- elm_object_signal_emit((_ly), sig, "elm"); \
- } while (0)
-
-/**
- * @def elm_layout_end_get
- * Convienience macro to get the end object in a layout that follows the
- * Elementary naming convention for its parts.
- *
- * @ingroup Layout
- */
-#define elm_layout_end_get(_ly) \
- elm_layout_content_get((_ly), "elm.swallow.end")
-
-/**
- * @def elm_layout_label_set
- * Convienience macro to set the label in a layout that follows the
- * Elementary naming convention for its parts.
- *
- * @ingroup Layout
- * @deprecated use elm_object_text_* instead.
- */
-#define elm_layout_label_set(_ly, _txt) \
- elm_layout_text_set((_ly), "elm.text", (_txt))
-
-/**
- * @def elm_layout_label_get
- * Convienience macro to get the label in a layout that follows the
- * Elementary naming convention for its parts.
- *
- * @ingroup Layout
- * @deprecated use elm_object_text_* instead.
- */
-#define elm_layout_label_get(_ly) \
- elm_layout_text_get((_ly), "elm.text")
-
- /* smart callbacks called:
- * "theme,changed" - when elm theme is changed.
+ struct _Elm_Entry_Anchor_Info
+ {
+ const char *name; /**< The name of the anchor, as stated in its href */
+ int button; /**< The mouse button used to click on it */
+ Evas_Coord x, /**< Anchor geometry, relative to canvas */
+ y, /**< Anchor geometry, relative to canvas */
+ w, /**< Anchor geometry, relative to canvas */
+ h; /**< Anchor geometry, relative to canvas */
+ };
+ /**
+ * @typedef Elm_Entry_Filter_Cb
+ * This callback type is used by entry filters to modify text.
+ * @param data The data specified as the last param when adding the filter
+ * @param entry The entry object
+ * @param text A pointer to the location of the text being filtered. This data can be modified,
+ * but any additional allocations must be managed by the user.
+ * @see elm_entry_text_filter_append
+ * @see elm_entry_text_filter_prepend
*/
+ typedef void (*Elm_Entry_Filter_Cb)(void *data, Evas_Object *entry, char **text);
/**
- * @defgroup Notify Notify
+ * This adds an entry to @p parent object.
*
- * @image html img/widget/notify/preview-00.png
- * @image latex img/widget/notify/preview-00.eps
+ * By default, entries are:
+ * @li not scrolled
+ * @li multi-line
+ * @li word wrapped
+ * @li autosave is enabled
*
- * Display a container in a particular region of the parent(top, bottom,
- * etc. A timeout can be set to automatically hide the notify. This is so
- * that, after an evas_object_show() on a notify object, if a timeout was set
- * on it, it will @b automatically get hidden after that time.
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
+ EAPI Evas_Object *elm_entry_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * Sets the entry to single line mode.
*
- * Signals that you can add callbacks for are:
- * @li "timeout" - when timeout happens on notify and it's hidden
- * @li "block,clicked" - when a click outside of the notify happens
+ * In single line mode, entries don't ever wrap when the text reaches the
+ * edge, and instead they keep growing horizontally. Pressing the @c Enter
+ * key will generate an @c "activate" event instead of adding a new line.
*
- * @ref tutorial_notify show usage of the API.
+ * When @p single_line is @c EINA_FALSE, line wrapping takes effect again
+ * and pressing enter will break the text into a different line
+ * without generating any events.
*
- * @{
+ * @param obj The entry object
+ * @param single_line If true, the text in the entry
+ * will be on a single line.
*/
+ EAPI void elm_entry_single_line_set(Evas_Object *obj, Eina_Bool single_line) EINA_ARG_NONNULL(1);
/**
- * @brief Possible orient values for notify.
+ * Gets whether the entry is set to be single line.
*
- * This values should be used in conjunction to elm_notify_orient_set() to
- * set the position in which the notify should appear(relative to its parent)
- * and in conjunction with elm_notify_orient_get() to know where the notify
- * is appearing.
+ * @param obj The entry object
+ * @return single_line If true, the text in the entry is set to display
+ * on a single line.
+ *
+ * @see elm_entry_single_line_set()
*/
- typedef enum _Elm_Notify_Orient
- {
- ELM_NOTIFY_ORIENT_TOP, /**< Notify should appear in the top of parent, default */
- ELM_NOTIFY_ORIENT_CENTER, /**< Notify should appear in the center of parent */
- ELM_NOTIFY_ORIENT_BOTTOM, /**< Notify should appear in the bottom of parent */
- ELM_NOTIFY_ORIENT_LEFT, /**< Notify should appear in the left of parent */
- ELM_NOTIFY_ORIENT_RIGHT, /**< Notify should appear in the right of parent */
- ELM_NOTIFY_ORIENT_TOP_LEFT, /**< Notify should appear in the top left of parent */
- ELM_NOTIFY_ORIENT_TOP_RIGHT, /**< Notify should appear in the top right of parent */
- ELM_NOTIFY_ORIENT_BOTTOM_LEFT, /**< Notify should appear in the bottom left of parent */
- ELM_NOTIFY_ORIENT_BOTTOM_RIGHT, /**< Notify should appear in the bottom right of parent */
- ELM_NOTIFY_ORIENT_LAST /**< Sentinel value, @b don't use */
- } Elm_Notify_Orient;
+ EAPI Eina_Bool elm_entry_single_line_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Add a new notify to the parent
+ * Sets the entry to password mode.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * In password mode, entries are implicitly single line and the display of
+ * any text in them is replaced with asterisks (*).
+ *
+ * @param obj The entry object
+ * @param password If true, password mode is enabled.
*/
- EAPI Evas_Object *elm_notify_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_password_set(Evas_Object *obj, Eina_Bool password) EINA_ARG_NONNULL(1);
/**
- * @brief Set the content of the notify widget
+ * Gets whether the entry is set to password mode.
*
- * @param obj The notify object
- * @param content The content will be filled in this notify object
+ * @param obj The entry object
+ * @return If true, the entry is set to display all characters
+ * as asterisks (*).
*
- * Once the content object is set, a previously set one will be deleted. If
- * you want to keep that old content object, use the
- * elm_notify_content_unset() function.
+ * @see elm_entry_password_set()
*/
- EAPI void elm_notify_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_entry_password_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Unset the content of the notify widget
- *
- * @param obj The notify object
- * @return The content that was being used
+ * This sets the text displayed within the entry to @p entry.
*
- * Unparent and return the content object which was set for this widget
+ * @param obj The entry object
+ * @param entry The text to be displayed
*
- * @see elm_notify_content_set()
+ * @deprecated Use elm_object_text_set() instead.
*/
- EAPI Evas_Object *elm_notify_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_entry_set(Evas_Object *obj, const char *entry) EINA_ARG_NONNULL(1);
/**
- * @brief Return the content of the notify widget
+ * This returns the text currently shown in object @p entry.
+ * See also elm_entry_entry_set().
*
- * @param obj The notify object
- * @return The content that is being used
+ * @param obj The entry object
+ * @return The currently displayed text or NULL on failure
*
- * @see elm_notify_content_set()
+ * @deprecated Use elm_object_text_get() instead.
*/
- EAPI Evas_Object *elm_notify_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_entry_entry_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Set the notify parent
+ * Appends @p entry to the text of the entry.
*
- * @param obj The notify object
- * @param content The new parent
+ * Adds the text in @p entry to the end of any text already present in the
+ * widget.
*
- * Once the parent object is set, a previously set one will be disconnected
- * and replaced.
+ * The appended text is subject to any filters set for the widget.
+ *
+ * @param obj The entry object
+ * @param entry The text to be displayed
+ *
+ * @see elm_entry_text_filter_append()
*/
- EAPI void elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_entry_append(Evas_Object *obj, const char *entry) EINA_ARG_NONNULL(1);
/**
- * @brief Get the notify parent
+ * Gets whether the entry is empty.
*
- * @param obj The notify object
- * @return The parent
+ * Empty means no text at all. If there are any markup tags, like an item
+ * tag for which no provider finds anything, and no text is displayed, this
+ * function still returns EINA_FALSE.
*
- * @see elm_notify_parent_set()
+ * @param obj The entry object
+ * @return EINA_TRUE if the entry is empty, EINA_FALSE otherwise.
*/
- EAPI Evas_Object *elm_notify_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_entry_is_empty(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Set the orientation
+ * Gets any selected text within the entry.
*
- * @param obj The notify object
- * @param orient The new orientation
+ * If there's any selected text in the entry, this function returns it as
+ * a string in markup format. NULL is returned if no selection exists or
+ * if an error occurred.
*
- * Sets the position in which the notify will appear in its parent.
+ * The returned value points to an internal string and should not be freed
+ * or modified in any way. If the @p entry object is deleted or its
+ * contents are changed, the returned pointer should be considered invalid.
*
- * @see @ref Elm_Notify_Orient for possible values.
+ * @param obj The entry object
+ * @return The selected text within the entry or NULL on failure
*/
- EAPI void elm_notify_orient_set(Evas_Object *obj, Elm_Notify_Orient orient) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_entry_selection_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Return the orientation
- * @param obj The notify object
- * @return The orientation of the notification
+ * Inserts the given text into the entry at the current cursor position.
*
- * @see elm_notify_orient_set()
- * @see Elm_Notify_Orient
+ * This inserts text at the cursor position as if it was typed
+ * by the user (note that this also allows markup which a user
+ * can't just "type" as it would be converted to escaped text, so this
+ * call can be used to insert things like emoticon items or bold push/pop
+ * tags, other font and color change tags etc.)
+ *
+ * If any selection exists, it will be replaced by the inserted text.
+ *
+ * The inserted text is subject to any filters set for the widget.
+ *
+ * @param obj The entry object
+ * @param entry The text to insert
+ *
+ * @see elm_entry_text_filter_append()
*/
- EAPI Elm_Notify_Orient elm_notify_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_entry_insert(Evas_Object *obj, const char *entry) EINA_ARG_NONNULL(1);
/**
- * @brief Set the time interval after which the notify window is going to be
- * hidden.
- *
- * @param obj The notify object
- * @param time The timeout in seconds
+ * Set the line wrap type to use on multi-line entries.
*
- * This function sets a timeout and starts the timer controlling when the
- * notify is hidden. Since calling evas_object_show() on a notify restarts
- * the timer controlling when the notify is hidden, setting this before the
- * notify is shown will in effect mean starting the timer when the notify is
- * shown.
+ * Sets the wrap type used by the entry to any of the specified in
+ * #Elm_Wrap_Type. This tells how the text will be implicitly cut into a new
+ * line (without inserting a line break or paragraph separator) when it
+ * reaches the far edge of the widget.
*
- * @note Set a value <= 0.0 to disable a running timer.
+ * Note that this only makes sense for multi-line entries. A widget set
+ * to be single line will never wrap.
*
- * @note If the value > 0.0 and the notify is previously visible, the
- * timer will be started with this value, canceling any running timer.
+ * @param obj The entry object
+ * @param wrap The wrap mode to use. See #Elm_Wrap_Type for details on them
*/
- EAPI void elm_notify_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap) EINA_ARG_NONNULL(1);
/**
- * @brief Return the timeout value (in seconds)
- * @param obj the notify object
+ * Gets the wrap mode the entry was set to use.
*
- * @see elm_notify_timeout_set()
+ * @param obj The entry object
+ * @return Wrap type
+ *
+ * @see also elm_entry_line_wrap_set()
*/
- EAPI double elm_notify_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Elm_Wrap_Type elm_entry_line_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Sets whether events should be passed to by a click outside
- * its area.
+ * Sets if the entry is to be editable or not.
*
- * @param obj The notify object
- * @param repeats EINA_TRUE Events are repeats, else no
+ * By default, entries are editable and when focused, any text input by the
+ * user will be inserted at the current cursor position. But calling this
+ * function with @p editable as EINA_FALSE will prevent the user from
+ * inputting text into the entry.
*
- * When true if the user clicks outside the window the events will be caught
- * by the others widgets, else the events are blocked.
+ * The only way to change the text of a non-editable entry is to use
+ * elm_object_text_set(), elm_entry_entry_insert() and other related
+ * functions.
*
- * @note The default value is EINA_TRUE.
+ * @param obj The entry object
+ * @param editable If EINA_TRUE, user input will be inserted in the entry,
+ * if not, the entry is read-only and no user input is allowed.
*/
- EAPI void elm_notify_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_editable_set(Evas_Object *obj, Eina_Bool editable) EINA_ARG_NONNULL(1);
/**
- * @brief Return true if events are repeat below the notify object
- * @param obj the notify object
+ * Gets whether the entry is editable or not.
*
- * @see elm_notify_repeat_events_set()
+ * @param obj The entry object
+ * @return If true, the entry is editable by the user.
+ * If false, it is not editable by the user
+ *
+ * @see elm_entry_editable_set()
*/
- EAPI Eina_Bool elm_notify_repeat_events_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_entry_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @}
+ * This drops any existing text selection within the entry.
+ *
+ * @param obj The entry object
*/
-
+ EAPI void elm_entry_select_none(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @defgroup Hover Hover
- *
- * @image html img/widget/hover/preview-00.png
- * @image latex img/widget/hover/preview-00.eps
- *
- * A Hover object will hover over its @p parent object at the @p target
- * location. Anything in the background will be given a darker coloring to
- * indicate that the hover object is on top (at the default theme). When the
- * hover is clicked it is dismissed(hidden), if the contents of the hover are
- * clicked that @b doesn't cause the hover to be dismissed.
+ * This selects all text within the entry.
*
- * @note The hover object will take up the entire space of @p target
- * object.
+ * @param obj The entry object
+ */
+ EAPI void elm_entry_select_all(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This moves the cursor one place to the right within the entry.
*
- * Elementary has the following styles for the hover widget:
- * @li default
- * @li popout
- * @li menu
- * @li hoversel_vertical
+ * @param obj The entry object
+ * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ */
+ EAPI Eina_Bool elm_entry_cursor_next(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This moves the cursor one place to the left within the entry.
*
- * The following are the available position for content:
- * @li left
- * @li top-left
- * @li top
- * @li top-right
- * @li right
- * @li bottom-right
- * @li bottom
- * @li bottom-left
- * @li middle
- * @li smart
+ * @param obj The entry object
+ * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ */
+ EAPI Eina_Bool elm_entry_cursor_prev(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This moves the cursor one line up within the entry.
*
- * Signals that you can add callbacks for are:
- * @li "clicked" - the user clicked the empty space in the hover to dismiss
- * @li "smart,changed" - a content object placed under the "smart"
- * policy was replaced to a new slot direction.
+ * @param obj The entry object
+ * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ */
+ EAPI Eina_Bool elm_entry_cursor_up(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This moves the cursor one line down within the entry.
*
- * See @ref tutorial_hover for more information.
+ * @param obj The entry object
+ * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ */
+ EAPI Eina_Bool elm_entry_cursor_down(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This moves the cursor to the beginning of the entry.
*
- * @{
+ * @param obj The entry object
*/
- typedef enum _Elm_Hover_Axis
- {
- ELM_HOVER_AXIS_NONE, /**< ELM_HOVER_AXIS_NONE -- no prefered orientation */
- ELM_HOVER_AXIS_HORIZONTAL, /**< ELM_HOVER_AXIS_HORIZONTAL -- horizontal */
- ELM_HOVER_AXIS_VERTICAL, /**< ELM_HOVER_AXIS_VERTICAL -- vertical */
- ELM_HOVER_AXIS_BOTH /**< ELM_HOVER_AXIS_BOTH -- both */
- } Elm_Hover_Axis;
+ EAPI void elm_entry_cursor_begin_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Adds a hover object to @p parent
+ * This moves the cursor to the end of the entry.
*
- * @param parent The parent object
- * @return The hover object or NULL if one could not be created
+ * @param obj The entry object
*/
- EAPI Evas_Object *elm_hover_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_cursor_end_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the target object for the hover.
- *
- * @param obj The hover object
- * @param target The object to center the hover onto. The hover
+ * This moves the cursor to the beginning of the current line.
*
- * This function will cause the hover to be centered on the target object.
+ * @param obj The entry object
*/
- EAPI void elm_hover_target_set(Evas_Object *obj, Evas_Object *target) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_cursor_line_begin_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Gets the target object for the hover.
- *
- * @param obj The hover object
- * @param parent The object to locate the hover over.
+ * This moves the cursor to the end of the current line.
*
- * @see elm_hover_target_set()
+ * @param obj The entry object
*/
- EAPI Evas_Object *elm_hover_target_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_cursor_line_end_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the parent object for the hover.
- *
- * @param obj The hover object
- * @param parent The object to locate the hover over.
+ * This begins a selection within the entry as though
+ * the user were holding down the mouse button to make a selection.
*
- * This function will cause the hover to take up the entire space that the
- * parent object fills.
+ * @param obj The entry object
*/
- EAPI void elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_cursor_selection_begin(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Gets the parent object for the hover.
- *
- * @param obj The hover object
- * @return The parent object to locate the hover over.
+ * This ends a selection within the entry as though
+ * the user had just released the mouse button while making a selection.
*
- * @see elm_hover_parent_set()
+ * @param obj The entry object
*/
- EAPI Evas_Object *elm_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_cursor_selection_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the content of the hover object and the direction in which it
- * will pop out.
+ * Gets whether a format node exists at the current cursor position.
*
- * @param obj The hover object
- * @param swallow The direction that the object will be displayed
- * at. Accepted values are "left", "top-left", "top", "top-right",
- * "right", "bottom-right", "bottom", "bottom-left", "middle" and
- * "smart".
- * @param content The content to place at @p swallow
+ * A format node is anything that defines how the text is rendered. It can
+ * be a visible format node, such as a line break or a paragraph separator,
+ * or an invisible one, such as bold begin or end tag.
+ * This function returns whether any format node exists at the current
+ * cursor position.
*
- * Once the content object is set for a given direction, a previously
- * set one (on the same direction) will be deleted. If you want to
- * keep that old content object, use the elm_hover_content_unset()
- * function.
+ * @param obj The entry object
+ * @return EINA_TRUE if the current cursor position contains a format node,
+ * EINA_FALSE otherwise.
*
- * All directions may have contents at the same time, except for
- * "smart". This is a special placement hint and its use case
- * independs of the calculations coming from
- * elm_hover_best_content_location_get(). Its use is for cases when
- * one desires only one hover content, but with a dinamic special
- * placement within the hover area. The content's geometry, whenever
- * it changes, will be used to decide on a best location not
- * extrapolating the hover's parent object view to show it in (still
- * being the hover's target determinant of its medium part -- move and
- * resize it to simulate finger sizes, for example). If one of the
- * directions other than "smart" are used, a previously content set
- * using it will be deleted, and vice-versa.
+ * @see elm_entry_cursor_is_visible_format_get()
*/
- EAPI void elm_hover_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_entry_cursor_is_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Get the content of the hover object, in a given direction.
- *
- * Return the content object which was set for this widget in the
- * @p swallow direction.
+ * Gets if the current cursor position holds a visible format node.
*
- * @param obj The hover object
- * @param swallow The direction that the object was display at.
- * @return The content that was being used
+ * @param obj The entry object
+ * @return EINA_TRUE if the current cursor is a visible format, EINA_FALSE
+ * if it's an invisible one or no format exists.
*
- * @see elm_hover_content_set()
+ * @see elm_entry_cursor_is_format_get()
*/
- EAPI Evas_Object *elm_hover_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_entry_cursor_is_visible_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @brief Unset the content of the hover object, in a given direction.
+ * Gets the character pointed by the cursor at its current position.
*
- * Unparent and return the content object set at @p swallow direction.
+ * This function returns a string with the utf8 character stored at the
+ * current cursor position.
+ * Only the text is returned, any format that may exist will not be part
+ * of the return value.
*
- * @param obj The hover object
- * @param swallow The direction that the object was display at.
- * @return The content that was being used.
+ * @param obj The entry object
+ * @return The text pointed by the cursors.
+ */
+ EAPI const char *elm_entry_cursor_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This function returns the geometry of the cursor.
*
- * @see elm_hover_content_set()
+ * It's useful if you want to draw something on the cursor (or where it is),
+ * or for example in the case of scrolled entry where you want to show the
+ * cursor.
+ *
+ * @param obj The entry object
+ * @param x returned geometry
+ * @param y returned geometry
+ * @param w returned geometry
+ * @param h returned geometry
+ * @return EINA_TRUE upon success, EINA_FALSE upon failure
*/
- EAPI Evas_Object *elm_hover_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_entry_cursor_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
- * @brief Returns the best swallow location for content in the hover.
+ * Sets the cursor position in the entry to the given value
*
- * @param obj The hover object
- * @param pref_axis The preferred orientation axis for the hover object to use
- * @return The edje location to place content into the hover or @c
- * NULL, on errors.
+ * The value in @p pos is the index of the character position within the
+ * contents of the string as returned by elm_entry_cursor_pos_get().
*
- * Best is defined here as the location at which there is the most available
- * space.
+ * @param obj The entry object
+ * @param pos The position of the cursor
+ */
+ EAPI void elm_entry_cursor_pos_set(Evas_Object *obj, int pos) EINA_ARG_NONNULL(1);
+ /**
+ * Retrieves the current position of the cursor in the entry
*
- * @p pref_axis may be one of
- * - @c ELM_HOVER_AXIS_NONE -- no prefered orientation
- * - @c ELM_HOVER_AXIS_HORIZONTAL -- horizontal
- * - @c ELM_HOVER_AXIS_VERTICAL -- vertical
- * - @c ELM_HOVER_AXIS_BOTH -- both
+ * @param obj The entry object
+ * @return The cursor position
+ */
+ EAPI int elm_entry_cursor_pos_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This executes a "cut" action on the selected text in the entry.
*
- * If ELM_HOVER_AXIS_HORIZONTAL is choosen the returned position will
- * nescessarily be along the horizontal axis("left" or "right"). If
- * ELM_HOVER_AXIS_VERTICAL is choosen the returned position will nescessarily
- * be along the vertical axis("top" or "bottom"). Chossing
- * ELM_HOVER_AXIS_BOTH or ELM_HOVER_AXIS_NONE has the same effect and the
- * returned position may be in either axis.
+ * @param obj The entry object
+ */
+ EAPI void elm_entry_selection_cut(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This executes a "copy" action on the selected text in the entry.
*
- * @see elm_hover_content_set()
+ * @param obj The entry object
*/
- EAPI const char *elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_selection_copy(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @}
+ * This executes a "paste" action in the entry.
+ *
+ * @param obj The entry object
*/
-
- /* entry */
+ EAPI void elm_entry_selection_paste(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @defgroup Entry Entry
+ * This clears and frees the items in a entry's contextual (longpress)
+ * menu.
*
- * @image html img/widget/entry/preview-00.png
- * @image latex img/widget/entry/preview-00.eps width=\textwidth
- * @image html img/widget/entry/preview-01.png
- * @image latex img/widget/entry/preview-01.eps width=\textwidth
- * @image html img/widget/entry/preview-02.png
- * @image latex img/widget/entry/preview-02.eps width=\textwidth
- * @image html img/widget/entry/preview-03.png
- * @image latex img/widget/entry/preview-03.eps width=\textwidth
+ * @param obj The entry object
*
- * An entry is a convenience widget which shows a box that the user can
- * enter text into. Entries by default don't scroll, so they grow to
- * accomodate the entire text, resizing the parent window as needed. This
- * can be changed with the elm_entry_scrollable_set() function.
+ * @see elm_entry_context_menu_item_add()
+ */
+ EAPI void elm_entry_context_menu_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This adds an item to the entry's contextual menu.
*
- * They can also be single line or multi line (the default) and when set
- * to multi line mode they support text wrapping in any of the modes
- * indicated by #Elm_Wrap_Type.
+ * A longpress on an entry will make the contextual menu show up, if this
+ * hasn't been disabled with elm_entry_context_menu_disabled_set().
+ * By default, this menu provides a few options like enabling selection mode,
+ * which is useful on embedded devices that need to be explicit about it,
+ * and when a selection exists it also shows the copy and cut actions.
*
- * Other features include password mode, filtering of inserted text with
- * elm_entry_text_filter_append() and related functions, inline "items" and
- * formatted markup text.
+ * With this function, developers can add other options to this menu to
+ * perform any action they deem necessary.
*
- * @section entry-markup Formatted text
+ * @param obj The entry object
+ * @param label The item's text label
+ * @param icon_file The item's icon file
+ * @param icon_type The item's icon type
+ * @param func The callback to execute when the item is clicked
+ * @param data The data to associate with the item for related functions
+ */
+ EAPI void elm_entry_context_menu_item_add(Evas_Object *obj, const char *label, const char *icon_file, Elm_Icon_Type icon_type, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
+ /**
+ * This disables the entry's contextual (longpress) menu.
*
- * The markup tags supported by the Entry are defined by the theme, but
- * even when writing new themes or extensions it's a good idea to stick to
- * a sane default, to maintain coherency and avoid application breakages.
- * Currently defined by the default theme are the following tags:
- * @li \<br\>: Inserts a line break.
- * @li \<ps\>: Inserts a paragraph separator. This is preferred over line
- * breaks.
- * @li \<tab\>: Inserts a tab.
- * @li \<em\>...\</em\>: Emphasis. Sets the @em oblique style for the
- * enclosed text.
- * @li \<b\>...\</b\>: Sets the @b bold style for the enclosed text.
- * @li \<link\>...\</link\>: Underlines the enclosed text.
- * @li \<hilight\>...\</hilight\>: Hilights the enclosed text.
+ * @param obj The entry object
+ * @param disabled If true, the menu is disabled
+ */
+ EAPI void elm_entry_context_menu_disabled_set(Evas_Object *obj, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+ /**
+ * This returns whether the entry's contextual (longpress) menu is
+ * disabled.
*
- * @section entry-special Special markups
+ * @param obj The entry object
+ * @return If true, the menu is disabled
+ */
+ EAPI Eina_Bool elm_entry_context_menu_disabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This appends a custom item provider to the list for that entry
*
- * Besides those used to format text, entries support two special markup
- * tags used to insert clickable portions of text or items inlined within
- * the text.
+ * This appends the given callback. The list is walked from beginning to end
+ * with each function called given the item href string in the text. If the
+ * function returns an object handle other than NULL (it should create an
+ * object to do this), then this object is used to replace that item. If
+ * not the next provider is called until one provides an item object, or the
+ * default provider in entry does.
*
- * @subsection entry-anchors Anchors
+ * @param obj The entry object
+ * @param func The function called to provide the item object
+ * @param data The data passed to @p func
*
- * Anchors are similar to HTML anchors. Text can be surrounded by \<a\> and
- * \</a\> tags and an event will be generated when this text is clicked,
- * like this:
+ * @see @ref entry-items
+ */
+ EAPI void elm_entry_item_provider_append(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *entry, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ /**
+ * This prepends a custom item provider to the list for that entry
*
- * @code
- * This text is outside <a href=anc-01>but this one is an anchor</a>
- * @endcode
+ * This prepends the given callback. See elm_entry_item_provider_append() for
+ * more information
*
- * The @c href attribute in the opening tag gives the name that will be
- * used to identify the anchor and it can be any valid utf8 string.
+ * @param obj The entry object
+ * @param func The function called to provide the item object
+ * @param data The data passed to @p func
+ */
+ EAPI void elm_entry_item_provider_prepend(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *entry, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ /**
+ * This removes a custom item provider to the list for that entry
*
- * When an anchor is clicked, an @c "anchor,clicked" signal is emitted with
- * an #Elm_Entry_Anchor_Info in the @c event_info parameter for the
- * callback function. The same applies for "anchor,in" (mouse in), "anchor,out"
- * (mouse out), "anchor,down" (mouse down), and "anchor,up" (mouse up) events on
- * an anchor.
+ * This removes the given callback. See elm_entry_item_provider_append() for
+ * more information
*
- * @subsection entry-items Items
+ * @param obj The entry object
+ * @param func The function called to provide the item object
+ * @param data The data passed to @p func
+ */
+ EAPI void elm_entry_item_provider_remove(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *entry, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ /**
+ * Append a filter function for text inserted in the entry
*
- * Inlined in the text, any other @c Evas_Object can be inserted by using
- * \<item\> tags this way:
+ * Append the given callback to the list. This functions will be called
+ * whenever any text is inserted into the entry, with the text to be inserted
+ * as a parameter. The callback function is free to alter the text in any way
+ * it wants, but it must remember to free the given pointer and update it.
+ * If the new text is to be discarded, the function can free it and set its
+ * text parameter to NULL. This will also prevent any following filters from
+ * being called.
*
- * @code
- * <item size=16x16 vsize=full href=emoticon/haha></item>
- * @endcode
+ * @param obj The entry object
+ * @param func The function to use as text filter
+ * @param data User data to pass to @p func
+ */
+ EAPI void elm_entry_text_filter_append(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
+ /**
+ * Prepend a filter function for text insdrted in the entry
*
- * Just like with anchors, the @c href identifies each item, but these need,
- * in addition, to indicate their size, which is done using any one of
- * @c size, @c absize or @c relsize attributes. These attributes take their
- * value in the WxH format, where W is the width and H the height of the
- * item.
+ * Prepend the given callback to the list. See elm_entry_text_filter_append()
+ * for more information
*
- * @li absize: Absolute pixel size for the item. Whatever value is set will
- * be the item's size regardless of any scale value the object may have
- * been set to. The final line height will be adjusted to fit larger items.
- * @li size: Similar to @c absize, but it's adjusted to the scale value set
- * for the object.
- * @li relsize: Size is adjusted for the item to fit within the current
- * line height.
+ * @param obj The entry object
+ * @param func The function to use as text filter
+ * @param data User data to pass to @p func
+ */
+ EAPI void elm_entry_text_filter_prepend(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
+ /**
+ * Remove a filter from the list
*
- * Besides their size, items are specificed a @c vsize value that affects
- * how their final size and position are calculated. The possible values
- * are:
- * @li ascent: Item will be placed within the line's baseline and its
- * ascent. That is, the height between the line where all characters are
- * positioned and the highest point in the line. For @c size and @c absize
- * items, the descent value will be added to the total line height to make
- * them fit. @c relsize items will be adjusted to fit within this space.
- * @li full: Items will be placed between the descent and ascent, or the
- * lowest point in the line and its highest.
+ * Removes the given callback from the filter list. See
+ * elm_entry_text_filter_append() for more information.
*
- * The next image shows different configurations of items and how they
- * are the previously mentioned options affect their sizes. In all cases,
- * the green line indicates the ascent, blue for the baseline and red for
- * the descent.
+ * @param obj The entry object
+ * @param func The filter function to remove
+ * @param data The user data passed when adding the function
+ */
+ EAPI void elm_entry_text_filter_remove(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
+ /**
+ * This converts a markup (HTML-like) string into UTF-8.
*
- * @image html entry_item.png
- * @image latex entry_item.eps width=\textwidth
+ * The returned string is a malloc'ed buffer and it should be freed when
+ * not needed anymore.
*
- * And another one to show how size differs from absize. In the first one,
- * the scale value is set to 1.0, while the second one is using one of 2.0.
+ * @param s The string (in markup) to be converted
+ * @return The converted string (in UTF-8). It should be freed.
+ */
+ EAPI char *elm_entry_markup_to_utf8(const char *s) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+ /**
+ * This converts a UTF-8 string into markup (HTML-like).
*
- * @image html entry_item_scale.png
- * @image latex entry_item_scale.eps width=\textwidth
+ * The returned string is a malloc'ed buffer and it should be freed when
+ * not needed anymore.
*
- * After the size for an item is calculated, the entry will request an
- * object to place in its space. For this, the functions set with
- * elm_entry_item_provider_append() and related functions will be called
- * in order until one of them returns a @c non-NULL value. If no providers
- * are available, or all of them return @c NULL, then the entry falls back
- * to one of the internal defaults, provided the name matches with one of
- * them.
+ * @param s The string (in UTF-8) to be converted
+ * @return The converted string (in markup). It should be freed.
+ */
+ EAPI char *elm_entry_utf8_to_markup(const char *s) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+ /**
+ * This sets the file (and implicitly loads it) for the text to display and
+ * then edit. All changes are written back to the file after a short delay if
+ * the entry object is set to autosave (which is the default).
*
- * All of the following are currently supported:
+ * If the entry had any other file set previously, any changes made to it
+ * will be saved if the autosave feature is enabled, otherwise, the file
+ * will be silently discarded and any non-saved changes will be lost.
*
- * - emoticon/angry
- * - emoticon/angry-shout
- * - emoticon/crazy-laugh
- * - emoticon/evil-laugh
- * - emoticon/evil
- * - emoticon/goggle-smile
- * - emoticon/grumpy
- * - emoticon/grumpy-smile
- * - emoticon/guilty
- * - emoticon/guilty-smile
- * - emoticon/haha
- * - emoticon/half-smile
- * - emoticon/happy-panting
- * - emoticon/happy
- * - emoticon/indifferent
- * - emoticon/kiss
- * - emoticon/knowing-grin
- * - emoticon/laugh
- * - emoticon/little-bit-sorry
- * - emoticon/love-lots
- * - emoticon/love
- * - emoticon/minimal-smile
- * - emoticon/not-happy
- * - emoticon/not-impressed
- * - emoticon/omg
- * - emoticon/opensmile
- * - emoticon/smile
- * - emoticon/sorry
- * - emoticon/squint-laugh
- * - emoticon/surprised
- * - emoticon/suspicious
- * - emoticon/tongue-dangling
- * - emoticon/tongue-poke
- * - emoticon/uh
- * - emoticon/unhappy
- * - emoticon/very-sorry
- * - emoticon/what
- * - emoticon/wink
- * - emoticon/worried
- * - emoticon/wtf
+ * @param obj The entry object
+ * @param file The path to the file to load and save
+ * @param format The file format
+ */
+ EAPI void elm_entry_file_set(Evas_Object *obj, const char *file, Elm_Text_Format format) EINA_ARG_NONNULL(1);
+ /**
+ * Gets the file being edited by the entry.
*
- * Alternatively, an item may reference an image by its path, using
- * the URI form @c file:///path/to/an/image.png and the entry will then
- * use that image for the item.
+ * This function can be used to retrieve any file set on the entry for
+ * edition, along with the format used to load and save it.
*
- * @section entry-files Loading and saving files
+ * @param obj The entry object
+ * @param file The path to the file to load and save
+ * @param format The file format
+ */
+ EAPI void elm_entry_file_get(const Evas_Object *obj, const char **file, Elm_Text_Format *format) EINA_ARG_NONNULL(1);
+ /**
+ * This function writes any changes made to the file set with
+ * elm_entry_file_set()
*
- * Entries have convinience functions to load text from a file and save
- * changes back to it after a short delay. The automatic saving is enabled
- * by default, but can be disabled with elm_entry_autosave_set() and files
- * can be loaded directly as plain text or have any markup in them
- * recognized. See elm_entry_file_set() for more details.
+ * @param obj The entry object
+ */
+ EAPI void elm_entry_file_save(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * This sets the entry object to 'autosave' the loaded text file or not.
*
- * @section entry-signals Emitted signals
+ * @param obj The entry object
+ * @param autosave Autosave the loaded file or not
*
- * This widget emits the following signals:
+ * @see elm_entry_file_set()
+ */
+ EAPI void elm_entry_autosave_set(Evas_Object *obj, Eina_Bool autosave) EINA_ARG_NONNULL(1);
+ /**
+ * This gets the entry object's 'autosave' status.
*
- * @li "changed": The text within the entry was changed.
- * @li "changed,user": The text within the entry was changed because of user interaction.
- * @li "activated": The enter key was pressed on a single line entry.
- * @li "press": A mouse button has been pressed on the entry.
- * @li "longpressed": A mouse button has been pressed and held for a couple
- * seconds.
- * @li "clicked": The entry has been clicked (mouse press and release).
- * @li "clicked,double": The entry has been double clicked.
- * @li "clicked,triple": The entry has been triple clicked.
- * @li "focused": The entry has received focus.
- * @li "unfocused": The entry has lost focus.
- * @li "selection,paste": A paste of the clipboard contents was requested.
- * @li "selection,copy": A copy of the selected text into the clipboard was
- * requested.
- * @li "selection,cut": A cut of the selected text into the clipboard was
- * requested.
- * @li "selection,start": A selection has begun and no previous selection
- * existed.
- * @li "selection,changed": The current selection has changed.
- * @li "selection,cleared": The current selection has been cleared.
- * @li "cursor,changed": The cursor has changed position.
- * @li "anchor,clicked": An anchor has been clicked. The event_info
- * parameter for the callback will be an #Elm_Entry_Anchor_Info.
- * @li "anchor,in": Mouse cursor has moved into an anchor. The event_info
- * parameter for the callback will be an #Elm_Entry_Anchor_Info.
- * @li "anchor,out": Mouse cursor has moved out of an anchor. The event_info
- * parameter for the callback will be an #Elm_Entry_Anchor_Info.
- * @li "anchor,up": Mouse button has been unpressed on an anchor. The event_info
- * parameter for the callback will be an #Elm_Entry_Anchor_Info.
- * @li "anchor,down": Mouse button has been pressed on an anchor. The event_info
- * parameter for the callback will be an #Elm_Entry_Anchor_Info.
- * @li "preedit,changed": The preedit string has changed.
+ * @param obj The entry object
+ * @return Autosave the loaded file or not
+ *
+ * @see elm_entry_file_set()
+ */
+ EAPI Eina_Bool elm_entry_autosave_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Control pasting of text and images for the widget.
*
- * @section entry-examples
+ * Normally the entry allows both text and images to be pasted. By setting
+ * textonly to be true, this prevents images from being pasted.
*
- * An overview of the Entry API can be seen in @ref entry_example_01
+ * Note this only changes the behaviour of text.
*
- * @{
+ * @param obj The entry object
+ * @param textonly paste mode - EINA_TRUE is text only, EINA_FALSE is
+ * text+image+other.
*/
+ EAPI void elm_entry_cnp_textonly_set(Evas_Object *obj, Eina_Bool textonly) EINA_ARG_NONNULL(1);
/**
- * @typedef Elm_Entry_Anchor_Info
+ * Getting elm_entry text paste/drop mode.
*
- * The info sent in the callback for the "anchor,clicked" signals emitted
- * by entries.
+ * In textonly mode, only text may be pasted or dropped into the widget.
+ *
+ * @param obj The entry object
+ * @return If the widget only accepts text from pastes.
*/
- typedef struct _Elm_Entry_Anchor_Info Elm_Entry_Anchor_Info;
+ EAPI Eina_Bool elm_entry_cnp_textonly_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @struct _Elm_Entry_Anchor_Info
+ * Enable or disable scrolling in entry
*
- * The info sent in the callback for the "anchor,clicked" signals emitted
- * by entries.
+ * Normally the entry is not scrollable unless you enable it with this call.
+ *
+ * @param obj The entry object
+ * @param scroll EINA_TRUE if it is to be scrollable, EINA_FALSE otherwise
*/
- struct _Elm_Entry_Anchor_Info
- {
- const char *name; /**< The name of the anchor, as stated in its href */
- int button; /**< The mouse button used to click on it */
- Evas_Coord x, /**< Anchor geometry, relative to canvas */
- y, /**< Anchor geometry, relative to canvas */
- w, /**< Anchor geometry, relative to canvas */
- h; /**< Anchor geometry, relative to canvas */
- };
+ EAPI void elm_entry_scrollable_set(Evas_Object *obj, Eina_Bool scroll);
/**
- * @typedef Elm_Entry_Filter_Cb
- * This callback type is used by entry filters to modify text.
- * @param data The data specified as the last param when adding the filter
- * @param entry The entry object
- * @param text A pointer to the location of the text being filtered. This data can be modified,
- * but any additional allocations must be managed by the user.
- * @see elm_entry_text_filter_append
- * @see elm_entry_text_filter_prepend
+ * Get the scrollable state of the entry
+ *
+ * Normally the entry is not scrollable. This gets the scrollable state
+ * of the entry. See elm_entry_scrollable_set() for more information.
+ *
+ * @param obj The entry object
+ * @return The scrollable state
*/
- typedef void (*Elm_Entry_Filter_Cb)(void *data, Evas_Object *entry, char **text);
-
+ EAPI Eina_Bool elm_entry_scrollable_get(const Evas_Object *obj);
/**
- * This adds an entry to @p parent object.
+ * This sets a widget to be displayed to the left of a scrolled entry.
*
- * By default, entries are:
- * @li not scrolled
- * @li multi-line
- * @li word wrapped
- * @li autosave is enabled
+ * @param obj The scrolled entry object
+ * @param icon The widget to display on the left side of the scrolled
+ * entry.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * @note A previously set widget will be destroyed.
+ * @note If the object being set does not have minimum size hints set,
+ * it won't get properly displayed.
+ *
+ * @see elm_entry_end_set()
*/
- EAPI Evas_Object *elm_entry_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_icon_set(Evas_Object *obj, Evas_Object *icon);
/**
- * Sets the entry to single line mode.
+ * Gets the leftmost widget of the scrolled entry. This object is
+ * owned by the scrolled entry and should not be modified.
*
- * In single line mode, entries don't ever wrap when the text reaches the
- * edge, and instead they keep growing horizontally. Pressing the @c Enter
- * key will generate an @c "activate" event instead of adding a new line.
+ * @param obj The scrolled entry object
+ * @return the left widget inside the scroller
+ */
+ EAPI Evas_Object *elm_entry_icon_get(const Evas_Object *obj);
+ /**
+ * Unset the leftmost widget of the scrolled entry, unparenting and
+ * returning it.
*
- * When @p single_line is @c EINA_FALSE, line wrapping takes effect again
- * and pressing enter will break the text into a different line
- * without generating any events.
+ * @param obj The scrolled entry object
+ * @return the previously set icon sub-object of this entry, on
+ * success.
*
- * @param obj The entry object
- * @param single_line If true, the text in the entry
- * will be on a single line.
+ * @see elm_entry_icon_set()
*/
- EAPI void elm_entry_single_line_set(Evas_Object *obj, Eina_Bool single_line) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_entry_icon_unset(Evas_Object *obj);
/**
- * Gets whether the entry is set to be single line.
- *
- * @param obj The entry object
- * @return single_line If true, the text in the entry is set to display
- * on a single line.
+ * Sets the visibility of the left-side widget of the scrolled entry,
+ * set by elm_entry_icon_set().
*
- * @see elm_entry_single_line_set()
+ * @param obj The scrolled entry object
+ * @param setting EINA_TRUE if the object should be displayed,
+ * EINA_FALSE if not.
*/
- EAPI Eina_Bool elm_entry_single_line_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_icon_visible_set(Evas_Object *obj, Eina_Bool setting);
/**
- * Sets the entry to password mode.
+ * This sets a widget to be displayed to the end of a scrolled entry.
*
- * In password mode, entries are implicitly single line and the display of
- * any text in them is replaced with asterisks (*).
+ * @param obj The scrolled entry object
+ * @param end The widget to display on the right side of the scrolled
+ * entry.
*
- * @param obj The entry object
- * @param password If true, password mode is enabled.
+ * @note A previously set widget will be destroyed.
+ * @note If the object being set does not have minimum size hints set,
+ * it won't get properly displayed.
+ *
+ * @see elm_entry_icon_set
*/
- EAPI void elm_entry_password_set(Evas_Object *obj, Eina_Bool password) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_end_set(Evas_Object *obj, Evas_Object *end);
/**
- * Gets whether the entry is set to password mode.
- *
- * @param obj The entry object
- * @return If true, the entry is set to display all characters
- * as asterisks (*).
+ * Gets the endmost widget of the scrolled entry. This object is owned
+ * by the scrolled entry and should not be modified.
*
- * @see elm_entry_password_set()
+ * @param obj The scrolled entry object
+ * @return the right widget inside the scroller
*/
- EAPI Eina_Bool elm_entry_password_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_entry_end_get(const Evas_Object *obj);
/**
- * This sets the text displayed within the entry to @p entry.
+ * Unset the endmost widget of the scrolled entry, unparenting and
+ * returning it.
*
- * @param obj The entry object
- * @param entry The text to be displayed
+ * @param obj The scrolled entry object
+ * @return the previously set icon sub-object of this entry, on
+ * success.
*
- * @deprecated Use elm_object_text_set() instead.
+ * @see elm_entry_icon_set()
*/
- EAPI void elm_entry_entry_set(Evas_Object *obj, const char *entry) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_entry_end_unset(Evas_Object *obj);
/**
- * This returns the text currently shown in object @p entry.
- * See also elm_entry_entry_set().
- *
- * @param obj The entry object
- * @return The currently displayed text or NULL on failure
+ * Sets the visibility of the end widget of the scrolled entry, set by
+ * elm_entry_end_set().
*
- * @deprecated Use elm_object_text_get() instead.
+ * @param obj The scrolled entry object
+ * @param setting EINA_TRUE if the object should be displayed,
+ * EINA_FALSE if not.
*/
- EAPI const char *elm_entry_entry_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_end_visible_set(Evas_Object *obj, Eina_Bool setting);
/**
- * Appends @p entry to the text of the entry.
+ * This sets the scrolled entry's scrollbar policy (ie. enabling/disabling
+ * them).
*
- * Adds the text in @p entry to the end of any text already present in the
- * widget.
+ * Setting an entry to single-line mode with elm_entry_single_line_set()
+ * will automatically disable the display of scrollbars when the entry
+ * moves inside its scroller.
*
- * The appended text is subject to any filters set for the widget.
+ * @param obj The scrolled entry object
+ * @param h The horizontal scrollbar policy to apply
+ * @param v The vertical scrollbar policy to apply
+ */
+ EAPI void elm_entry_scrollbar_policy_set(Evas_Object *obj, Elm_Scroller_Policy h, Elm_Scroller_Policy v);
+ /**
+ * This enables/disables bouncing within the entry.
*
- * @param obj The entry object
- * @param entry The text to be displayed
+ * This function sets whether the entry will bounce when scrolling reaches
+ * the end of the contained entry.
*
- * @see elm_entry_text_filter_append()
+ * @param obj The scrolled entry object
+ * @param h The horizontal bounce state
+ * @param v The vertical bounce state
*/
- EAPI void elm_entry_entry_append(Evas_Object *obj, const char *entry) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
/**
- * Gets whether the entry is empty.
+ * Get the bounce mode
*
- * Empty means no text at all. If there are any markup tags, like an item
- * tag for which no provider finds anything, and no text is displayed, this
- * function still returns EINA_FALSE.
+ * @param obj The Entry object
+ * @param h_bounce Allow bounce horizontally
+ * @param v_bounce Allow bounce vertically
+ */
+ EAPI void elm_entry_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
+
+ /* pre-made filters for entries */
+ /**
+ * @typedef Elm_Entry_Filter_Limit_Size
*
- * @param obj The entry object
- * @return EINA_TRUE if the entry is empty, EINA_FALSE otherwise.
+ * Data for the elm_entry_filter_limit_size() entry filter.
*/
- EAPI Eina_Bool elm_entry_is_empty(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Entry_Filter_Limit_Size Elm_Entry_Filter_Limit_Size;
/**
- * Gets any selected text within the entry.
+ * @struct _Elm_Entry_Filter_Limit_Size
*
- * If there's any selected text in the entry, this function returns it as
- * a string in markup format. NULL is returned if no selection exists or
- * if an error occurred.
+ * Data for the elm_entry_filter_limit_size() entry filter.
+ */
+ struct _Elm_Entry_Filter_Limit_Size
+ {
+ int max_char_count; /**< The maximum number of characters allowed. */
+ int max_byte_count; /**< The maximum number of bytes allowed*/
+ };
+ /**
+ * Filter inserted text based on user defined character and byte limits
*
- * The returned value points to an internal string and should not be freed
- * or modified in any way. If the @p entry object is deleted or its
- * contents are changed, the returned pointer should be considered invalid.
+ * Add this filter to an entry to limit the characters that it will accept
+ * based the the contents of the provided #Elm_Entry_Filter_Limit_Size.
+ * The funtion works on the UTF-8 representation of the string, converting
+ * it from the set markup, thus not accounting for any format in it.
*
- * @param obj The entry object
- * @return The selected text within the entry or NULL on failure
+ * The user must create an #Elm_Entry_Filter_Limit_Size structure and pass
+ * it as data when setting the filter. In it, it's possible to set limits
+ * by character count or bytes (any of them is disabled if 0), and both can
+ * be set at the same time. In that case, it first checks for characters,
+ * then bytes.
+ *
+ * The function will cut the inserted text in order to allow only the first
+ * number of characters that are still allowed. The cut is made in
+ * characters, even when limiting by bytes, in order to always contain
+ * valid ones and avoid half unicode characters making it in.
+ *
+ * This filter, like any others, does not apply when setting the entry text
+ * directly with elm_object_text_set() (or the deprecated
+ * elm_entry_entry_set()).
+ */
+ EAPI void elm_entry_filter_limit_size(void *data, Evas_Object *entry, char **text) EINA_ARG_NONNULL(1, 2, 3);
+ /**
+ * @typedef Elm_Entry_Filter_Accept_Set
+ *
+ * Data for the elm_entry_filter_accept_set() entry filter.
*/
- EAPI const char *elm_entry_selection_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Entry_Filter_Accept_Set Elm_Entry_Filter_Accept_Set;
/**
- * Inserts the given text into the entry at the current cursor position.
+ * @struct _Elm_Entry_Filter_Accept_Set
*
- * This inserts text at the cursor position as if it was typed
- * by the user (note that this also allows markup which a user
- * can't just "type" as it would be converted to escaped text, so this
- * call can be used to insert things like emoticon items or bold push/pop
- * tags, other font and color change tags etc.)
+ * Data for the elm_entry_filter_accept_set() entry filter.
+ */
+ struct _Elm_Entry_Filter_Accept_Set
+ {
+ const char *accepted; /**< Set of characters accepted in the entry. */
+ const char *rejected; /**< Set of characters rejected from the entry. */
+ };
+ /**
+ * Filter inserted text based on accepted or rejected sets of characters
*
- * If any selection exists, it will be replaced by the inserted text.
+ * Add this filter to an entry to restrict the set of accepted characters
+ * based on the sets in the provided #Elm_Entry_Filter_Accept_Set.
+ * This structure contains both accepted and rejected sets, but they are
+ * mutually exclusive.
*
- * The inserted text is subject to any filters set for the widget.
+ * The @c accepted set takes preference, so if it is set, the filter will
+ * only work based on the accepted characters, ignoring anything in the
+ * @c rejected value. If @c accepted is @c NULL, then @c rejected is used.
*
- * @param obj The entry object
- * @param entry The text to insert
+ * In both cases, the function filters by matching utf8 characters to the
+ * raw markup text, so it can be used to remove formatting tags.
*
- * @see elm_entry_text_filter_append()
+ * This filter, like any others, does not apply when setting the entry text
+ * directly with elm_object_text_set() (or the deprecated
+ * elm_entry_entry_set()).
*/
- EAPI void elm_entry_entry_insert(Evas_Object *obj, const char *entry) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_filter_accept_set(void *data, Evas_Object *entry, char **text) EINA_ARG_NONNULL(1, 3);
/**
- * Set the line wrap type to use on multi-line entries.
- *
- * Sets the wrap type used by the entry to any of the specified in
- * #Elm_Wrap_Type. This tells how the text will be implicitly cut into a new
- * line (without inserting a line break or paragraph separator) when it
- * reaches the far edge of the widget.
- *
- * Note that this only makes sense for multi-line entries. A widget set
- * to be single line will never wrap.
+ * Set the input panel layout of the entry
*
* @param obj The entry object
- * @param wrap The wrap mode to use. See #Elm_Wrap_Type for details on them
+ * @param layout layout type
*/
- EAPI void elm_entry_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap) EINA_ARG_NONNULL(1);
+ EAPI void elm_entry_input_panel_layout_set(Evas_Object *obj, Elm_Input_Panel_Layout layout) EINA_ARG_NONNULL(1);
/**
- * Gets the wrap mode the entry was set to use.
+ * Get the input panel layout of the entry
*
* @param obj The entry object
- * @return Wrap type
+ * @return layout type
*
- * @see also elm_entry_line_wrap_set()
+ * @see elm_entry_input_panel_layout_set
*/
- EAPI Elm_Wrap_Type elm_entry_line_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Elm_Input_Panel_Layout elm_entry_input_panel_layout_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Sets if the entry is to be editable or not.
+ * @}
+ */
+
+ /* composite widgets - these basically put together basic widgets above
+ * in convenient packages that do more than basic stuff */
+
+ /* anchorview */
+ /**
+ * @defgroup Anchorview Anchorview
*
- * By default, entries are editable and when focused, any text input by the
- * user will be inserted at the current cursor position. But calling this
- * function with @p editable as EINA_FALSE will prevent the user from
- * inputting text into the entry.
+ * @image html img/widget/anchorview/preview-00.png
+ * @image latex img/widget/anchorview/preview-00.eps
*
- * The only way to change the text of a non-editable entry is to use
- * elm_object_text_set(), elm_entry_entry_insert() and other related
- * functions.
+ * Anchorview is for displaying text that contains markup with anchors
+ * like <c>\<a href=1234\>something\</\></c> in it.
*
- * @param obj The entry object
- * @param editable If EINA_TRUE, user input will be inserted in the entry,
- * if not, the entry is read-only and no user input is allowed.
- */
- EAPI void elm_entry_editable_set(Evas_Object *obj, Eina_Bool editable) EINA_ARG_NONNULL(1);
- /**
- * Gets whether the entry is editable or not.
+ * Besides being styled differently, the anchorview widget provides the
+ * necessary functionality so that clicking on these anchors brings up a
+ * popup with user defined content such as "call", "add to contacts" or
+ * "open web page". This popup is provided using the @ref Hover widget.
*
- * @param obj The entry object
- * @return If true, the entry is editable by the user.
- * If false, it is not editable by the user
+ * This widget is very similar to @ref Anchorblock, so refer to that
+ * widget for an example. The only difference Anchorview has is that the
+ * widget is already provided with scrolling functionality, so if the
+ * text set to it is too large to fit in the given space, it will scroll,
+ * whereas the @ref Anchorblock widget will keep growing to ensure all the
+ * text can be displayed.
*
- * @see elm_entry_editable_set()
- */
- EAPI Eina_Bool elm_entry_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * This drops any existing text selection within the entry.
+ * This widget emits the following signals:
+ * @li "anchor,clicked": will be called when an anchor is clicked. The
+ * @p event_info parameter on the callback will be a pointer of type
+ * ::Elm_Entry_Anchorview_Info.
*
- * @param obj The entry object
+ * See @ref Anchorblock for an example on how to use both of them.
+ *
+ * @see Anchorblock
+ * @see Entry
+ * @see Hover
+ *
+ * @{
*/
- EAPI void elm_entry_select_none(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This selects all text within the entry.
+ * @typedef Elm_Entry_Anchorview_Info
*
- * @param obj The entry object
+ * The info sent in the callback for "anchor,clicked" signals emitted by
+ * the Anchorview widget.
*/
- EAPI void elm_entry_select_all(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Entry_Anchorview_Info Elm_Entry_Anchorview_Info;
/**
- * This moves the cursor one place to the right within the entry.
+ * @struct _Elm_Entry_Anchorview_Info
*
- * @param obj The entry object
- * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ * The info sent in the callback for "anchor,clicked" signals emitted by
+ * the Anchorview widget.
*/
- EAPI Eina_Bool elm_entry_cursor_next(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ struct _Elm_Entry_Anchorview_Info
+ {
+ const char *name; /**< Name of the anchor, as indicated in its href
+ attribute */
+ int button; /**< The mouse button used to click on it */
+ Evas_Object *hover; /**< The hover object to use for the popup */
+ struct {
+ Evas_Coord x, y, w, h;
+ } anchor, /**< Geometry selection of text used as anchor */
+ hover_parent; /**< Geometry of the object used as parent by the
+ hover */
+ Eina_Bool hover_left : 1; /**< Hint indicating if there's space
+ for content on the left side of
+ the hover. Before calling the
+ callback, the widget will make the
+ necessary calculations to check
+ which sides are fit to be set with
+ content, based on the position the
+ hover is activated and its distance
+ to the edges of its parent object
+ */
+ Eina_Bool hover_right : 1; /**< Hint indicating content fits on
+ the right side of the hover.
+ See @ref hover_left */
+ Eina_Bool hover_top : 1; /**< Hint indicating content fits on top
+ of the hover. See @ref hover_left */
+ Eina_Bool hover_bottom : 1; /**< Hint indicating content fits
+ below the hover. See @ref
+ hover_left */
+ };
/**
- * This moves the cursor one place to the left within the entry.
+ * Add a new Anchorview object
*
- * @param obj The entry object
- * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*/
- EAPI Eina_Bool elm_entry_cursor_prev(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_anchorview_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * This moves the cursor one line up within the entry.
+ * Set the text to show in the anchorview
*
- * @param obj The entry object
- * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ * Sets the text of the anchorview to @p text. This text can include markup
+ * format tags, including <c>\<a href=anchorname\></c> to begin a segment of
+ * text that will be specially styled and react to click events, ended with
+ * either of \</a\> or \</\>. When clicked, the anchor will emit an
+ * "anchor,clicked" signal that you can attach a callback to with
+ * evas_object_smart_callback_add(). The name of the anchor given in the
+ * event info struct will be the one set in the href attribute, in this
+ * case, anchorname.
+ *
+ * Other markup can be used to style the text in different ways, but it's
+ * up to the style defined in the theme which tags do what.
+ * @deprecated use elm_object_text_set() instead.
*/
- EAPI Eina_Bool elm_entry_cursor_up(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI void elm_anchorview_text_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
/**
- * This moves the cursor one line down within the entry.
+ * Get the markup text set for the anchorview
*
- * @param obj The entry object
- * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ * Retrieves the text set on the anchorview, with markup tags included.
+ *
+ * @param obj The anchorview object
+ * @return The markup text set or @c NULL if nothing was set or an error
+ * occurred
+ * @deprecated use elm_object_text_set() instead.
*/
- EAPI Eina_Bool elm_entry_cursor_down(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI const char *elm_anchorview_text_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This moves the cursor to the beginning of the entry.
+ * Set the parent of the hover popup
*
- * @param obj The entry object
+ * Sets the parent object to use by the hover created by the anchorview
+ * when an anchor is clicked. See @ref Hover for more details on this.
+ * If no parent is set, the same anchorview object will be used.
+ *
+ * @param obj The anchorview object
+ * @param parent The object to use as parent for the hover
*/
- EAPI void elm_entry_cursor_begin_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * This moves the cursor to the end of the entry.
+ * Get the parent of the hover popup
*
- * @param obj The entry object
+ * Get the object used as parent for the hover created by the anchorview
+ * widget. See @ref Hover for more details on this.
+ *
+ * @param obj The anchorview object
+ * @return The object used as parent for the hover, NULL if none is set.
*/
- EAPI void elm_entry_cursor_end_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_anchorview_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This moves the cursor to the beginning of the current line.
+ * Set the style that the hover should use
*
- * @param obj The entry object
+ * When creating the popup hover, anchorview will request that it's
+ * themed according to @p style.
+ *
+ * @param obj The anchorview object
+ * @param style The style to use for the underlying hover
+ *
+ * @see elm_object_style_set()
*/
- EAPI void elm_entry_cursor_line_begin_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_hover_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
/**
- * This moves the cursor to the end of the current line.
+ * Get the style that the hover should use
*
- * @param obj The entry object
+ * Get the style the hover created by anchorview will use.
+ *
+ * @param obj The anchorview object
+ * @return The style to use by the hover. NULL means the default is used.
+ *
+ * @see elm_object_style_set()
*/
- EAPI void elm_entry_cursor_line_end_set(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_anchorview_hover_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This begins a selection within the entry as though
- * the user were holding down the mouse button to make a selection.
+ * Ends the hover popup in the anchorview
*
- * @param obj The entry object
+ * When an anchor is clicked, the anchorview widget will create a hover
+ * object to use as a popup with user provided content. This function
+ * terminates this popup, returning the anchorview to its normal state.
+ *
+ * @param obj The anchorview object
*/
- EAPI void elm_entry_cursor_selection_begin(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_hover_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This ends a selection within the entry as though
- * the user had just released the mouse button while making a selection.
+ * Set bouncing behaviour when the scrolled content reaches an edge
+ *
+ * Tell the internal scroller object whether it should bounce or not
+ * when it reaches the respective edges for each axis.
*
- * @param obj The entry object
+ * @param obj The anchorview object
+ * @param h_bounce Whether to bounce or not in the horizontal axis
+ * @param v_bounce Whether to bounce or not in the vertical axis
+ *
+ * @see elm_scroller_bounce_set()
*/
- EAPI void elm_entry_cursor_selection_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
/**
- * Gets whether a format node exists at the current cursor position.
+ * Get the set bouncing behaviour of the internal scroller
*
- * A format node is anything that defines how the text is rendered. It can
- * be a visible format node, such as a line break or a paragraph separator,
- * or an invisible one, such as bold begin or end tag.
- * This function returns whether any format node exists at the current
- * cursor position.
+ * Get whether the internal scroller should bounce when the edge of each
+ * axis is reached scrolling.
*
- * @param obj The entry object
- * @return EINA_TRUE if the current cursor position contains a format node,
- * EINA_FALSE otherwise.
+ * @param obj The anchorview object
+ * @param h_bounce Pointer where to store the bounce state of the horizontal
+ * axis
+ * @param v_bounce Pointer where to store the bounce state of the vertical
+ * axis
*
- * @see elm_entry_cursor_is_visible_format_get()
+ * @see elm_scroller_bounce_get()
*/
- EAPI Eina_Bool elm_entry_cursor_is_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
/**
- * Gets if the current cursor position holds a visible format node.
+ * Appends a custom item provider to the given anchorview
*
- * @param obj The entry object
- * @return EINA_TRUE if the current cursor is a visible format, EINA_FALSE
- * if it's an invisible one or no format exists.
+ * Appends the given function to the list of items providers. This list is
+ * called, one function at a time, with the given @p data pointer, the
+ * anchorview object and, in the @p item parameter, the item name as
+ * referenced in its href string. Following functions in the list will be
+ * called in order until one of them returns something different to NULL,
+ * which should be an Evas_Object which will be used in place of the item
+ * element.
*
- * @see elm_entry_cursor_is_format_get()
- */
- EAPI Eina_Bool elm_entry_cursor_is_visible_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Gets the character pointed by the cursor at its current position.
+ * Items in the markup text take the form \<item relsize=16x16 vsize=full
+ * href=item/name\>\</item\>
*
- * This function returns a string with the utf8 character stored at the
- * current cursor position.
- * Only the text is returned, any format that may exist will not be part
- * of the return value.
+ * @param obj The anchorview object
+ * @param func The function to add to the list of providers
+ * @param data User data that will be passed to the callback function
*
- * @param obj The entry object
- * @return The text pointed by the cursors.
+ * @see elm_entry_item_provider_append()
*/
- EAPI const char *elm_entry_cursor_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_item_provider_append(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
/**
- * This function returns the geometry of the cursor.
+ * Prepend a custom item provider to the given anchorview
*
- * It's useful if you want to draw something on the cursor (or where it is),
- * or for example in the case of scrolled entry where you want to show the
- * cursor.
+ * Like elm_anchorview_item_provider_append(), but it adds the function
+ * @p func to the beginning of the list, instead of the end.
*
- * @param obj The entry object
- * @param x returned geometry
- * @param y returned geometry
- * @param w returned geometry
- * @param h returned geometry
- * @return EINA_TRUE upon success, EINA_FALSE upon failure
+ * @param obj The anchorview object
+ * @param func The function to add to the list of providers
+ * @param data User data that will be passed to the callback function
*/
- EAPI Eina_Bool elm_entry_cursor_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_item_provider_prepend(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
/**
- * Sets the cursor position in the entry to the given value
+ * Remove a custom item provider from the list of the given anchorview
*
- * The value in @p pos is the index of the character position within the
- * contents of the string as returned by elm_entry_cursor_pos_get().
+ * Removes the function and data pairing that matches @p func and @p data.
+ * That is, unless the same function and same user data are given, the
+ * function will not be removed from the list. This allows us to add the
+ * same callback several times, with different @p data pointers and be
+ * able to remove them later without conflicts.
*
- * @param obj The entry object
- * @param pos The position of the cursor
+ * @param obj The anchorview object
+ * @param func The function to remove from the list
+ * @param data The data matching the function to remove from the list
*/
- EAPI void elm_entry_cursor_pos_set(Evas_Object *obj, int pos) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorview_item_provider_remove(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
/**
- * Retrieves the current position of the cursor in the entry
- *
- * @param obj The entry object
- * @return The cursor position
+ * @}
*/
- EAPI int elm_entry_cursor_pos_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /* anchorblock */
/**
- * This executes a "cut" action on the selected text in the entry.
+ * @defgroup Anchorblock Anchorblock
*
- * @param obj The entry object
- */
- EAPI void elm_entry_selection_cut(Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * This executes a "copy" action on the selected text in the entry.
+ * @image html img/widget/anchorblock/preview-00.png
+ * @image latex img/widget/anchorblock/preview-00.eps
*
- * @param obj The entry object
+ * Anchorblock is for displaying text that contains markup with anchors
+ * like <c>\<a href=1234\>something\</\></c> in it.
+ *
+ * Besides being styled differently, the anchorblock widget provides the
+ * necessary functionality so that clicking on these anchors brings up a
+ * popup with user defined content such as "call", "add to contacts" or
+ * "open web page". This popup is provided using the @ref Hover widget.
+ *
+ * This widget emits the following signals:
+ * @li "anchor,clicked": will be called when an anchor is clicked. The
+ * @p event_info parameter on the callback will be a pointer of type
+ * ::Elm_Entry_Anchorblock_Info.
+ *
+ * @see Anchorview
+ * @see Entry
+ * @see Hover
+ *
+ * Since examples are usually better than plain words, we might as well
+ * try @ref tutorial_anchorblock_example "one".
*/
- EAPI void elm_entry_selection_copy(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This executes a "paste" action in the entry.
- *
- * @param obj The entry object
+ * @addtogroup Anchorblock
+ * @{
*/
- EAPI void elm_entry_selection_paste(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This clears and frees the items in a entry's contextual (longpress)
- * menu.
- *
- * @param obj The entry object
+ * @typedef Elm_Entry_Anchorblock_Info
*
- * @see elm_entry_context_menu_item_add()
+ * The info sent in the callback for "anchor,clicked" signals emitted by
+ * the Anchorblock widget.
*/
- EAPI void elm_entry_context_menu_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Entry_Anchorblock_Info Elm_Entry_Anchorblock_Info;
/**
- * This adds an item to the entry's contextual menu.
- *
- * A longpress on an entry will make the contextual menu show up, if this
- * hasn't been disabled with elm_entry_context_menu_disabled_set().
- * By default, this menu provides a few options like enabling selection mode,
- * which is useful on embedded devices that need to be explicit about it,
- * and when a selection exists it also shows the copy and cut actions.
- *
- * With this function, developers can add other options to this menu to
- * perform any action they deem necessary.
+ * @struct _Elm_Entry_Anchorblock_Info
*
- * @param obj The entry object
- * @param label The item's text label
- * @param icon_file The item's icon file
- * @param icon_type The item's icon type
- * @param func The callback to execute when the item is clicked
- * @param data The data to associate with the item for related functions
+ * The info sent in the callback for "anchor,clicked" signals emitted by
+ * the Anchorblock widget.
*/
- EAPI void elm_entry_context_menu_item_add(Evas_Object *obj, const char *label, const char *icon_file, Elm_Icon_Type icon_type, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
+ struct _Elm_Entry_Anchorblock_Info
+ {
+ const char *name; /**< Name of the anchor, as indicated in its href
+ attribute */
+ int button; /**< The mouse button used to click on it */
+ Evas_Object *hover; /**< The hover object to use for the popup */
+ struct {
+ Evas_Coord x, y, w, h;
+ } anchor, /**< Geometry selection of text used as anchor */
+ hover_parent; /**< Geometry of the object used as parent by the
+ hover */
+ Eina_Bool hover_left : 1; /**< Hint indicating if there's space
+ for content on the left side of
+ the hover. Before calling the
+ callback, the widget will make the
+ necessary calculations to check
+ which sides are fit to be set with
+ content, based on the position the
+ hover is activated and its distance
+ to the edges of its parent object
+ */
+ Eina_Bool hover_right : 1; /**< Hint indicating content fits on
+ the right side of the hover.
+ See @ref hover_left */
+ Eina_Bool hover_top : 1; /**< Hint indicating content fits on top
+ of the hover. See @ref hover_left */
+ Eina_Bool hover_bottom : 1; /**< Hint indicating content fits
+ below the hover. See @ref
+ hover_left */
+ };
/**
- * This disables the entry's contextual (longpress) menu.
+ * Add a new Anchorblock object
*
- * @param obj The entry object
- * @param disabled If true, the menu is disabled
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*/
- EAPI void elm_entry_context_menu_disabled_set(Evas_Object *obj, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_anchorblock_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * This returns whether the entry's contextual (longpress) menu is
- * disabled.
+ * Set the text to show in the anchorblock
*
- * @param obj The entry object
- * @return If true, the menu is disabled
+ * Sets the text of the anchorblock to @p text. This text can include markup
+ * format tags, including <c>\<a href=anchorname\></a></c> to begin a segment
+ * of text that will be specially styled and react to click events, ended
+ * with either of \</a\> or \</\>. When clicked, the anchor will emit an
+ * "anchor,clicked" signal that you can attach a callback to with
+ * evas_object_smart_callback_add(). The name of the anchor given in the
+ * event info struct will be the one set in the href attribute, in this
+ * case, anchorname.
+ *
+ * Other markup can be used to style the text in different ways, but it's
+ * up to the style defined in the theme which tags do what.
+ * @deprecated use elm_object_text_set() instead.
*/
- EAPI Eina_Bool elm_entry_context_menu_disabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI void elm_anchorblock_text_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
/**
- * This appends a custom item provider to the list for that entry
- *
- * This appends the given callback. The list is walked from beginning to end
- * with each function called given the item href string in the text. If the
- * function returns an object handle other than NULL (it should create an
- * object to do this), then this object is used to replace that item. If
- * not the next provider is called until one provides an item object, or the
- * default provider in entry does.
+ * Get the markup text set for the anchorblock
*
- * @param obj The entry object
- * @param func The function called to provide the item object
- * @param data The data passed to @p func
+ * Retrieves the text set on the anchorblock, with markup tags included.
*
- * @see @ref entry-items
+ * @param obj The anchorblock object
+ * @return The markup text set or @c NULL if nothing was set or an error
+ * occurred
+ * @deprecated use elm_object_text_set() instead.
*/
- EAPI void elm_entry_item_provider_append(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *entry, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ EINA_DEPRECATED EAPI const char *elm_anchorblock_text_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This prepends a custom item provider to the list for that entry
+ * Set the parent of the hover popup
*
- * This prepends the given callback. See elm_entry_item_provider_append() for
- * more information
+ * Sets the parent object to use by the hover created by the anchorblock
+ * when an anchor is clicked. See @ref Hover for more details on this.
*
- * @param obj The entry object
- * @param func The function called to provide the item object
- * @param data The data passed to @p func
+ * @param obj The anchorblock object
+ * @param parent The object to use as parent for the hover
*/
- EAPI void elm_entry_item_provider_prepend(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *entry, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI void elm_anchorblock_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * This removes a custom item provider to the list for that entry
+ * Get the parent of the hover popup
*
- * This removes the given callback. See elm_entry_item_provider_append() for
- * more information
+ * Get the object used as parent for the hover created by the anchorblock
+ * widget. See @ref Hover for more details on this.
+ * If no parent is set, the same anchorblock object will be used.
*
- * @param obj The entry object
- * @param func The function called to provide the item object
- * @param data The data passed to @p func
+ * @param obj The anchorblock object
+ * @return The object used as parent for the hover, NULL if none is set.
*/
- EAPI void elm_entry_item_provider_remove(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *entry, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI Evas_Object *elm_anchorblock_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Append a filter function for text inserted in the entry
+ * Set the style that the hover should use
*
- * Append the given callback to the list. This functions will be called
- * whenever any text is inserted into the entry, with the text to be inserted
- * as a parameter. The callback function is free to alter the text in any way
- * it wants, but it must remember to free the given pointer and update it.
- * If the new text is to be discarded, the function can free it and set its
- * text parameter to NULL. This will also prevent any following filters from
- * being called.
+ * When creating the popup hover, anchorblock will request that it's
+ * themed according to @p style.
*
- * @param obj The entry object
- * @param func The function to use as text filter
- * @param data User data to pass to @p func
+ * @param obj The anchorblock object
+ * @param style The style to use for the underlying hover
+ *
+ * @see elm_object_style_set()
*/
- EAPI void elm_entry_text_filter_append(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI void elm_anchorblock_hover_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
/**
- * Prepend a filter function for text insdrted in the entry
+ * Get the style that the hover should use
*
- * Prepend the given callback to the list. See elm_entry_text_filter_append()
- * for more information
+ * Get the style the hover created by anchorblock will use.
*
- * @param obj The entry object
- * @param func The function to use as text filter
- * @param data User data to pass to @p func
+ * @param obj The anchorblock object
+ * @return The style to use by the hover. NULL means the default is used.
+ *
+ * @see elm_object_style_set()
*/
- EAPI void elm_entry_text_filter_prepend(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI const char *elm_anchorblock_hover_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Remove a filter from the list
+ * Ends the hover popup in the anchorblock
*
- * Removes the given callback from the filter list. See
- * elm_entry_text_filter_append() for more information.
+ * When an anchor is clicked, the anchorblock widget will create a hover
+ * object to use as a popup with user provided content. This function
+ * terminates this popup, returning the anchorblock to its normal state.
*
- * @param obj The entry object
- * @param func The filter function to remove
- * @param data The user data passed when adding the function
+ * @param obj The anchorblock object
*/
- EAPI void elm_entry_text_filter_remove(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI void elm_anchorblock_hover_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This converts a markup (HTML-like) string into UTF-8.
+ * Appends a custom item provider to the given anchorblock
*
- * The returned string is a malloc'ed buffer and it should be freed when
- * not needed anymore.
+ * Appends the given function to the list of items providers. This list is
+ * called, one function at a time, with the given @p data pointer, the
+ * anchorblock object and, in the @p item parameter, the item name as
+ * referenced in its href string. Following functions in the list will be
+ * called in order until one of them returns something different to NULL,
+ * which should be an Evas_Object which will be used in place of the item
+ * element.
*
- * @param s The string (in markup) to be converted
- * @return The converted string (in UTF-8). It should be freed.
- */
- EAPI char *elm_entry_markup_to_utf8(const char *s) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
- /**
- * This converts a UTF-8 string into markup (HTML-like).
+ * Items in the markup text take the form \<item relsize=16x16 vsize=full
+ * href=item/name\>\</item\>
*
- * The returned string is a malloc'ed buffer and it should be freed when
- * not needed anymore.
+ * @param obj The anchorblock object
+ * @param func The function to add to the list of providers
+ * @param data User data that will be passed to the callback function
*
- * @param s The string (in UTF-8) to be converted
- * @return The converted string (in markup). It should be freed.
+ * @see elm_entry_item_provider_append()
*/
- EAPI char *elm_entry_utf8_to_markup(const char *s) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+ EAPI void elm_anchorblock_item_provider_append(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorblock, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
/**
- * This sets the file (and implicitly loads it) for the text to display and
- * then edit. All changes are written back to the file after a short delay if
- * the entry object is set to autosave (which is the default).
+ * Prepend a custom item provider to the given anchorblock
*
- * If the entry had any other file set previously, any changes made to it
- * will be saved if the autosave feature is enabled, otherwise, the file
- * will be silently discarded and any non-saved changes will be lost.
+ * Like elm_anchorblock_item_provider_append(), but it adds the function
+ * @p func to the beginning of the list, instead of the end.
*
- * @param obj The entry object
- * @param file The path to the file to load and save
- * @param format The file format
+ * @param obj The anchorblock object
+ * @param func The function to add to the list of providers
+ * @param data User data that will be passed to the callback function
*/
- EAPI void elm_entry_file_set(Evas_Object *obj, const char *file, Elm_Text_Format format) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorblock_item_provider_prepend(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorblock, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
/**
- * Gets the file being edited by the entry.
+ * Remove a custom item provider from the list of the given anchorblock
*
- * This function can be used to retrieve any file set on the entry for
- * edition, along with the format used to load and save it.
+ * Removes the function and data pairing that matches @p func and @p data.
+ * That is, unless the same function and same user data are given, the
+ * function will not be removed from the list. This allows us to add the
+ * same callback several times, with different @p data pointers and be
+ * able to remove them later without conflicts.
*
- * @param obj The entry object
- * @param file The path to the file to load and save
- * @param format The file format
+ * @param obj The anchorblock object
+ * @param func The function to remove from the list
+ * @param data The data matching the function to remove from the list
*/
- EAPI void elm_entry_file_get(const Evas_Object *obj, const char **file, Elm_Text_Format *format) EINA_ARG_NONNULL(1);
+ EAPI void elm_anchorblock_item_provider_remove(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorblock, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
/**
- * This function writes any changes made to the file set with
- * elm_entry_file_set()
- *
- * @param obj The entry object
+ * @}
*/
- EAPI void elm_entry_file_save(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * This sets the entry object to 'autosave' the loaded text file or not.
+ * @defgroup Bubble Bubble
*
- * @param obj The entry object
- * @param autosave Autosave the loaded file or not
+ * @image html img/widget/bubble/preview-00.png
+ * @image latex img/widget/bubble/preview-00.eps
+ * @image html img/widget/bubble/preview-01.png
+ * @image latex img/widget/bubble/preview-01.eps
+ * @image html img/widget/bubble/preview-02.png
+ * @image latex img/widget/bubble/preview-02.eps
*
- * @see elm_entry_file_set()
- */
- EAPI void elm_entry_autosave_set(Evas_Object *obj, Eina_Bool autosave) EINA_ARG_NONNULL(1);
- /**
- * This gets the entry object's 'autosave' status.
+ * @brief The Bubble is a widget to show text similarly to how speech is
+ * represented in comics.
*
- * @param obj The entry object
- * @return Autosave the loaded file or not
+ * The bubble widget contains 5 important visual elements:
+ * @li The frame is a rectangle with rounded rectangles and an "arrow".
+ * @li The @p icon is an image to which the frame's arrow points to.
+ * @li The @p label is a text which appears to the right of the icon if the
+ * corner is "top_left" or "bottom_left" and is right aligned to the frame
+ * otherwise.
+ * @li The @p info is a text which appears to the right of the label. Info's
+ * font is of a ligther color than label.
+ * @li The @p content is an evas object that is shown inside the frame.
*
- * @see elm_entry_file_set()
- */
- EAPI Eina_Bool elm_entry_autosave_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Control pasting of text and images for the widget.
+ * The position of the arrow, icon, label and info depends on which corner is
+ * selected. The four available corners are:
+ * @li "top_left" - Default
+ * @li "top_right"
+ * @li "bottom_left"
+ * @li "bottom_right"
*
- * Normally the entry allows both text and images to be pasted. By setting
- * textonly to be true, this prevents images from being pasted.
+ * Signals that you can add callbacks for are:
+ * @li "clicked" - This is called when a user has clicked the bubble.
*
- * Note this only changes the behaviour of text.
+ * For an example of using a buble see @ref bubble_01_example_page "this".
*
- * @param obj The entry object
- * @param textonly paste mode - EINA_TRUE is text only, EINA_FALSE is
- * text+image+other.
+ * @{
*/
- EAPI void elm_entry_cnp_textonly_set(Evas_Object *obj, Eina_Bool textonly) EINA_ARG_NONNULL(1);
/**
- * Getting elm_entry text paste/drop mode.
+ * Add a new bubble to the parent
*
- * In textonly mode, only text may be pasted or dropped into the widget.
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
*
- * @param obj The entry object
- * @return If the widget only accepts text from pastes.
+ * This function adds a text bubble to the given parent evas object.
*/
- EAPI Eina_Bool elm_entry_cnp_textonly_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_bubble_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * Enable or disable scrolling in entry
+ * Set the label of the bubble
*
- * Normally the entry is not scrollable unless you enable it with this call.
+ * @param obj The bubble object
+ * @param label The string to set in the label
*
- * @param obj The entry object
- * @param scroll EINA_TRUE if it is to be scrollable, EINA_FALSE otherwise
+ * This function sets the title of the bubble. Where this appears depends on
+ * the selected corner.
+ * @deprecated use elm_object_text_set() instead.
*/
- EAPI void elm_entry_scrollable_set(Evas_Object *obj, Eina_Bool scroll);
+ EINA_DEPRECATED EAPI void elm_bubble_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
/**
- * Get the scrollable state of the entry
+ * Get the label of the bubble
*
- * Normally the entry is not scrollable. This gets the scrollable state
- * of the entry. See elm_entry_scrollable_set() for more information.
+ * @param obj The bubble object
+ * @return The string of set in the label
*
- * @param obj The entry object
- * @return The scrollable state
+ * This function gets the title of the bubble.
+ * @deprecated use elm_object_text_get() instead.
*/
- EAPI Eina_Bool elm_entry_scrollable_get(const Evas_Object *obj);
+ EINA_DEPRECATED EAPI const char *elm_bubble_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This sets a widget to be displayed to the left of a scrolled entry.
- *
- * @param obj The scrolled entry object
- * @param icon The widget to display on the left side of the scrolled
- * entry.
+ * Set the info of the bubble
*
- * @note A previously set widget will be destroyed.
- * @note If the object being set does not have minimum size hints set,
- * it won't get properly displayed.
+ * @param obj The bubble object
+ * @param info The given info about the bubble
*
- * @see elm_entry_end_set()
+ * This function sets the info of the bubble. Where this appears depends on
+ * the selected corner.
+ * @deprecated use elm_object_text_part_set() instead. (with "info" as the parameter).
*/
- EAPI void elm_entry_icon_set(Evas_Object *obj, Evas_Object *icon);
+ EINA_DEPRECATED EAPI void elm_bubble_info_set(Evas_Object *obj, const char *info) EINA_ARG_NONNULL(1);
/**
- * Gets the leftmost widget of the scrolled entry. This object is
- * owned by the scrolled entry and should not be modified.
+ * Get the info of the bubble
*
- * @param obj The scrolled entry object
- * @return the left widget inside the scroller
+ * @param obj The bubble object
+ *
+ * @return The "info" string of the bubble
+ *
+ * This function gets the info text.
+ * @deprecated use elm_object_text_part_get() instead. (with "info" as the parameter).
*/
- EAPI Evas_Object *elm_entry_icon_get(const Evas_Object *obj);
+ EINA_DEPRECATED EAPI const char *elm_bubble_info_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Unset the leftmost widget of the scrolled entry, unparenting and
- * returning it.
+ * Set the content to be shown in the bubble
*
- * @param obj The scrolled entry object
- * @return the previously set icon sub-object of this entry, on
- * success.
+ * Once the content object is set, a previously set one will be deleted.
+ * If you want to keep the old content object, use the
+ * elm_bubble_content_unset() function.
*
- * @see elm_entry_icon_set()
+ * @param obj The bubble object
+ * @param content The given content of the bubble
+ *
+ * This function sets the content shown on the middle of the bubble.
*/
- EAPI Evas_Object *elm_entry_icon_unset(Evas_Object *obj);
+ EAPI void elm_bubble_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
/**
- * Sets the visibility of the left-side widget of the scrolled entry,
- * set by elm_entry_icon_set().
+ * Get the content shown in the bubble
*
- * @param obj The scrolled entry object
- * @param setting EINA_TRUE if the object should be displayed,
- * EINA_FALSE if not.
+ * Return the content object which is set for this widget.
+ *
+ * @param obj The bubble object
+ * @return The content that is being used
*/
- EAPI void elm_entry_icon_visible_set(Evas_Object *obj, Eina_Bool setting);
+ EAPI Evas_Object *elm_bubble_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This sets a widget to be displayed to the end of a scrolled entry.
- *
- * @param obj The scrolled entry object
- * @param end The widget to display on the right side of the scrolled
- * entry.
+ * Unset the content shown in the bubble
*
- * @note A previously set widget will be destroyed.
- * @note If the object being set does not have minimum size hints set,
- * it won't get properly displayed.
+ * Unparent and return the content object which was set for this widget.
*
- * @see elm_entry_icon_set
+ * @param obj The bubble object
+ * @return The content that was being used
*/
- EAPI void elm_entry_end_set(Evas_Object *obj, Evas_Object *end);
+ EAPI Evas_Object *elm_bubble_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Gets the endmost widget of the scrolled entry. This object is owned
- * by the scrolled entry and should not be modified.
+ * Set the icon of the bubble
*
- * @param obj The scrolled entry object
- * @return the right widget inside the scroller
+ * Once the icon object is set, a previously set one will be deleted.
+ * If you want to keep the old content object, use the
+ * elm_icon_content_unset() function.
+ *
+ * @param obj The bubble object
+ * @param icon The given icon for the bubble
*/
- EAPI Evas_Object *elm_entry_end_get(const Evas_Object *obj);
+ EAPI void elm_bubble_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
/**
- * Unset the endmost widget of the scrolled entry, unparenting and
- * returning it.
+ * Get the icon of the bubble
*
- * @param obj The scrolled entry object
- * @return the previously set icon sub-object of this entry, on
- * success.
+ * @param obj The bubble object
+ * @return The icon for the bubble
*
- * @see elm_entry_icon_set()
+ * This function gets the icon shown on the top left of bubble.
*/
- EAPI Evas_Object *elm_entry_end_unset(Evas_Object *obj);
+ EAPI Evas_Object *elm_bubble_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Sets the visibility of the end widget of the scrolled entry, set by
- * elm_entry_end_set().
+ * Unset the icon of the bubble
*
- * @param obj The scrolled entry object
- * @param setting EINA_TRUE if the object should be displayed,
- * EINA_FALSE if not.
+ * Unparent and return the icon object which was set for this widget.
+ *
+ * @param obj The bubble object
+ * @return The icon that was being used
*/
- EAPI void elm_entry_end_visible_set(Evas_Object *obj, Eina_Bool setting);
+ EAPI Evas_Object *elm_bubble_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * This sets the scrolled entry's scrollbar policy (ie. enabling/disabling
- * them).
+ * Set the corner of the bubble
*
- * Setting an entry to single-line mode with elm_entry_single_line_set()
- * will automatically disable the display of scrollbars when the entry
- * moves inside its scroller.
+ * @param obj The bubble object.
+ * @param corner The given corner for the bubble.
*
- * @param obj The scrolled entry object
- * @param h The horizontal scrollbar policy to apply
- * @param v The vertical scrollbar policy to apply
+ * This function sets the corner of the bubble. The corner will be used to
+ * determine where the arrow in the frame points to and where label, icon and
+ * info arre shown.
+ *
+ * Possible values for corner are:
+ * @li "top_left" - Default
+ * @li "top_right"
+ * @li "bottom_left"
+ * @li "bottom_right"
*/
- EAPI void elm_entry_scrollbar_policy_set(Evas_Object *obj, Elm_Scroller_Policy h, Elm_Scroller_Policy v);
+ EAPI void elm_bubble_corner_set(Evas_Object *obj, const char *corner) EINA_ARG_NONNULL(1, 2);
/**
- * This enables/disables bouncing within the entry.
+ * Get the corner of the bubble
*
- * This function sets whether the entry will bounce when scrolling reaches
- * the end of the contained entry.
+ * @param obj The bubble object.
+ * @return The given corner for the bubble.
*
- * @param obj The scrolled entry object
- * @param h The horizontal bounce state
- * @param v The vertical bounce state
+ * This function gets the selected corner of the bubble.
*/
- EAPI void elm_entry_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
+ EAPI const char *elm_bubble_corner_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the bounce mode
- *
- * @param obj The Entry object
- * @param h_bounce Allow bounce horizontally
- * @param v_bounce Allow bounce vertically
+ * @}
*/
- EAPI void elm_entry_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
- /* pre-made filters for entries */
/**
- * @typedef Elm_Entry_Filter_Limit_Size
+ * @defgroup Photo Photo
*
- * Data for the elm_entry_filter_limit_size() entry filter.
+ * For displaying the photo of a person (contact). Simple yet
+ * with a very specific purpose.
+ *
+ * Signals that you can add callbacks for are:
+ *
+ * "clicked" - This is called when a user has clicked the photo
+ * "drag,start" - Someone started dragging the image out of the object
+ * "drag,end" - Dragged item was dropped (somewhere)
+ *
+ * @{
*/
- typedef struct _Elm_Entry_Filter_Limit_Size Elm_Entry_Filter_Limit_Size;
+
/**
- * @struct _Elm_Entry_Filter_Limit_Size
+ * Add a new photo to the parent
*
- * Data for the elm_entry_filter_limit_size() entry filter.
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ *
+ * @ingroup Photo
*/
- struct _Elm_Entry_Filter_Limit_Size
- {
- int max_char_count; /**< The maximum number of characters allowed. */
- int max_byte_count; /**< The maximum number of bytes allowed*/
- };
+ EAPI Evas_Object *elm_photo_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
/**
- * Filter inserted text based on user defined character and byte limits
- *
- * Add this filter to an entry to limit the characters that it will accept
- * based the the contents of the provided #Elm_Entry_Filter_Limit_Size.
- * The funtion works on the UTF-8 representation of the string, converting
- * it from the set markup, thus not accounting for any format in it.
+ * Set the file that will be used as photo
*
- * The user must create an #Elm_Entry_Filter_Limit_Size structure and pass
- * it as data when setting the filter. In it, it's possible to set limits
- * by character count or bytes (any of them is disabled if 0), and both can
- * be set at the same time. In that case, it first checks for characters,
- * then bytes.
+ * @param obj The photo object
+ * @param file The path to file that will be used as photo
*
- * The function will cut the inserted text in order to allow only the first
- * number of characters that are still allowed. The cut is made in
- * characters, even when limiting by bytes, in order to always contain
- * valid ones and avoid half unicode characters making it in.
+ * @return (1 = success, 0 = error)
*
- * This filter, like any others, does not apply when setting the entry text
- * directly with elm_object_text_set() (or the deprecated
- * elm_entry_entry_set()).
+ * @ingroup Photo
*/
- EAPI void elm_entry_filter_limit_size(void *data, Evas_Object *entry, char **text) EINA_ARG_NONNULL(1, 2, 3);
- /**
- * @typedef Elm_Entry_Filter_Accept_Set
+ EAPI Eina_Bool elm_photo_file_set(Evas_Object *obj, const char *file) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the file that will be used as thumbnail in the photo.
*
- * Data for the elm_entry_filter_accept_set() entry filter.
+ * @param obj The photo object.
+ * @param file The path to file that will be used as thumb.
+ * @param group The key used in case of an EET file.
+ *
+ * @ingroup Photo
*/
- typedef struct _Elm_Entry_Filter_Accept_Set Elm_Entry_Filter_Accept_Set;
+ EAPI void elm_photo_thumb_set(const Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
+
/**
- * @struct _Elm_Entry_Filter_Accept_Set
+ * Set the size that will be used on the photo
*
- * Data for the elm_entry_filter_accept_set() entry filter.
+ * @param obj The photo object
+ * @param size The size that the photo will be
+ *
+ * @ingroup Photo
*/
- struct _Elm_Entry_Filter_Accept_Set
- {
- const char *accepted; /**< Set of characters accepted in the entry. */
- const char *rejected; /**< Set of characters rejected from the entry. */
- };
+ EAPI void elm_photo_size_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
+
/**
- * Filter inserted text based on accepted or rejected sets of characters
+ * Set if the photo should be completely visible or not.
*
- * Add this filter to an entry to restrict the set of accepted characters
- * based on the sets in the provided #Elm_Entry_Filter_Accept_Set.
- * This structure contains both accepted and rejected sets, but they are
- * mutually exclusive.
+ * @param obj The photo object
+ * @param fill if true the photo will be completely visible
*
- * The @c accepted set takes preference, so if it is set, the filter will
- * only work based on the accepted characters, ignoring anything in the
- * @c rejected value. If @c accepted is @c NULL, then @c rejected is used.
+ * @ingroup Photo
+ */
+ EAPI void elm_photo_fill_inside_set(Evas_Object *obj, Eina_Bool fill) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set editability of the photo.
*
- * In both cases, the function filters by matching utf8 characters to the
- * raw markup text, so it can be used to remove formatting tags.
+ * An editable photo can be dragged to or from, and can be cut or
+ * pasted too. Note that pasting an image or dropping an item on
+ * the image will delete the existing content.
*
- * This filter, like any others, does not apply when setting the entry text
- * directly with elm_object_text_set() (or the deprecated
- * elm_entry_entry_set()).
+ * @param obj The photo object.
+ * @param set To set of clear editablity.
*/
- EAPI void elm_entry_filter_accept_set(void *data, Evas_Object *entry, char **text) EINA_ARG_NONNULL(1, 3);
+ EAPI void elm_photo_editable_set(Evas_Object *obj, Eina_Bool set) EINA_ARG_NONNULL(1);
+
/**
* @}
*/
- /* composite widgets - these basically put together basic widgets above
- * in convenient packages that do more than basic stuff */
-
- /* anchorview */
+ /* gesture layer */
/**
- * @defgroup Anchorview Anchorview
+ * @defgroup Elm_Gesture_Layer Gesture Layer
+ * Gesture Layer Usage:
*
- * @image html img/widget/anchorview/preview-00.png
- * @image latex img/widget/anchorview/preview-00.eps
+ * Use Gesture Layer to detect gestures.
+ * The advantage is that you don't have to implement
+ * gesture detection, just set callbacks of gesture state.
+ * By using gesture layer we make standard interface.
*
- * Anchorview is for displaying text that contains markup with anchors
- * like <c>\<a href=1234\>something\</\></c> in it.
+ * In order to use Gesture Layer you start with @ref elm_gesture_layer_add
+ * with a parent object parameter.
+ * Next 'activate' gesture layer with a @ref elm_gesture_layer_attach
+ * call. Usually with same object as target (2nd parameter).
*
- * Besides being styled differently, the anchorview widget provides the
- * necessary functionality so that clicking on these anchors brings up a
- * popup with user defined content such as "call", "add to contacts" or
- * "open web page". This popup is provided using the @ref Hover widget.
+ * Now you need to tell gesture layer what gestures you follow.
+ * This is done with @ref elm_gesture_layer_cb_set call.
+ * By setting the callback you actually saying to gesture layer:
+ * I would like to know when the gesture @ref Elm_Gesture_Types
+ * switches to state @ref Elm_Gesture_State.
*
- * This widget is very similar to @ref Anchorblock, so refer to that
- * widget for an example. The only difference Anchorview has is that the
- * widget is already provided with scrolling functionality, so if the
- * text set to it is too large to fit in the given space, it will scroll,
- * whereas the @ref Anchorblock widget will keep growing to ensure all the
- * text can be displayed.
+ * Next, you need to implement the actual action that follows the input
+ * in your callback.
*
- * This widget emits the following signals:
- * @li "anchor,clicked": will be called when an anchor is clicked. The
- * @p event_info parameter on the callback will be a pointer of type
- * ::Elm_Entry_Anchorview_Info.
+ * Note that if you like to stop being reported about a gesture, just set
+ * all callbacks referring this gesture to NULL.
+ * (again with @ref elm_gesture_layer_cb_set)
*
- * See @ref Anchorblock for an example on how to use both of them.
+ * The information reported by gesture layer to your callback is depending
+ * on @ref Elm_Gesture_Types:
+ * @ref Elm_Gesture_Taps_Info is the info reported for tap gestures:
+ * @ref ELM_GESTURE_N_TAPS, @ref ELM_GESTURE_N_LONG_TAPS,
+ * @ref ELM_GESTURE_N_DOUBLE_TAPS, @ref ELM_GESTURE_N_TRIPLE_TAPS.
+ *
+ * @ref Elm_Gesture_Momentum_Info is info reported for momentum gestures:
+ * @ref ELM_GESTURE_MOMENTUM.
+ *
+ * @ref Elm_Gesture_Line_Info is the info reported for line gestures:
+ * (this also contains @ref Elm_Gesture_Momentum_Info internal structure)
+ * @ref ELM_GESTURE_N_LINES, @ref ELM_GESTURE_N_FLICKS.
+ * Note that we consider a flick as a line-gesture that should be completed
+ * in flick-time-limit as defined in @ref Config.
+ *
+ * @ref Elm_Gesture_Zoom_Info is the info reported for @ref ELM_GESTURE_ZOOM gesture.
+ *
+ * @ref Elm_Gesture_Rotate_Info is the info reported for @ref ELM_GESTURE_ROTATE gesture.
+ *
+ *
+ * Gesture Layer Tweaks:
*
- * @see Anchorblock
- * @see Entry
- * @see Hover
+ * Note that line, flick, gestures can start without the need to remove fingers from surface.
+ * When user fingers rests on same-spot gesture is ended and starts again when fingers moved.
*
- * @{
+ * Setting glayer_continues_enable to false in @ref Config will change this behavior
+ * so gesture starts when user touches (a *DOWN event) touch-surface
+ * and ends when no fingers touches surface (a *UP event).
*/
+
/**
- * @typedef Elm_Entry_Anchorview_Info
- *
- * The info sent in the callback for "anchor,clicked" signals emitted by
- * the Anchorview widget.
+ * @enum _Elm_Gesture_Types
+ * Enum of supported gesture types.
+ * @ingroup Elm_Gesture_Layer
*/
- typedef struct _Elm_Entry_Anchorview_Info Elm_Entry_Anchorview_Info;
+ enum _Elm_Gesture_Types
+ {
+ ELM_GESTURE_FIRST = 0,
+
+ ELM_GESTURE_N_TAPS, /**< N fingers single taps */
+ ELM_GESTURE_N_LONG_TAPS, /**< N fingers single long-taps */
+ ELM_GESTURE_N_DOUBLE_TAPS, /**< N fingers double-single taps */
+ ELM_GESTURE_N_TRIPLE_TAPS, /**< N fingers triple-single taps */
+
+ ELM_GESTURE_MOMENTUM, /**< Reports momentum in the dircetion of move */
+
+ ELM_GESTURE_N_LINES, /**< N fingers line gesture */
+ ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
+
+ ELM_GESTURE_ZOOM, /**< Zoom */
+ ELM_GESTURE_ROTATE, /**< Rotate */
+
+ ELM_GESTURE_LAST
+ };
+
/**
- * @struct _Elm_Entry_Anchorview_Info
- *
- * The info sent in the callback for "anchor,clicked" signals emitted by
- * the Anchorview widget.
+ * @typedef Elm_Gesture_Types
+ * gesture types enum
+ * @ingroup Elm_Gesture_Layer
*/
- struct _Elm_Entry_Anchorview_Info
+ typedef enum _Elm_Gesture_Types Elm_Gesture_Types;
+
+ /**
+ * @enum _Elm_Gesture_State
+ * Enum of gesture states.
+ * @ingroup Elm_Gesture_Layer
+ */
+ enum _Elm_Gesture_State
{
- const char *name; /**< Name of the anchor, as indicated in its href
- attribute */
- int button; /**< The mouse button used to click on it */
- Evas_Object *hover; /**< The hover object to use for the popup */
- struct {
- Evas_Coord x, y, w, h;
- } anchor, /**< Geometry selection of text used as anchor */
- hover_parent; /**< Geometry of the object used as parent by the
- hover */
- Eina_Bool hover_left : 1; /**< Hint indicating if there's space
- for content on the left side of
- the hover. Before calling the
- callback, the widget will make the
- necessary calculations to check
- which sides are fit to be set with
- content, based on the position the
- hover is activated and its distance
- to the edges of its parent object
- */
- Eina_Bool hover_right : 1; /**< Hint indicating content fits on
- the right side of the hover.
- See @ref hover_left */
- Eina_Bool hover_top : 1; /**< Hint indicating content fits on top
- of the hover. See @ref hover_left */
- Eina_Bool hover_bottom : 1; /**< Hint indicating content fits
- below the hover. See @ref
- hover_left */
+ ELM_GESTURE_STATE_UNDEFINED = -1, /**< Gesture not STARTed */
+ ELM_GESTURE_STATE_START, /**< Gesture STARTed */
+ ELM_GESTURE_STATE_MOVE, /**< Gesture is ongoing */
+ ELM_GESTURE_STATE_END, /**< Gesture completed */
+ ELM_GESTURE_STATE_ABORT /**< Onging gesture was ABORTed */
};
+
/**
- * Add a new Anchorview object
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * @typedef Elm_Gesture_State
+ * gesture states enum
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI Evas_Object *elm_anchorview_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ typedef enum _Elm_Gesture_State Elm_Gesture_State;
+
/**
- * Set the text to show in the anchorview
- *
- * Sets the text of the anchorview to @p text. This text can include markup
- * format tags, including <c>\<a href=anchorname\></c> to begin a segment of
- * text that will be specially styled and react to click events, ended with
- * either of \</a\> or \</\>. When clicked, the anchor will emit an
- * "anchor,clicked" signal that you can attach a callback to with
- * evas_object_smart_callback_add(). The name of the anchor given in the
- * event info struct will be the one set in the href attribute, in this
- * case, anchorname.
- *
- * Other markup can be used to style the text in different ways, but it's
- * up to the style defined in the theme which tags do what.
- * @deprecated use elm_object_text_set() instead.
+ * @struct _Elm_Gesture_Taps_Info
+ * Struct holds taps info for user
+ * @ingroup Elm_Gesture_Layer
*/
- EINA_DEPRECATED EAPI void elm_anchorview_text_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
+ struct _Elm_Gesture_Taps_Info
+ {
+ Evas_Coord x, y; /**< Holds center point between fingers */
+ unsigned int n; /**< Number of fingers tapped */
+ unsigned int timestamp; /**< event timestamp */
+ };
+
/**
- * Get the markup text set for the anchorview
- *
- * Retrieves the text set on the anchorview, with markup tags included.
- *
- * @param obj The anchorview object
- * @return The markup text set or @c NULL if nothing was set or an error
- * occurred
- * @deprecated use elm_object_text_set() instead.
+ * @typedef Elm_Gesture_Taps_Info
+ * holds taps info for user
+ * @ingroup Elm_Gesture_Layer
*/
- EINA_DEPRECATED EAPI const char *elm_anchorview_text_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
+
/**
- * Set the parent of the hover popup
- *
- * Sets the parent object to use by the hover created by the anchorview
- * when an anchor is clicked. See @ref Hover for more details on this.
- * If no parent is set, the same anchorview object will be used.
- *
- * @param obj The anchorview object
- * @param parent The object to use as parent for the hover
+ * @struct _Elm_Gesture_Momentum_Info
+ * Struct holds momentum info for user
+ * x1 and y1 are not necessarily in sync
+ * x1 holds x value of x direction starting point
+ * and same holds for y1.
+ * This is noticeable when doing V-shape movement
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI void elm_anchorview_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+ struct _Elm_Gesture_Momentum_Info
+ { /* Report line ends, timestamps, and momentum computed */
+ Evas_Coord x1; /**< Final-swipe direction starting point on X */
+ Evas_Coord y1; /**< Final-swipe direction starting point on Y */
+ Evas_Coord x2; /**< Final-swipe direction ending point on X */
+ Evas_Coord y2; /**< Final-swipe direction ending point on Y */
+
+ unsigned int tx; /**< Timestamp of start of final x-swipe */
+ unsigned int ty; /**< Timestamp of start of final y-swipe */
+
+ Evas_Coord mx; /**< Momentum on X */
+ Evas_Coord my; /**< Momentum on Y */
+ };
+
/**
- * Get the parent of the hover popup
- *
- * Get the object used as parent for the hover created by the anchorview
- * widget. See @ref Hover for more details on this.
- *
- * @param obj The anchorview object
- * @return The object used as parent for the hover, NULL if none is set.
+ * @typedef Elm_Gesture_Momentum_Info
+ * holds momentum info for user
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI Evas_Object *elm_anchorview_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
+
/**
- * Set the style that the hover should use
- *
- * When creating the popup hover, anchorview will request that it's
- * themed according to @p style.
- *
- * @param obj The anchorview object
- * @param style The style to use for the underlying hover
- *
- * @see elm_object_style_set()
+ * @struct _Elm_Gesture_Line_Info
+ * Struct holds line info for user
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI void elm_anchorview_hover_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
+ struct _Elm_Gesture_Line_Info
+ { /* Report line ends, timestamps, and momentum computed */
+ Elm_Gesture_Momentum_Info momentum; /**< Line momentum info */
+ unsigned int n; /**< Number of fingers (lines) */
+ /* FIXME should be radians, bot degrees */
+ double angle; /**< Angle (direction) of lines */
+ };
+
/**
- * Get the style that the hover should use
- *
- * Get the style the hover created by anchorview will use.
- *
- * @param obj The anchorview object
- * @return The style to use by the hover. NULL means the default is used.
- *
- * @see elm_object_style_set()
+ * @typedef Elm_Gesture_Line_Info
+ * Holds line info for user
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI const char *elm_anchorview_hover_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
+
/**
- * Ends the hover popup in the anchorview
- *
- * When an anchor is clicked, the anchorview widget will create a hover
- * object to use as a popup with user provided content. This function
- * terminates this popup, returning the anchorview to its normal state.
- *
- * @param obj The anchorview object
+ * @struct _Elm_Gesture_Zoom_Info
+ * Struct holds zoom info for user
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI void elm_anchorview_hover_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ struct _Elm_Gesture_Zoom_Info
+ {
+ Evas_Coord x, y; /**< Holds zoom center point reported to user */
+ Evas_Coord radius; /**< Holds radius between fingers reported to user */
+ double zoom; /**< Zoom value: 1.0 means no zoom */
+ double momentum; /**< Zoom momentum: zoom growth per second (NOT YET SUPPORTED) */
+ };
+
/**
- * Set bouncing behaviour when the scrolled content reaches an edge
- *
- * Tell the internal scroller object whether it should bounce or not
- * when it reaches the respective edges for each axis.
- *
- * @param obj The anchorview object
- * @param h_bounce Whether to bounce or not in the horizontal axis
- * @param v_bounce Whether to bounce or not in the vertical axis
- *
- * @see elm_scroller_bounce_set()
+ * @typedef Elm_Gesture_Zoom_Info
+ * Holds zoom info for user
+ * @ingroup Elm_Gesture_Layer
+ */
+ typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
+
+ /**
+ * @struct _Elm_Gesture_Rotate_Info
+ * Struct holds rotation info for user
+ * @ingroup Elm_Gesture_Layer
+ */
+ struct _Elm_Gesture_Rotate_Info
+ {
+ Evas_Coord x, y; /**< Holds zoom center point reported to user */
+ Evas_Coord radius; /**< Holds radius between fingers reported to user */
+ double base_angle; /**< Holds start-angle */
+ double angle; /**< Rotation value: 0.0 means no rotation */
+ double momentum; /**< Rotation momentum: rotation done per second (NOT YET SUPPORTED) */
+ };
+
+ /**
+ * @typedef Elm_Gesture_Rotate_Info
+ * Holds rotation info for user
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI void elm_anchorview_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
+ typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
+
/**
- * Get the set bouncing behaviour of the internal scroller
- *
- * Get whether the internal scroller should bounce when the edge of each
- * axis is reached scrolling.
- *
- * @param obj The anchorview object
- * @param h_bounce Pointer where to store the bounce state of the horizontal
- * axis
- * @param v_bounce Pointer where to store the bounce state of the vertical
- * axis
+ * @typedef Elm_Gesture_Event_Cb
+ * User callback used to stream gesture info from gesture layer
+ * @param data user data
+ * @param event_info gesture report info
+ * Returns a flag field to be applied on the causing event.
+ * You should probably return EVAS_EVENT_FLAG_ON_HOLD if your widget acted
+ * upon the event, in an irreversible way.
*
- * @see elm_scroller_bounce_get()
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI void elm_anchorview_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
+ typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb) (void *data, void *event_info);
+
/**
- * Appends a custom item provider to the given anchorview
- *
- * Appends the given function to the list of items providers. This list is
- * called, one function at a time, with the given @p data pointer, the
- * anchorview object and, in the @p item parameter, the item name as
- * referenced in its href string. Following functions in the list will be
- * called in order until one of them returns something different to NULL,
- * which should be an Evas_Object which will be used in place of the item
- * element.
+ * Use function to set callbacks to be notified about
+ * change of state of gesture.
+ * When a user registers a callback with this function
+ * this means this gesture has to be tested.
*
- * Items in the markup text take the form \<item relsize=16x16 vsize=full
- * href=item/name\>\</item\>
+ * When ALL callbacks for a gesture are set to NULL
+ * it means user isn't interested in gesture-state
+ * and it will not be tested.
*
- * @param obj The anchorview object
- * @param func The function to add to the list of providers
- * @param data User data that will be passed to the callback function
+ * @param obj Pointer to gesture-layer.
+ * @param idx The gesture you would like to track its state.
+ * @param cb callback function pointer.
+ * @param cb_type what event this callback tracks: START, MOVE, END, ABORT.
+ * @param data user info to be sent to callback (usually, Smart Data)
*
- * @see elm_entry_item_provider_append()
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI void elm_anchorview_item_provider_append(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI void elm_gesture_layer_cb_set(Evas_Object *obj, Elm_Gesture_Types idx, Elm_Gesture_State cb_type, Elm_Gesture_Event_Cb cb, void *data) EINA_ARG_NONNULL(1);
+
/**
- * Prepend a custom item provider to the given anchorview
+ * Call this function to get repeat-events settings.
*
- * Like elm_anchorview_item_provider_append(), but it adds the function
- * @p func to the beginning of the list, instead of the end.
+ * @param obj Pointer to gesture-layer.
*
- * @param obj The anchorview object
- * @param func The function to add to the list of providers
- * @param data User data that will be passed to the callback function
+ * @return repeat events settings.
+ * @see elm_gesture_layer_hold_events_set()
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI void elm_anchorview_item_provider_prepend(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI Eina_Bool elm_gesture_layer_hold_events_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Remove a custom item provider from the list of the given anchorview
+ * This function called in order to make gesture-layer repeat events.
+ * Set this of you like to get the raw events only if gestures were not detected.
+ * Clear this if you like gesture layer to fwd events as testing gestures.
*
- * Removes the function and data pairing that matches @p func and @p data.
- * That is, unless the same function and same user data are given, the
- * function will not be removed from the list. This allows us to add the
- * same callback several times, with different @p data pointers and be
- * able to remove them later without conflicts.
+ * @param obj Pointer to gesture-layer.
+ * @param r Repeat: TRUE/FALSE
*
- * @param obj The anchorview object
- * @param func The function to remove from the list
- * @param data The data matching the function to remove from the list
- */
- EAPI void elm_anchorview_item_provider_remove(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
- /**
- * @}
+ * @ingroup Elm_Gesture_Layer
*/
+ EAPI void elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool r) EINA_ARG_NONNULL(1);
- /* anchorblock */
/**
- * @defgroup Anchorblock Anchorblock
- *
- * @image html img/widget/anchorblock/preview-00.png
- * @image latex img/widget/anchorblock/preview-00.eps
- *
- * Anchorblock is for displaying text that contains markup with anchors
- * like <c>\<a href=1234\>something\</\></c> in it.
- *
- * Besides being styled differently, the anchorblock widget provides the
- * necessary functionality so that clicking on these anchors brings up a
- * popup with user defined content such as "call", "add to contacts" or
- * "open web page". This popup is provided using the @ref Hover widget.
- *
- * This widget emits the following signals:
- * @li "anchor,clicked": will be called when an anchor is clicked. The
- * @p event_info parameter on the callback will be a pointer of type
- * ::Elm_Entry_Anchorblock_Info.
- *
- * @see Anchorview
- * @see Entry
- * @see Hover
+ * This function sets step-value for zoom action.
+ * Set step to any positive value.
+ * Cancel step setting by setting to 0.0
*
- * Since examples are usually better than plain words, we might as well
- * try @ref tutorial_anchorblock_example "one".
- */
- /**
- * @addtogroup Anchorblock
- * @{
- */
- /**
- * @typedef Elm_Entry_Anchorblock_Info
+ * @param obj Pointer to gesture-layer.
+ * @param s new zoom step value.
*
- * The info sent in the callback for "anchor,clicked" signals emitted by
- * the Anchorblock widget.
+ * @ingroup Elm_Gesture_Layer
*/
- typedef struct _Elm_Entry_Anchorblock_Info Elm_Entry_Anchorblock_Info;
+ EAPI void elm_gesture_layer_zoom_step_set(Evas_Object *obj, double s) EINA_ARG_NONNULL(1);
+
/**
- * @struct _Elm_Entry_Anchorblock_Info
+ * This function sets step-value for rotate action.
+ * Set step to any positive value.
+ * Cancel step setting by setting to 0.0
*
- * The info sent in the callback for "anchor,clicked" signals emitted by
- * the Anchorblock widget.
- */
- struct _Elm_Entry_Anchorblock_Info
- {
- const char *name; /**< Name of the anchor, as indicated in its href
- attribute */
- int button; /**< The mouse button used to click on it */
- Evas_Object *hover; /**< The hover object to use for the popup */
- struct {
- Evas_Coord x, y, w, h;
- } anchor, /**< Geometry selection of text used as anchor */
- hover_parent; /**< Geometry of the object used as parent by the
- hover */
- Eina_Bool hover_left : 1; /**< Hint indicating if there's space
- for content on the left side of
- the hover. Before calling the
- callback, the widget will make the
- necessary calculations to check
- which sides are fit to be set with
- content, based on the position the
- hover is activated and its distance
- to the edges of its parent object
- */
- Eina_Bool hover_right : 1; /**< Hint indicating content fits on
- the right side of the hover.
- See @ref hover_left */
- Eina_Bool hover_top : 1; /**< Hint indicating content fits on top
- of the hover. See @ref hover_left */
- Eina_Bool hover_bottom : 1; /**< Hint indicating content fits
- below the hover. See @ref
- hover_left */
- };
- /**
- * Add a new Anchorblock object
+ * @param obj Pointer to gesture-layer.
+ * @param s new roatate step value.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * @ingroup Elm_Gesture_Layer
*/
- EAPI Evas_Object *elm_anchorblock_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI void elm_gesture_layer_rotate_step_set(Evas_Object *obj, double s) EINA_ARG_NONNULL(1);
+
/**
- * Set the text to show in the anchorblock
+ * This function called to attach gesture-layer to an Evas_Object.
+ * @param obj Pointer to gesture-layer.
+ * @param t Pointer to underlying object (AKA Target)
*
- * Sets the text of the anchorblock to @p text. This text can include markup
- * format tags, including <c>\<a href=anchorname\></a></c> to begin a segment
- * of text that will be specially styled and react to click events, ended
- * with either of \</a\> or \</\>. When clicked, the anchor will emit an
- * "anchor,clicked" signal that you can attach a callback to with
- * evas_object_smart_callback_add(). The name of the anchor given in the
- * event info struct will be the one set in the href attribute, in this
- * case, anchorname.
+ * @return TRUE, FALSE on success, failure.
*
- * Other markup can be used to style the text in different ways, but it's
- * up to the style defined in the theme which tags do what.
- * @deprecated use elm_object_text_set() instead.
+ * @ingroup Elm_Gesture_Layer
*/
- EINA_DEPRECATED EAPI void elm_anchorblock_text_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *t) EINA_ARG_NONNULL(1, 2);
+
/**
- * Get the markup text set for the anchorblock
+ * Call this function to construct a new gesture-layer object.
+ * This does not activate the gesture layer. You have to
+ * call elm_gesture_layer_attach in order to 'activate' gesture-layer.
*
- * Retrieves the text set on the anchorblock, with markup tags included.
+ * @param parent the parent object.
*
- * @param obj The anchorblock object
- * @return The markup text set or @c NULL if nothing was set or an error
- * occurred
- * @deprecated use elm_object_text_set() instead.
+ * @return Pointer to new gesture-layer object.
+ *
+ * @ingroup Elm_Gesture_Layer
*/
- EINA_DEPRECATED EAPI const char *elm_anchorblock_text_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
/**
- * Set the parent of the hover popup
+ * @defgroup Thumb Thumb
*
- * Sets the parent object to use by the hover created by the anchorblock
- * when an anchor is clicked. See @ref Hover for more details on this.
+ * @image html img/widget/thumb/preview-00.png
+ * @image latex img/widget/thumb/preview-00.eps
*
- * @param obj The anchorblock object
- * @param parent The object to use as parent for the hover
- */
- EAPI void elm_anchorblock_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
- /**
- * Get the parent of the hover popup
+ * A thumb object is used for displaying the thumbnail of an image or video.
+ * You must have compiled Elementary with Ethumb_Client support and the DBus
+ * service must be present and auto-activated in order to have thumbnails to
+ * be generated.
*
- * Get the object used as parent for the hover created by the anchorblock
- * widget. See @ref Hover for more details on this.
- * If no parent is set, the same anchorblock object will be used.
+ * Once the thumbnail object becomes visible, it will check if there is a
+ * previously generated thumbnail image for the file set on it. If not, it
+ * will start generating this thumbnail.
*
- * @param obj The anchorblock object
- * @return The object used as parent for the hover, NULL if none is set.
- */
- EAPI Evas_Object *elm_anchorblock_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Set the style that the hover should use
+ * Different config settings will cause different thumbnails to be generated
+ * even on the same file.
*
- * When creating the popup hover, anchorblock will request that it's
- * themed according to @p style.
+ * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check the
+ * Ethumb documentation to change this path, and to see other configuration
+ * options.
*
- * @param obj The anchorblock object
- * @param style The style to use for the underlying hover
+ * Signals that you can add callbacks for are:
*
- * @see elm_object_style_set()
- */
- EAPI void elm_anchorblock_hover_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
- /**
- * Get the style that the hover should use
+ * - "clicked" - This is called when a user has clicked the thumb without dragging
+ * around.
+ * - "clicked,double" - This is called when a user has double-clicked the thumb.
+ * - "press" - This is called when a user has pressed down the thumb.
+ * - "generate,start" - The thumbnail generation started.
+ * - "generate,stop" - The generation process stopped.
+ * - "generate,error" - The generation failed.
+ * - "load,error" - The thumbnail image loading failed.
*
- * Get the style the hover created by anchorblock will use.
+ * available styles:
+ * - default
+ * - noframe
*
- * @param obj The anchorblock object
- * @return The style to use by the hover. NULL means the default is used.
+ * An example of use of thumbnail:
*
- * @see elm_object_style_set()
+ * - @ref thumb_example_01
*/
- EAPI const char *elm_anchorblock_hover_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
- * Ends the hover popup in the anchorblock
+ * @addtogroup Thumb
+ * @{
+ */
+
+ /**
+ * @enum _Elm_Thumb_Animation_Setting
+ * @typedef Elm_Thumb_Animation_Setting
*
- * When an anchor is clicked, the anchorblock widget will create a hover
- * object to use as a popup with user provided content. This function
- * terminates this popup, returning the anchorblock to its normal state.
+ * Used to set if a video thumbnail is animating or not.
*
- * @param obj The anchorblock object
+ * @ingroup Thumb
*/
- EAPI void elm_anchorblock_hover_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ typedef enum _Elm_Thumb_Animation_Setting
+ {
+ ELM_THUMB_ANIMATION_START = 0, /**< Play animation once */
+ ELM_THUMB_ANIMATION_LOOP, /**< Keep playing animation until stop is requested */
+ ELM_THUMB_ANIMATION_STOP, /**< Stop playing the animation */
+ ELM_THUMB_ANIMATION_LAST
+ } Elm_Thumb_Animation_Setting;
+
/**
- * Appends a custom item provider to the given anchorblock
- *
- * Appends the given function to the list of items providers. This list is
- * called, one function at a time, with the given @p data pointer, the
- * anchorblock object and, in the @p item parameter, the item name as
- * referenced in its href string. Following functions in the list will be
- * called in order until one of them returns something different to NULL,
- * which should be an Evas_Object which will be used in place of the item
- * element.
+ * Add a new thumb object to the parent.
*
- * Items in the markup text take the form \<item relsize=16x16 vsize=full
- * href=item/name\>\</item\>
+ * @param parent The parent object.
+ * @return The new object or NULL if it cannot be created.
*
- * @param obj The anchorblock object
- * @param func The function to add to the list of providers
- * @param data User data that will be passed to the callback function
+ * @see elm_thumb_file_set()
+ * @see elm_thumb_ethumb_client_get()
*
- * @see elm_entry_item_provider_append()
+ * @ingroup Thumb
*/
- EAPI void elm_anchorblock_item_provider_append(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorblock, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
+ EAPI Evas_Object *elm_thumb_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * Prepend a custom item provider to the given anchorblock
+ * Reload thumbnail if it was generated before.
*
- * Like elm_anchorblock_item_provider_append(), but it adds the function
- * @p func to the beginning of the list, instead of the end.
+ * @param obj The thumb object to reload
*
- * @param obj The anchorblock object
- * @param func The function to add to the list of providers
- * @param data User data that will be passed to the callback function
- */
- EAPI void elm_anchorblock_item_provider_prepend(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorblock, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
- /**
- * Remove a custom item provider from the list of the given anchorblock
+ * This is useful if the ethumb client configuration changed, like its
+ * size, aspect or any other property one set in the handle returned
+ * by elm_thumb_ethumb_client_get().
*
- * Removes the function and data pairing that matches @p func and @p data.
- * That is, unless the same function and same user data are given, the
- * function will not be removed from the list. This allows us to add the
- * same callback several times, with different @p data pointers and be
- * able to remove them later without conflicts.
+ * If the options didn't change, the thumbnail won't be generated again, but
+ * the old one will still be used.
*
- * @param obj The anchorblock object
- * @param func The function to remove from the list
- * @param data The data matching the function to remove from the list
- */
- EAPI void elm_anchorblock_item_provider_remove(Evas_Object *obj, Evas_Object *(*func) (void *data, Evas_Object *anchorblock, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
- /**
- * @}
+ * @see elm_thumb_file_set()
+ *
+ * @ingroup Thumb
*/
-
+ EAPI void elm_thumb_reload(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @defgroup Bubble Bubble
+ * Set the file that will be used as thumbnail.
*
- * @image html img/widget/bubble/preview-00.png
- * @image html img/widget/bubble/preview-01.png
- * @image html img/widget/bubble/preview-02.png
+ * @param obj The thumb object.
+ * @param file The path to file that will be used as thumb.
+ * @param key The key used in case of an EET file.
*
- * @brief The Bubble is a widget to show text similarly to how speech is
- * represented in comics.
+ * The file can be an image or a video (in that case, acceptable extensions are:
+ * avi, mp4, ogv, mov, mpg and wmv). To start the video animation, use the
+ * function elm_thumb_animate().
*
- * The bubble widget contains 5 important visual elements:
- * @li The frame is a rectangle with rounded rectangles and an "arrow".
- * @li The @p icon is an image to which the frame's arrow points to.
- * @li The @p label is a text which appears to the right of the icon if the
- * corner is "top_left" or "bottom_left" and is right aligned to the frame
- * otherwise.
- * @li The @p info is a text which appears to the right of the label. Info's
- * font is of a ligther color than label.
- * @li The @p content is an evas object that is shown inside the frame.
+ * @see elm_thumb_file_get()
+ * @see elm_thumb_reload()
+ * @see elm_thumb_animate()
*
- * The position of the arrow, icon, label and info depends on which corner is
- * selected. The four available corners are:
- * @li "top_left" - Default
- * @li "top_right"
- * @li "bottom_left"
- * @li "bottom_right"
+ * @ingroup Thumb
+ */
+ EAPI void elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
+ /**
+ * Get the image or video path and key used to generate the thumbnail.
*
- * Signals that you can add callbacks for are:
- * @li "clicked" - This is called when a user has clicked the bubble.
+ * @param obj The thumb object.
+ * @param file Pointer to filename.
+ * @param key Pointer to key.
*
- * For an example of using a buble see @ref bubble_01_example_page "this".
+ * @see elm_thumb_file_set()
+ * @see elm_thumb_path_get()
*
- * @{
+ * @ingroup Thumb
*/
+ EAPI void elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
/**
- * Add a new bubble to the parent
+ * Get the path and key to the image or video generated by ethumb.
*
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
+ * One just need to make sure that the thumbnail was generated before getting
+ * its path; otherwise, the path will be NULL. One way to do that is by asking
+ * for the path when/after the "generate,stop" smart callback is called.
*
- * This function adds a text bubble to the given parent evas object.
- */
- EAPI Evas_Object *elm_bubble_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- /**
- * Set the label of the bubble
+ * @param obj The thumb object.
+ * @param file Pointer to thumb path.
+ * @param key Pointer to thumb key.
*
- * @param obj The bubble object
- * @param label The string to set in the label
+ * @see elm_thumb_file_get()
*
- * This function sets the title of the bubble. Where this appears depends on
- * the selected corner.
- * @deprecated use elm_object_text_set() instead.
+ * @ingroup Thumb
*/
- EINA_DEPRECATED EAPI void elm_bubble_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+ EAPI void elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
/**
- * Get the label of the bubble
+ * Set the animation state for the thumb object. If its content is an animated
+ * video, you may start/stop the animation or tell it to play continuously and
+ * looping.
*
- * @param obj The bubble object
- * @return The string of set in the label
+ * @param obj The thumb object.
+ * @param setting The animation setting.
*
- * This function gets the title of the bubble.
- * @deprecated use elm_object_text_set() instead.
+ * @see elm_thumb_file_set()
+ *
+ * @ingroup Thumb
*/
- EINA_DEPRECATED EAPI const char *elm_bubble_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s) EINA_ARG_NONNULL(1);
/**
- * Set the info of the bubble
+ * Get the animation state for the thumb object.
*
- * @param obj The bubble object
- * @param info The given info about the bubble
+ * @param obj The thumb object.
+ * @return getting The animation setting or @c ELM_THUMB_ANIMATION_LAST,
+ * on errors.
*
- * This function sets the info of the bubble. Where this appears depends on
- * the selected corner.
- * @deprecated use elm_object_text_set() instead.
+ * @see elm_thumb_animate_set()
+ *
+ * @ingroup Thumb
*/
- EINA_DEPRECATED EAPI void elm_bubble_info_set(Evas_Object *obj, const char *info) EINA_ARG_NONNULL(1);
+ EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * Get the info of the bubble
+ * Get the ethumb_client handle so custom configuration can be made.
*
- * @param obj The bubble object
+ * @return Ethumb_Client instance or NULL.
*
- * @return The "info" string of the bubble
+ * This must be called before the objects are created to be sure no object is
+ * visible and no generation started.
*
- * This function gets the info text.
- * @deprecated use elm_object_text_set() instead.
- */
- EINA_DEPRECATED EAPI const char *elm_bubble_info_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Set the content to be shown in the bubble
+ * Example of usage:
*
- * Once the content object is set, a previously set one will be deleted.
- * If you want to keep the old content object, use the
- * elm_bubble_content_unset() function.
+ * @code
+ * #include <Elementary.h>
+ * #ifndef ELM_LIB_QUICKLAUNCH
+ * EAPI_MAIN int
+ * elm_main(int argc, char **argv)
+ * {
+ * Ethumb_Client *client;
*
- * @param obj The bubble object
- * @param content The given content of the bubble
+ * elm_need_ethumb();
*
- * This function sets the content shown on the middle of the bubble.
- */
- EAPI void elm_bubble_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
- /**
- * Get the content shown in the bubble
+ * // ... your code
*
- * Return the content object which is set for this widget.
+ * client = elm_thumb_ethumb_client_get();
+ * if (!client)
+ * {
+ * ERR("could not get ethumb_client");
+ * return 1;
+ * }
+ * ethumb_client_size_set(client, 100, 100);
+ * ethumb_client_crop_align_set(client, 0.5, 0.5);
+ * // ... your code
*
- * @param obj The bubble object
- * @return The content that is being used
- */
- EAPI Evas_Object *elm_bubble_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Unset the content shown in the bubble
+ * // Create elm_thumb objects here
*
- * Unparent and return the content object which was set for this widget.
+ * elm_run();
+ * elm_shutdown();
+ * return 0;
+ * }
+ * #endif
+ * ELM_MAIN()
+ * @endcode
*
- * @param obj The bubble object
- * @return The content that was being used
+ * @note There's only one client handle for Ethumb, so once a configuration
+ * change is done to it, any other request for thumbnails (for any thumbnail
+ * object) will use that configuration. Thus, this configuration is global.
+ *
+ * @ingroup Thumb
*/
- EAPI Evas_Object *elm_bubble_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void *elm_thumb_ethumb_client_get(void);
/**
- * Set the icon of the bubble
- *
- * Once the icon object is set, a previously set one will be deleted.
- * If you want to keep the old content object, use the
- * elm_icon_content_unset() function.
+ * Get the ethumb_client connection state.
*
- * @param obj The bubble object
- * @param icon The given icon for the bubble
+ * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
+ * otherwise.
*/
- EAPI void elm_bubble_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_thumb_ethumb_client_connected(void);
/**
- * Get the icon of the bubble
+ * Make the thumbnail 'editable'.
*
- * @param obj The bubble object
- * @return The icon for the bubble
+ * @param obj Thumb object.
+ * @param set Turn on or off editability. Default is @c EINA_FALSE.
*
- * This function gets the icon shown on the top left of bubble.
- */
- EAPI Evas_Object *elm_bubble_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /**
- * Unset the icon of the bubble
+ * This means the thumbnail is a valid drag target for drag and drop, and can be
+ * cut or pasted too.
*
- * Unparent and return the icon object which was set for this widget.
+ * @see elm_thumb_editable_get()
*
- * @param obj The bubble object
- * @return The icon that was being used
+ * @ingroup Thumb
*/
- EAPI Evas_Object *elm_bubble_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit) EINA_ARG_NONNULL(1);
/**
- * Set the corner of the bubble
- *
- * @param obj The bubble object.
- * @param corner The given corner for the bubble.
+ * Make the thumbnail 'editable'.
*
- * This function sets the corner of the bubble. The corner will be used to
- * determine where the arrow in the frame points to and where label, icon and
- * info arre shown.
+ * @param obj Thumb object.
+ * @return Editability.
*
- * Possible values for corner are:
- * @li "top_left" - Default
- * @li "top_right"
- * @li "bottom_left"
- * @li "bottom_right"
- */
- EAPI void elm_bubble_corner_set(Evas_Object *obj, const char *corner) EINA_ARG_NONNULL(1, 2);
- /**
- * Get the corner of the bubble
+ * This means the thumbnail is a valid drag target for drag and drop, and can be
+ * cut or pasted too.
*
- * @param obj The bubble object.
- * @return The given corner for the bubble.
+ * @see elm_thumb_editable_set()
*
- * This function gets the selected corner of the bubble.
+ * @ingroup Thumb
*/
- EAPI const char *elm_bubble_corner_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_thumb_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
* @}
*/
- /* photo */
- EAPI Evas_Object *elm_photo_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_photo_file_set(Evas_Object *obj, const char *file) EINA_ARG_NONNULL(1);
- EAPI void elm_photo_size_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
- EAPI void elm_photo_fill_inside_set(Evas_Object *obj, Eina_Bool fill) EINA_ARG_NONNULL(1);
- EAPI void elm_photo_editable_set(Evas_Object *obj, Eina_Bool set) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "clicked" - the user clicked the icon
- * "drag,start" - Someone started dragging the image out of the object
- * "drag,end" - Dragged item was dropped (somewhere)
- */
-
- /* gesture layer */
/**
- * @defgroup Elm_Gesture_Layer Gesture Layer
- * Gesture Layer Usage:
- *
- * Use Gesture Layer to detect gestures.
- * The advantage is that you don't have to implement
- * gesture detection, just set callbacks of gesture state.
- * By using gesture layer we make standard interface.
- *
- * In order to use Gesture Layer you start with @ref elm_gesture_layer_add
- * with a parent object parameter.
- * Next 'activate' gesture layer with a @ref elm_gesture_layer_attach
- * call. Usually with same object as target (2nd parameter).
- *
- * Now you need to tell gesture layer what gestures you follow.
- * This is done with @ref elm_gesture_layer_cb_set call.
- * By setting the callback you actually saying to gesture layer:
- * I would like to know when the gesture @ref Elm_Gesture_Types
- * switches to state @ref Elm_Gesture_State.
+ * @defgroup Web Web
*
- * Next, you need to implement the actual action that follows the input
- * in your callback.
- *
- * Note that if you like to stop being reported about a gesture, just set
- * all callbacks referring this gesture to NULL.
- * (again with @ref elm_gesture_layer_cb_set)
+ * @image html img/widget/web/preview-00.png
+ * @image latex img/widget/web/preview-00.eps
*
- * The information reported by gesture layer to your callback is depending
- * on @ref Elm_Gesture_Types:
- * @ref Elm_Gesture_Taps_Info is the info reported for tap gestures:
- * @ref ELM_GESTURE_N_TAPS, @ref ELM_GESTURE_N_LONG_TAPS,
- * @ref ELM_GESTURE_N_DOUBLE_TAPS, @ref ELM_GESTURE_N_TRIPLE_TAPS.
+ * A web object is used for displaying web pages (HTML/CSS/JS)
+ * using WebKit-EFL. You must have compiled Elementary with
+ * ewebkit support.
*
- * @ref Elm_Gesture_Momentum_Info is info reported for momentum gestures:
- * @ref ELM_GESTURE_MOMENTUM.
+ * Signals that you can add callbacks for are:
+ * @li "download,request": A file download has been requested. Event info is
+ * a pointer to a Elm_Web_Download
+ * @li "editorclient,contents,changed": Editor client's contents changed
+ * @li "editorclient,selection,changed": Editor client's selection changed
+ * @li "frame,created": A new frame was created. Event info is an
+ * Evas_Object which can be handled with WebKit's ewk_frame API
+ * @li "icon,received": An icon was received by the main frame
+ * @li "inputmethod,changed": Input method changed. Event info is an
+ * Eina_Bool indicating whether it's enabled or not
+ * @li "js,windowobject,clear": JS window object has been cleared
+ * @li "link,hover,in": Mouse cursor is hovering over a link. Event info
+ * is a char *link[2], where the first string contains the URL the link
+ * points to, and the second one the title of the link
+ * @li "link,hover,out": Mouse cursor left the link
+ * @li "load,document,finished": Loading of a document finished. Event info
+ * is the frame that finished loading
+ * @li "load,error": Load failed. Event info is a pointer to
+ * Elm_Web_Frame_Load_Error
+ * @li "load,finished": Load finished. Event info is NULL on success, on
+ * error it's a pointer to Elm_Web_Frame_Load_Error
+ * @li "load,newwindow,show": A new window was created and is ready to be
+ * shown
+ * @li "load,progress": Overall load progress. Event info is a pointer to
+ * a double containing a value between 0.0 and 1.0
+ * @li "load,provisional": Started provisional load
+ * @li "load,started": Loading of a document started
+ * @li "menubar,visible,get": Queries if the menubar is visible. Event info
+ * is a pointer to Eina_Bool where the callback should set EINA_TRUE if
+ * the menubar is visible, or EINA_FALSE in case it's not
+ * @li "menubar,visible,set": Informs menubar visibility. Event info is
+ * an Eina_Bool indicating the visibility
+ * @li "popup,created": A dropdown widget was activated, requesting its
+ * popup menu to be created. Event info is a pointer to Elm_Web_Menu
+ * @li "popup,willdelete": The web object is ready to destroy the popup
+ * object created. Event info is a pointer to Elm_Web_Menu
+ * @li "ready": Page is fully loaded
+ * @li "scrollbars,visible,get": Queries visibility of scrollbars. Event
+ * info is a pointer to Eina_Bool where the visibility state should be set
+ * @li "scrollbars,visible,set": Informs scrollbars visibility. Event info
+ * is an Eina_Bool with the visibility state set
+ * @li "statusbar,text,set": Text of the statusbar changed. Even info is
+ * a string with the new text
+ * @li "statusbar,visible,get": Queries visibility of the status bar.
+ * Event info is a pointer to Eina_Bool where the visibility state should be
+ * set.
+ * @li "statusbar,visible,set": Informs statusbar visibility. Event info is
+ * an Eina_Bool with the visibility value
+ * @li "title,changed": Title of the main frame changed. Event info is a
+ * string with the new title
+ * @li "toolbars,visible,get": Queries visibility of toolbars. Event info
+ * is a pointer to Eina_Bool where the visibility state should be set
+ * @li "toolbars,visible,set": Informs the visibility of toolbars. Event
+ * info is an Eina_Bool with the visibility state
+ * @li "tooltip,text,set": Show and set text of a tooltip. Event info is
+ * a string with the text to show
+ * @li "uri,changed": URI of the main frame changed. Event info is a string
+ * with the new URI
+ * @li "view,resized": The web object internal's view changed sized
+ * @li "windows,close,request": A JavaScript request to close the current
+ * window was requested
+ * @li "zoom,animated,end": Animated zoom finished
*
- * @ref Elm_Gesture_Line_Info is the info reported for line gestures:
- * (this also contains @ref Elm_Gesture_Momentum_Info internal structure)
- * @ref ELM_GESTURE_N_LINES, @ref ELM_GESTURE_N_FLICKS.
- * Note that we consider a flick as a line-gesture that should be completed
- * in flick-time-limit as defined in @ref Config.
+ * available styles:
+ * - default
*
- * @ref Elm_Gesture_Zoom_Info is the info reported for @ref ELM_GESTURE_ZOOM gesture.
+ * An example of use of web:
*
- * @ref Elm_Gesture_Rotate_Info is the info reported for @ref ELM_GESTURE_ROTATE gesture.
- * */
+ * - @ref web_example_01 TBD
+ */
/**
- * @enum _Elm_Gesture_Types
- * Enum of supported gesture types.
- * @ingroup Elm_Gesture_Layer
+ * @addtogroup Web
+ * @{
*/
- enum _Elm_Gesture_Types
- {
- ELM_GESTURE_FIRST = 0,
-
- ELM_GESTURE_N_TAPS, /**< N fingers single taps */
- ELM_GESTURE_N_LONG_TAPS, /**< N fingers single long-taps */
- ELM_GESTURE_N_DOUBLE_TAPS, /**< N fingers double-single taps */
- ELM_GESTURE_N_TRIPLE_TAPS, /**< N fingers triple-single taps */
- ELM_GESTURE_MOMENTUM, /**< Reports momentum in the dircetion of move */
-
- ELM_GESTURE_N_LINES, /**< N fingers line gesture */
- ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
-
- ELM_GESTURE_ZOOM, /**< Zoom */
- ELM_GESTURE_ROTATE, /**< Rotate */
-
- ELM_GESTURE_LAST
+ /**
+ * Structure used to report load errors.
+ *
+ * Load errors are reported as signal by elm_web. All the strings are
+ * temporary references and should @b not be used after the signal
+ * callback returns. If it's required, make copies with strdup() or
+ * eina_stringshare_add() (they are not even guaranteed to be
+ * stringshared, so must use eina_stringshare_add() and not
+ * eina_stringshare_ref()).
+ */
+ typedef struct _Elm_Web_Frame_Load_Error Elm_Web_Frame_Load_Error;
+ /**
+ * Structure used to report load errors.
+ *
+ * Load errors are reported as signal by elm_web. All the strings are
+ * temporary references and should @b not be used after the signal
+ * callback returns. If it's required, make copies with strdup() or
+ * eina_stringshare_add() (they are not even guaranteed to be
+ * stringshared, so must use eina_stringshare_add() and not
+ * eina_stringshare_ref()).
+ */
+ struct _Elm_Web_Frame_Load_Error
+ {
+ int code; /**< Numeric error code */
+ Eina_Bool is_cancellation; /**< Error produced by cancelling a request */
+ const char *domain; /**< Error domain name */
+ const char *description; /**< Error description (already localized) */
+ const char *failing_url; /**< The URL that failed to load */
+ Evas_Object *frame; /**< Frame object that produced the error */
};
/**
- * @typedef Elm_Gesture_Types
- * gesture types enum
- * @ingroup Elm_Gesture_Layer
+ * The possibles types that the items in a menu can be
*/
- typedef enum _Elm_Gesture_Types Elm_Gesture_Types;
-
+ typedef enum _Elm_Web_Menu_Item_Type Elm_Web_Menu_Item_Type;
/**
- * @enum _Elm_Gesture_State
- * Enum of gesture states.
- * @ingroup Elm_Gesture_Layer
+ * The possibles types that the items in a menu can be
*/
- enum _Elm_Gesture_State
+ enum _Elm_Web_Menu_Item_Type
{
- ELM_GESTURE_STATE_UNDEFINED = -1, /**< Gesture not STARTed */
- ELM_GESTURE_STATE_START, /**< Gesture STARTed */
- ELM_GESTURE_STATE_MOVE, /**< Gesture is ongoing */
- ELM_GESTURE_STATE_END, /**< Gesture completed */
- ELM_GESTURE_STATE_ABORT /**< Onging gesture was ABORTed */
+ ELM_WEB_MENU_SEPARATOR,
+ ELM_WEB_MENU_GROUP,
+ ELM_WEB_MENU_OPTION
};
/**
- * @typedef Elm_Gesture_State
- * gesture states enum
- * @ingroup Elm_Gesture_Layer
+ * Structure describing the items in a menu
*/
- typedef enum _Elm_Gesture_State Elm_Gesture_State;
-
+ typedef struct _Elm_Web_Menu_Item Elm_Web_Menu_Item;
/**
- * @struct _Elm_Gesture_Taps_Info
- * Struct holds taps info for user
- * @ingroup Elm_Gesture_Layer
+ * Structure describing the items in a menu
*/
- struct _Elm_Gesture_Taps_Info
+ struct _Elm_Web_Menu_Item
{
- Evas_Coord x, y; /**< Holds center point between fingers */
- unsigned int n; /**< Number of fingers tapped */
- unsigned int timestamp; /**< event timestamp */
+ const char *text; /**< The text for the item */
+ Elm_Web_Menu_Item_Type type; /**< The type of the item */
};
/**
- * @typedef Elm_Gesture_Taps_Info
- * holds taps info for user
- * @ingroup Elm_Gesture_Layer
+ * Structure describing the menu of a popup
+ *
+ * This structure will be passed as the @c event_info for the "popup,create"
+ * signal, which is emitted when a dropdown menu is opened. Users wanting
+ * to handle these popups by themselves should listen to this signal and
+ * set the @c handled property of the struct to @c EINA_TRUE. Leaving this
+ * property as @c EINA_FALSE means that the user will not handle the popup
+ * and the default implementation will be used.
+ *
+ * When the popup is ready to be dismissed, a "popup,willdelete" signal
+ * will be emitted to notify the user that it can destroy any objects and
+ * free all data related to it.
+ *
+ * @see elm_web_popup_selected_set()
+ * @see elm_web_popup_destroy()
*/
- typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
-
+ typedef struct _Elm_Web_Menu Elm_Web_Menu;
/**
- * @struct _Elm_Gesture_Momentum_Info
- * Struct holds momentum info for user
- * x1 and y1 are not necessarily in sync
- * x1 holds x value of x direction starting point
- * and same holds for y1.
- * This is noticeable when doing V-shape movement
- * @ingroup Elm_Gesture_Layer
+ * Structure describing the menu of a popup
+ *
+ * This structure will be passed as the @c event_info for the "popup,create"
+ * signal, which is emitted when a dropdown menu is opened. Users wanting
+ * to handle these popups by themselves should listen to this signal and
+ * set the @c handled property of the struct to @c EINA_TRUE. Leaving this
+ * property as @c EINA_FALSE means that the user will not handle the popup
+ * and the default implementation will be used.
+ *
+ * When the popup is ready to be dismissed, a "popup,willdelete" signal
+ * will be emitted to notify the user that it can destroy any objects and
+ * free all data related to it.
+ *
+ * @see elm_web_popup_selected_set()
+ * @see elm_web_popup_destroy()
*/
- struct _Elm_Gesture_Momentum_Info
- { /* Report line ends, timestamps, and momentum computed */
- Evas_Coord x1; /**< Final-swipe direction starting point on X */
- Evas_Coord y1; /**< Final-swipe direction starting point on Y */
- Evas_Coord x2; /**< Final-swipe direction ending point on X */
- Evas_Coord y2; /**< Final-swipe direction ending point on Y */
+ struct _Elm_Web_Menu
+ {
+ Eina_List *items; /**< List of #Elm_Web_Menu_Item */
+ int x; /**< The X position of the popup, relative to the elm_web object */
+ int y; /**< The Y position of the popup, relative to the elm_web object */
+ int width; /**< Width of the popup menu */
+ int height; /**< Height of the popup menu */
- unsigned int tx; /**< Timestamp of start of final x-swipe */
- unsigned int ty; /**< Timestamp of start of final y-swipe */
+ Eina_Bool handled : 1; /**< Set to @c EINA_TRUE by the user to indicate that the popup has been handled and the default implementation should be ignored. Leave as @c EINA_FALSE otherwise. */
+ };
- Evas_Coord mx; /**< Momentum on X */
- Evas_Coord my; /**< Momentum on Y */
+ typedef struct _Elm_Web_Download Elm_Web_Download;
+ struct _Elm_Web_Download
+ {
+ const char *url;
};
/**
- * @typedef Elm_Gesture_Momentum_Info
- * holds momentum info for user
- * @ingroup Elm_Gesture_Layer
+ * Opaque handler containing the features (such as statusbar, menubar, etc)
+ * that are to be set on a newly requested window.
*/
- typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
-
+ typedef struct _Elm_Web_Window_Features Elm_Web_Window_Features;
/**
- * @struct _Elm_Gesture_Line_Info
- * Struct holds line info for user
- * @ingroup Elm_Gesture_Layer
+ * Callback type for the create_window hook.
+ *
+ * The function parameters are:
+ * @li @p data User data pointer set when setting the hook function
+ * @li @p obj The elm_web object requesting the new window
+ * @li @p js Set to @c EINA_TRUE if the request was originated from
+ * JavaScript. @c EINA_FALSE otherwise.
+ * @li @p window_features A pointer of #Elm_Web_Window_Features indicating
+ * the features requested for the new window.
+ *
+ * The returned value of the function should be the @c elm_web widget where
+ * the request will be loaded. That is, if a new window or tab is created,
+ * the elm_web widget in it should be returned, and @b NOT the window
+ * object.
+ * Returning @c NULL should cancel the request.
+ *
+ * @see elm_web_window_create_hook_set()
+ */
+ typedef Evas_Object *(*Elm_Web_Window_Open)(void *data, Evas_Object *obj, Eina_Bool js, const Elm_Web_Window_Features *window_features);
+ /**
+ * Callback type for the JS alert hook.
+ *
+ * The function parameters are:
+ * @li @p data User data pointer set when setting the hook function
+ * @li @p obj The elm_web object requesting the new window
+ * @li @p message The message to show in the alert dialog
+ *
+ * The function should return the object representing the alert dialog.
+ * Elm_Web will run a second main loop to handle the dialog and normal
+ * flow of the application will be restored when the object is deleted, so
+ * the user should handle the popup properly in order to delete the object
+ * when the action is finished.
+ * If the function returns @c NULL the popup will be ignored.
+ *
+ * @see elm_web_dialog_alert_hook_set()
*/
- struct _Elm_Gesture_Line_Info
- { /* Report line ends, timestamps, and momentum computed */
- Elm_Gesture_Momentum_Info momentum; /**< Line momentum info */
- unsigned int n; /**< Number of fingers (lines) */
- /* FIXME should be radians, bot degrees */
- double angle; /**< Angle (direction) of lines */
- };
-
+ typedef Evas_Object *(*Elm_Web_Dialog_Alert)(void *data, Evas_Object *obj, const char *message);
/**
- * @typedef Elm_Gesture_Line_Info
- * Holds line info for user
- * @ingroup Elm_Gesture_Layer
+ * Callback type for the JS confirm hook.
+ *
+ * The function parameters are:
+ * @li @p data User data pointer set when setting the hook function
+ * @li @p obj The elm_web object requesting the new window
+ * @li @p message The message to show in the confirm dialog
+ * @li @p ret Pointer where to store the user selection. @c EINA_TRUE if
+ * the user selected @c Ok, @c EINA_FALSE otherwise.
+ *
+ * The function should return the object representing the confirm dialog.
+ * Elm_Web will run a second main loop to handle the dialog and normal
+ * flow of the application will be restored when the object is deleted, so
+ * the user should handle the popup properly in order to delete the object
+ * when the action is finished.
+ * If the function returns @c NULL the popup will be ignored.
+ *
+ * @see elm_web_dialog_confirm_hook_set()
*/
- typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
-
+ typedef Evas_Object *(*Elm_Web_Dialog_Confirm)(void *data, Evas_Object *obj, const char *message, Eina_Bool *ret);
/**
- * @struct _Elm_Gesture_Zoom_Info
- * Struct holds zoom info for user
- * @ingroup Elm_Gesture_Layer
+ * Callback type for the JS prompt hook.
+ *
+ * The function parameters are:
+ * @li @p data User data pointer set when setting the hook function
+ * @li @p obj The elm_web object requesting the new window
+ * @li @p message The message to show in the prompt dialog
+ * @li @p def_value The default value to present the user in the entry
+ * @li @p value Pointer where to store the value given by the user. Must
+ * be a malloc'ed string or @c NULL if the user cancelled the popup.
+ * @li @p ret Pointer where to store the user selection. @c EINA_TRUE if
+ * the user selected @c Ok, @c EINA_FALSE otherwise.
+ *
+ * The function should return the object representing the prompt dialog.
+ * Elm_Web will run a second main loop to handle the dialog and normal
+ * flow of the application will be restored when the object is deleted, so
+ * the user should handle the popup properly in order to delete the object
+ * when the action is finished.
+ * If the function returns @c NULL the popup will be ignored.
+ *
+ * @see elm_web_dialog_prompt_hook_set()
+ */
+ typedef Evas_Object *(*Elm_Web_Dialog_Prompt)(void *data, Evas_Object *obj, const char *message, const char *def_value, char **value, Eina_Bool *ret);
+ /**
+ * Callback type for the JS file selector hook.
+ *
+ * The function parameters are:
+ * @li @p data User data pointer set when setting the hook function
+ * @li @p obj The elm_web object requesting the new window
+ * @li @p allows_multiple @c EINA_TRUE if multiple files can be selected.
+ * @li @p accept_types Mime types accepted
+ * @li @p selected Pointer where to store the list of malloc'ed strings
+ * containing the path to each file selected. Must be @c NULL if the file
+ * dialog is cancelled
+ * @li @p ret Pointer where to store the user selection. @c EINA_TRUE if
+ * the user selected @c Ok, @c EINA_FALSE otherwise.
+ *
+ * The function should return the object representing the file selector
+ * dialog.
+ * Elm_Web will run a second main loop to handle the dialog and normal
+ * flow of the application will be restored when the object is deleted, so
+ * the user should handle the popup properly in order to delete the object
+ * when the action is finished.
+ * If the function returns @c NULL the popup will be ignored.
+ *
+ * @see elm_web_dialog_file selector_hook_set()
*/
- struct _Elm_Gesture_Zoom_Info
- {
- Evas_Coord x, y; /**< Holds zoom center point reported to user */
- Evas_Coord radius; /**< Holds radius between fingers reported to user */
- double zoom; /**< Zoom value: 1.0 means no zoom */
- double momentum; /**< Zoom momentum: zoom growth per second (NOT YET SUPPORTED) */
- };
-
+ typedef Evas_Object *(*Elm_Web_Dialog_File_Selector)(void *data, Evas_Object *obj, Eina_Bool allows_multiple, const char *accept_types, Eina_List **selected, Eina_Bool *ret);
/**
- * @typedef Elm_Gesture_Zoom_Info
- * Holds zoom info for user
- * @ingroup Elm_Gesture_Layer
+ * Callback type for the JS console message hook.
+ *
+ * When a console message is added from JavaScript, any set function to the
+ * console message hook will be called for the user to handle. There is no
+ * default implementation of this hook.
+ *
+ * The function parameters are:
+ * @li @p data User data pointer set when setting the hook function
+ * @li @p obj The elm_web object that originated the message
+ * @li @p message The message sent
+ * @li @p line_number The line number
+ * @li @p source_id Source id
+ *
+ * @see elm_web_console_message_hook_set()
*/
- typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
-
+ typedef void (*Elm_Web_Console_Message)(void *data, Evas_Object *obj, const char *message, unsigned int line_number, const char *source_id);
/**
- * @struct _Elm_Gesture_Rotate_Info
- * Struct holds rotation info for user
- * @ingroup Elm_Gesture_Layer
+ * Add a new web object to the parent.
+ *
+ * @param parent The parent object.
+ * @return The new object or NULL if it cannot be created.
+ *
+ * @see elm_web_uri_set()
+ * @see elm_web_webkit_view_get()
*/
- struct _Elm_Gesture_Rotate_Info
- {
- Evas_Coord x, y; /**< Holds zoom center point reported to user */
- Evas_Coord radius; /**< Holds radius between fingers reported to user */
- double base_angle; /**< Holds start-angle */
- double angle; /**< Rotation value: 0.0 means no rotation */
- double momentum; /**< Rotation momentum: rotation done per second (NOT YET SUPPORTED) */
- };
+ EAPI Evas_Object *elm_web_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
- * @typedef Elm_Gesture_Rotate_Info
- * Holds rotation info for user
- * @ingroup Elm_Gesture_Layer
+ * Get internal ewk_view object from web object.
+ *
+ * Elementary may not provide some low level features of EWebKit,
+ * instead of cluttering the API with proxy methods we opted to
+ * return the internal reference. Be careful using it as it may
+ * interfere with elm_web behavior.
+ *
+ * @param obj The web object.
+ * @return The internal ewk_view object or NULL if it does not
+ * exist. (Failure to create or Elementary compiled without
+ * ewebkit)
+ *
+ * @see elm_web_add()
*/
- typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
+ EAPI Evas_Object *elm_web_webkit_view_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
- * @typedef Elm_Gesture_Event_Cb
- * User callback used to stream gesture info from gesture layer
- * @param data user data
- * @param event_info gesture report info
- * Returns a flag field to be applied on the causing event.
- * You should probably return EVAS_EVENT_FLAG_ON_HOLD if your widget acted
- * upon the event, in an irreversible way.
+ * Sets the function to call when a new window is requested
*
- * @ingroup Elm_Gesture_Layer
+ * This hook will be called when a request to create a new window is
+ * issued from the web page loaded.
+ * There is no default implementation for this feature, so leaving this
+ * unset or passing @c NULL in @p func will prevent new windows from
+ * opening.
+ *
+ * @param obj The web object where to set the hook function
+ * @param func The hook function to be called when a window is requested
+ * @param data User data
*/
- typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb) (void *data, void *event_info);
-
+ EAPI void elm_web_window_create_hook_set(Evas_Object *obj, Elm_Web_Window_Open func, void *data);
/**
- * Use function to set callbacks to be notified about
- * change of state of gesture.
- * When a user registers a callback with this function
- * this means this gesture has to be tested.
+ * Sets the function to call when an alert dialog
*
- * When ALL callbacks for a gesture are set to NULL
- * it means user isn't interested in gesture-state
- * and it will not be tested.
+ * This hook will be called when a JavaScript alert dialog is requested.
+ * If no function is set or @c NULL is passed in @p func, the default
+ * implementation will take place.
*
- * @param obj Pointer to gesture-layer.
- * @param idx The gesture you would like to track its state.
- * @param cb callback function pointer.
- * @param cb_type what event this callback tracks: START, MOVE, END, ABORT.
- * @param data user info to be sent to callback (usually, Smart Data)
+ * @param obj The web object where to set the hook function
+ * @param func The callback function to be used
+ * @param data User data
*
- * @ingroup Elm_Gesture_Layer
+ * @see elm_web_inwin_mode_set()
*/
- EAPI void elm_gesture_layer_cb_set(Evas_Object *obj, Elm_Gesture_Types idx, Elm_Gesture_State cb_type, Elm_Gesture_Event_Cb cb, void *data) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_web_dialog_alert_hook_set(Evas_Object *obj, Elm_Web_Dialog_Alert func, void *data);
/**
- * Call this function to get repeat-events settings.
+ * Sets the function to call when an confirm dialog
*
- * @param obj Pointer to gesture-layer.
+ * This hook will be called when a JavaScript confirm dialog is requested.
+ * If no function is set or @c NULL is passed in @p func, the default
+ * implementation will take place.
*
- * @return repeat events settings.
- * @see elm_gesture_layer_hold_events_set()
- * @ingroup Elm_Gesture_Layer
+ * @param obj The web object where to set the hook function
+ * @param func The callback function to be used
+ * @param data User data
+ *
+ * @see elm_web_inwin_mode_set()
*/
- EAPI Eina_Bool elm_gesture_layer_hold_events_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_web_dialog_confirm_hook_set(Evas_Object *obj, Elm_Web_Dialog_Confirm func, void *data);
/**
- * This function called in order to make gesture-layer repeat events.
- * Set this of you like to get the raw events only if gestures were not detected.
- * Clear this if you like gesture layer to fwd events as testing gestures.
+ * Sets the function to call when an prompt dialog
*
- * @param obj Pointer to gesture-layer.
- * @param r Repeat: TRUE/FALSE
+ * This hook will be called when a JavaScript prompt dialog is requested.
+ * If no function is set or @c NULL is passed in @p func, the default
+ * implementation will take place.
*
- * @ingroup Elm_Gesture_Layer
+ * @param obj The web object where to set the hook function
+ * @param func The callback function to be used
+ * @param data User data
+ *
+ * @see elm_web_inwin_mode_set()
*/
- EAPI void elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool r) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_web_dialog_prompt_hook_set(Evas_Object *obj, Elm_Web_Dialog_Prompt func, void *data);
/**
- * This function sets step-value for zoom action.
- * Set step to any positive value.
- * Cancel step setting by setting to 0.0
+ * Sets the function to call when an file selector dialog
*
- * @param obj Pointer to gesture-layer.
- * @param s new zoom step value.
+ * This hook will be called when a JavaScript file selector dialog is
+ * requested.
+ * If no function is set or @c NULL is passed in @p func, the default
+ * implementation will take place.
*
- * @ingroup Elm_Gesture_Layer
+ * @param obj The web object where to set the hook function
+ * @param func The callback function to be used
+ * @param data User data
+ *
+ * @see elm_web_inwin_mode_set()
*/
- EAPI void elm_gesture_layer_zoom_step_set(Evas_Object *obj, double s) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_web_dialog_file_selector_hook_set(Evas_Object *obj, Elm_Web_Dialog_File_Selector func, void *data);
/**
- * This function sets step-value for rotate action.
- * Set step to any positive value.
- * Cancel step setting by setting to 0.0
+ * Sets the function to call when a console message is emitted from JS
*
- * @param obj Pointer to gesture-layer.
- * @param s new roatate step value.
+ * This hook will be called when a console message is emitted from
+ * JavaScript. There is no default implementation for this feature.
*
- * @ingroup Elm_Gesture_Layer
+ * @param obj The web object where to set the hook function
+ * @param func The callback function to be used
+ * @param data User data
*/
- EAPI void elm_gesture_layer_rotate_step_set(Evas_Object *obj, double s) EINA_ARG_NONNULL(1);
-
+ EAPI void elm_web_console_message_hook_set(Evas_Object *obj, Elm_Web_Console_Message func, void *data);
/**
- * This function called to attach gesture-layer to an Evas_Object.
- * @param obj Pointer to gesture-layer.
- * @param t Pointer to underlying object (AKA Target)
+ * Gets the status of the tab propagation
*
- * @return TRUE, FALSE on success, failure.
+ * @param obj The web object to query
+ * @return EINA_TRUE if tab propagation is enabled, EINA_FALSE otherwise
*
- * @ingroup Elm_Gesture_Layer
+ * @see elm_web_tab_propagate_set()
*/
- EAPI Eina_Bool elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *t) EINA_ARG_NONNULL(1, 2);
-
+ EAPI Eina_Bool elm_web_tab_propagate_get(const Evas_Object *obj);
/**
- * Call this function to construct a new gesture-layer object.
- * This does not activate the gesture layer. You have to
- * call elm_gesture_layer_attach in order to 'activate' gesture-layer.
+ * Sets whether to use tab propagation
*
- * @param parent the parent object.
+ * If tab propagation is enabled, whenever the user presses the Tab key,
+ * Elementary will handle it and switch focus to the next widget.
+ * The default value is disabled, where WebKit will handle the Tab key to
+ * cycle focus though its internal objects, jumping to the next widget
+ * only when that cycle ends.
*
- * @return Pointer to new gesture-layer object.
+ * @param obj The web object
+ * @param propagate Whether to propagate Tab keys to Elementary or not
+ */
+ EAPI void elm_web_tab_propagate_set(Evas_Object *obj, Eina_Bool propagate);
+ /**
+ * Sets the URI for the web object
*
- * @ingroup Elm_Gesture_Layer
+ * It must be a full URI, with resource included, in the form
+ * http://www.enlightenment.org or file:///tmp/something.html
+ *
+ * @param obj The web object
+ * @param uri The URI to set
+ * @return EINA_TRUE if the URI could be, EINA_FALSE if an error occurred
*/
- EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
-
+ EAPI Eina_Bool elm_web_uri_set(Evas_Object *obj, const char *uri);
/**
- * @defgroup Thumb Thumb
+ * Gets the current URI for the object
*
- * @image html img/widget/thumb/preview-00.png
- * @image latex img/widget/thumb/preview-00.eps
+ * The returned string must not be freed and is guaranteed to be
+ * stringshared.
*
- * A thumb object is used for displaying the thumbnail of an image or video.
- * You must have compiled Elementary with Ethumb_Client support and the DBus
- * service must be present and auto-activated in order to have thumbnails to
- * be generated.
+ * @param obj The web object
+ * @return A stringshared internal string with the current URI, or NULL on
+ * failure
+ */
+ EAPI const char *elm_web_uri_get(const Evas_Object *obj);
+ /**
+ * Gets the current title
*
- * Once the thumbnail object becomes visible, it will check if there is a
- * previously generated thumbnail image for the file set on it. If not, it
- * will start generating this thumbnail.
+ * The returned string must not be freed and is guaranteed to be
+ * stringshared.
*
- * Different config settings will cause different thumbnails to be generated
- * even on the same file.
+ * @param obj The web object
+ * @return A stringshared internal string with the current title, or NULL on
+ * failure
+ */
+ EAPI const char *elm_web_title_get(const Evas_Object *obj);
+ /**
+ * Sets the background color to be used by the web object
*
- * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check the
- * Ethumb documentation to change this path, and to see other configuration
- * options.
+ * This is the color that will be used by default when the loaded page
+ * does not set it's own. Color values are pre-multiplied.
*
- * Signals that you can add callbacks for are:
+ * @param obj The web object
+ * @param r Red component
+ * @param g Green component
+ * @param b Blue component
+ * @param a Alpha component
+ */
+ EAPI void elm_web_bg_color_set(Evas_Object *obj, int r, int g, int b, int a);
+ /**
+ * Gets the background color to be used by the web object
*
- * - "clicked" - This is called when a user has clicked the thumb without dragging
- * around.
- * - "clicked,double" - This is called when a user has double-clicked the thumb.
- * - "press" - This is called when a user has pressed down the thumb.
- * - "generate,start" - The thumbnail generation started.
- * - "generate,stop" - The generation process stopped.
- * - "generate,error" - The generation failed.
- * - "load,error" - The thumbnail image loading failed.
+ * This is the color that will be used by default when the loaded page
+ * does not set it's own. Color values are pre-multiplied.
*
- * available styles:
- * - default
- * - noframe
+ * @param obj The web object
+ * @param r Red component
+ * @param g Green component
+ * @param b Blue component
+ * @param a Alpha component
+ */
+ EAPI void elm_web_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a);
+ /**
+ * Gets a copy of the currently selected text
*
- * An example of use of thumbnail:
+ * The string returned must be freed by the user when it's done with it.
*
- * - @ref thumb_example_01
+ * @param obj The web object
+ * @return A newly allocated string, or NULL if nothing is selected or an
+ * error occurred
*/
-
+ EAPI char *elm_view_selection_get(const Evas_Object *obj);
/**
- * @addtogroup Thumb
- * @{
+ * Tells the web object which index in the currently open popup was selected
+ *
+ * When the user handles the popup creation from the "popup,created" signal,
+ * it needs to tell the web object which item was selected by calling this
+ * function with the index corresponding to the item.
+ *
+ * @param obj The web object
+ * @param index The index selected
+ *
+ * @see elm_web_popup_destroy()
*/
-
+ EAPI void elm_web_popup_selected_set(Evas_Object *obj, int index);
/**
- * @enum _Elm_Thumb_Animation_Setting
- * @typedef Elm_Thumb_Animation_Setting
+ * Dismisses an open dropdown popup
*
- * Used to set if a video thumbnail is animating or not.
+ * When the popup from a dropdown widget is to be dismissed, either after
+ * selecting an option or to cancel it, this function must be called, which
+ * will later emit an "popup,willdelete" signal to notify the user that
+ * any memory and objects related to this popup can be freed.
*
- * @ingroup Thumb
+ * @param obj The web object
+ * @return EINA_TRUE if the menu was successfully destroyed, or EINA_FALSE
+ * if there was no menu to destroy
*/
- typedef enum _Elm_Thumb_Animation_Setting
- {
- ELM_THUMB_ANIMATION_START = 0, /**< Play animation once */
- ELM_THUMB_ANIMATION_LOOP, /**< Keep playing animation until stop is requested */
- ELM_THUMB_ANIMATION_STOP, /**< Stop playing the animation */
- ELM_THUMB_ANIMATION_LAST
- } Elm_Thumb_Animation_Setting;
-
+ EAPI Eina_Bool elm_web_popup_destroy(Evas_Object *obj);
/**
- * Add a new thumb object to the parent.
+ * Searches the given string in a document.
*
- * @param parent The parent object.
- * @return The new object or NULL if it cannot be created.
+ * @param obj The web object where to search the text
+ * @param string String to search
+ * @param case_sensitive If search should be case sensitive or not
+ * @param forward If search is from cursor and on or backwards
+ * @param wrap If search should wrap at the end
*
- * @see elm_thumb_file_set()
- * @see elm_thumb_ethumb_client_get()
+ * @return @c EINA_TRUE if the given string was found, @c EINA_FALSE if not
+ * or failure
+ */
+ EAPI Eina_Bool elm_web_text_search(const Evas_Object *obj, const char *string, Eina_Bool case_sensitive, Eina_Bool forward, Eina_Bool wrap);
+ /**
+ * Marks matches of the given string in a document.
*
- * @ingroup Thumb
+ * @param obj The web object where to search text
+ * @param string String to match
+ * @param case_sensitive If match should be case sensitive or not
+ * @param highlight If matches should be highlighted
+ * @param limit Maximum amount of matches, or zero to unlimited
+ *
+ * @return number of matched @a string
*/
- EAPI Evas_Object *elm_thumb_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ EAPI unsigned int elm_web_text_matches_mark(Evas_Object *obj, const char *string, Eina_Bool case_sensitive, Eina_Bool highlight, unsigned int limit);
/**
- * Reload thumbnail if it was generated before.
+ * Clears all marked matches in the document
*
- * @param obj The thumb object to reload
+ * @param obj The web object
*
- * This is useful if the ethumb client configuration changed, like its
- * size, aspect or any other property one set in the handle returned
- * by elm_thumb_ethumb_client_get().
+ * @return EINA_TRUE on success, EINA_FALSE otherwise
+ */
+ EAPI Eina_Bool elm_web_text_matches_unmark_all(Evas_Object *obj);
+ /**
+ * Sets whether to highlight the matched marks
*
- * If the options didn't change, the thumbnail won't be generated again, but
- * the old one will still be used.
+ * If enabled, marks set with elm_web_text_matches_mark() will be
+ * highlighted.
*
- * @see elm_thumb_file_set()
+ * @param obj The web object
+ * @param highlight Whether to highlight the marks or not
*
- * @ingroup Thumb
+ * @return EINA_TRUE on success, EINA_FALSE otherwise
*/
- EAPI void elm_thumb_reload(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_web_text_matches_highlight_set(Evas_Object *obj, Eina_Bool highlight);
/**
- * Set the file that will be used as thumbnail.
+ * Gets whether highlighting marks is enabled
*
- * @param obj The thumb object.
- * @param file The path to file that will be used as thumb.
- * @param key The key used in case of an EET file.
+ * @param The web object
*
- * The file can be an image or a video (in that case, acceptable extensions are:
- * avi, mp4, ogv, mov, mpg and wmv). To start the video animation, use the
- * function elm_thumb_animate().
+ * @return EINA_TRUE is marks are set to be highlighted, EINA_FALSE
+ * otherwise
+ */
+ EAPI Eina_Bool elm_web_text_matches_highlight_get(const Evas_Object *obj);
+ /**
+ * Gets the overall loading progress of the page
*
- * @see elm_thumb_file_get()
- * @see elm_thumb_reload()
- * @see elm_thumb_animate()
+ * Returns the estimated loading progress of the page, with a value between
+ * 0.0 and 1.0. This is an estimated progress accounting for all the frames
+ * included in the page.
*
- * @ingroup Thumb
+ * @param The web object
+ *
+ * @return A value between 0.0 and 1.0 indicating the progress, or -1.0 on
+ * failure
*/
- EAPI void elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
+ EAPI double elm_web_load_progress_get(const Evas_Object *obj);
/**
- * Get the image or video path and key used to generate the thumbnail.
+ * Stops loading the current page
*
- * @param obj The thumb object.
- * @param file Pointer to filename.
- * @param key Pointer to key.
+ * Cancels the loading of the current page in the web object. This will
+ * cause a "load,error" signal to be emitted, with the is_cancellation
+ * flag set to EINA_TRUE.
*
- * @see elm_thumb_file_set()
- * @see elm_thumb_path_get()
+ * @param obj The web object
*
- * @ingroup Thumb
+ * @return EINA_TRUE if the cancel was successful, EINA_FALSE otherwise
*/
- EAPI void elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_web_stop(Evas_Object *obj);
/**
- * Get the path and key to the image or video generated by ethumb.
+ * Requests a reload of the current document in the object
*
- * One just need to make sure that the thumbnail was generated before getting
- * its path; otherwise, the path will be NULL. One way to do that is by asking
- * for the path when/after the "generate,stop" smart callback is called.
+ * @param obj The web object
*
- * @param obj The thumb object.
- * @param file Pointer to thumb path.
- * @param key Pointer to thumb key.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise
+ */
+ EAPI Eina_Bool elm_web_reload(Evas_Object *obj);
+ /**
+ * Requests a reload of the current document, avoiding any existing caches
*
- * @see elm_thumb_file_get()
+ * @param obj The web object
*
- * @ingroup Thumb
+ * @return EINA_TRUE on success, EINA_FALSE otherwise
*/
- EAPI void elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_web_reload_full(Evas_Object *obj);
/**
- * Set the animation state for the thumb object. If its content is an animated
- * video, you may start/stop the animation or tell it to play continuously and
- * looping.
+ * Goes back one step in the browsing history
*
- * @param obj The thumb object.
- * @param setting The animation setting.
+ * This is equivalent to calling elm_web_object_navigate(obj, -1);
*
- * @see elm_thumb_file_set()
+ * @param obj The web object
*
- * @ingroup Thumb
+ * @return EINA_TRUE on success, EINA_FALSE otherwise
+ *
+ * @see elm_web_history_enable_set()
+ * @see elm_web_back_possible()
+ * @see elm_web_forward()
+ * @see elm_web_navigate()
*/
- EAPI void elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_web_back(Evas_Object *obj);
/**
- * Get the animation state for the thumb object.
+ * Goes forward one step in the browsing history
*
- * @param obj The thumb object.
- * @return getting The animation setting or @c ELM_THUMB_ANIMATION_LAST,
- * on errors.
+ * This is equivalent to calling elm_web_object_navigate(obj, 1);
*
- * @see elm_thumb_animate_set()
+ * @param obj The web object
*
- * @ingroup Thumb
+ * @return EINA_TRUE on success, EINA_FALSE otherwise
+ *
+ * @see elm_web_history_enable_set()
+ * @see elm_web_forward_possible()
+ * @see elm_web_back()
+ * @see elm_web_navigate()
*/
- EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_web_forward(Evas_Object *obj);
/**
- * Get the ethumb_client handle so custom configuration can be made.
+ * Jumps the given number of steps in the browsing history
*
- * @return Ethumb_Client instance or NULL.
+ * The @p steps value can be a negative integer to back in history, or a
+ * positive to move forward.
+ *
+ * @param obj The web object
+ * @param steps The number of steps to jump
+ *
+ * @return EINA_TRUE on success, EINA_FALSE on error or if not enough
+ * history exists to jump the given number of steps
*
- * This must be called before the objects are created to be sure no object is
- * visible and no generation started.
+ * @see elm_web_history_enable_set()
+ * @see elm_web_navigate_possible()
+ * @see elm_web_back()
+ * @see elm_web_forward()
+ */
+ EAPI Eina_Bool elm_web_navigate(Evas_Object *obj, int steps);
+ /**
+ * Queries whether it's possible to go back in history
*
- * Example of usage:
+ * @param obj The web object
*
- * @code
- * #include <Elementary.h>
- * #ifndef ELM_LIB_QUICKLAUNCH
- * EAPI int
- * elm_main(int argc, char **argv)
- * {
- * Ethumb_Client *client;
+ * @return EINA_TRUE if it's possible to back in history, EINA_FALSE
+ * otherwise
+ */
+ EAPI Eina_Bool elm_web_back_possible(Evas_Object *obj);
+ /**
+ * Queries whether it's possible to go forward in history
*
- * elm_need_ethumb();
+ * @param obj The web object
*
- * // ... your code
+ * @return EINA_TRUE if it's possible to forward in history, EINA_FALSE
+ * otherwise
+ */
+ EAPI Eina_Bool elm_web_forward_possible(Evas_Object *obj);
+ /**
+ * Queries whether it's possible to jump the given number of steps
*
- * client = elm_thumb_ethumb_client_get();
- * if (!client)
- * {
- * ERR("could not get ethumb_client");
- * return 1;
- * }
- * ethumb_client_size_set(client, 100, 100);
- * ethumb_client_crop_align_set(client, 0.5, 0.5);
- * // ... your code
+ * The @p steps value can be a negative integer to back in history, or a
+ * positive to move forward.
*
- * // Create elm_thumb objects here
+ * @param obj The web object
+ * @param steps The number of steps to check for
*
- * elm_run();
- * elm_shutdown();
- * return 0;
- * }
- * #endif
- * ELM_MAIN()
- * @endcode
+ * @return EINA_TRUE if enough history exists to perform the given jump,
+ * EINA_FALSE otherwise
+ */
+ EAPI Eina_Bool elm_web_navigate_possible(Evas_Object *obj, int steps);
+ /**
+ * Gets whether browsing history is enabled for the given object
*
- * @note There's only one client handle for Ethumb, so once a configuration
- * change is done to it, any other request for thumbnails (for any thumbnail
- * object) will use that configuration. Thus, this configuration is global.
+ * @param obj The web object
*
- * @ingroup Thumb
+ * @return EINA_TRUE if history is enabled, EINA_FALSE otherwise
*/
- EAPI void *elm_thumb_ethumb_client_get(void);
+ EAPI Eina_Bool elm_web_history_enable_get(const Evas_Object *obj);
/**
- * Get the ethumb_client connection state.
+ * Enables or disables the browsing history
*
- * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
- * otherwise.
+ * @param obj The web object
+ * @param enable Whether to enable or disable the browsing history
*/
- EAPI Eina_Bool elm_thumb_ethumb_client_connected(void);
+ EAPI void elm_web_history_enable_set(Evas_Object *obj, Eina_Bool enable);
/**
- * Make the thumbnail 'editable'.
+ * Gets whether text-only zoom is set
*
- * @param obj Thumb object.
- * @param set Turn on or off editability. Default is @c EINA_FALSE.
+ * @param obj The web object
*
- * This means the thumbnail is a valid drag target for drag and drop, and can be
- * cut or pasted too.
+ * @return EINA_TRUE if zoom is set to affect only text, EINA_FALSE
+ * otherwise
*
- * @see elm_thumb_editable_get()
+ * @see elm_web_zoom_text_only_set()
+ */
+ EAPI Eina_Bool elm_web_zoom_text_only_get(const Evas_Object *obj);
+ /**
+ * Enables or disables zoom to affect only text
*
- * @ingroup Thumb
+ * If set, then the zoom level set to the page will only be applied on text,
+ * leaving other objects, such as images, at their original size.
+ *
+ * @param obj The web object
+ * @param setting EINA_TRUE to use text-only zoom, EINA_FALSE to have zoom
+ * affect the entire page
*/
- EAPI Eina_Bool elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit) EINA_ARG_NONNULL(1);
+ EAPI void elm_web_zoom_text_only_set(Evas_Object *obj, Eina_Bool setting);
/**
- * Make the thumbnail 'editable'.
+ * Sets the default dialogs to use an Inwin instead of a normal window
*
- * @param obj Thumb object.
- * @return Editability.
+ * If set, then the default implementation for the JavaScript dialogs and
+ * file selector will be opened in an Inwin. Otherwise they will use a
+ * normal separated window.
*
- * This means the thumbnail is a valid drag target for drag and drop, and can be
- * cut or pasted too.
+ * @param obj The web object
+ * @param value EINA_TRUE to use Inwin, EINA_FALSE to use a normal window
+ */
+ EAPI void elm_web_inwin_mode_set(Evas_Object *obj, Eina_Bool value);
+ /**
+ * Gets whether Inwin mode is set for the current object
*
- * @see elm_thumb_editable_set()
+ * @param obj The web object
*
- * @ingroup Thumb
+ * @return EINA_TRUE if Inwin mode is set, EINA_FALSE otherwise
*/
- EAPI Eina_Bool elm_thumb_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_web_inwin_mode_get(const Evas_Object *obj);
+
+ EAPI void elm_web_window_features_ref(Elm_Web_Window_Features *wf);
+ EAPI void elm_web_window_features_unref(Elm_Web_Window_Features *wf);
+ EAPI void elm_web_window_features_bool_property_get(const Elm_Web_Window_Features *wf, Eina_Bool *toolbar_visible, Eina_Bool *statusbar_visible, Eina_Bool *scrollbars_visible, Eina_Bool *menubar_visible, Eina_Bool *locationbar_visble, Eina_Bool *fullscreen);
+ EAPI void elm_web_window_features_int_property_get(const Elm_Web_Window_Features *wf, int *x, int *y, int *w, int *h);
/**
* @}
EAPI Elm_Icon_Lookup_Order elm_toolbar_icon_order_lookup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
+ * Set whether the toolbar should always have an item selected.
+ *
+ * @param obj The toolbar object.
+ * @param wrap @c EINA_TRUE to enable always-select mode or @c EINA_FALSE to
+ * disable it.
+ *
+ * This will cause the toolbar to always have an item selected, and clicking
+ * the selected item will not cause a selected event to be emitted. Enabling this mode
+ * will immediately select the first toolbar item.
+ *
+ * Always-selected is disabled by default.
+ *
+ * @see elm_toolbar_always_select_mode_get().
+ *
+ * @ingroup Toolbar
+ */
+ EAPI void elm_toolbar_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether the toolbar should always have an item selected.
+ *
+ * @param obj The toolbar object.
+ * @return @c EINA_TRUE means an item will always be selected, @c EINA_FALSE indicates
+ * that it is possible to have no items selected. If @p obj is @c NULL, @c EINA_FALSE is returned.
+ *
+ * @see elm_toolbar_always_select_mode_set() for details.
+ *
+ * @ingroup Toolbar
+ */
+ EAPI Eina_Bool elm_toolbar_always_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
* Set whether the toolbar items' should be selected by the user or not.
*
* @param obj The toolbar object.
EAPI const char *elm_toolbar_item_icon_get(const Elm_Toolbar_Item *item) EINA_ARG_NONNULL(1);
/**
+ * Get the object of @p item.
+ *
+ * @param item The toolbar item.
+ * @return The object
+ *
+ * @ingroup Toolbar
+ */
+ EAPI Evas_Object *elm_toolbar_item_object_get(const Elm_Toolbar_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the icon object of @p item.
+ *
+ * @param item The toolbar item.
+ * @return The icon object
+ *
+ * @see elm_toolbar_item_icon_set() or elm_toolbar_item_icon_memfile_set() for details.
+ *
+ * @ingroup Toolbar
+ */
+ EAPI Evas_Object *elm_toolbar_item_icon_object_get(Elm_Toolbar_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the icon associated with @p item to an image in a binary buffer.
+ *
+ * @param item The toolbar item.
+ * @param img The binary data that will be used as an image
+ * @param size The size of binary data @p img
+ * @param format Optional format of @p img to pass to the image loader
+ * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
+ *
+ * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
+ *
+ * @note The icon image set by this function can be changed by
+ * elm_toolbar_item_icon_set().
+ *
+ * @ingroup Toolbar
+ */
+ EAPI Eina_Bool elm_toolbar_item_icon_memfile_set(Elm_Toolbar_Item *item, const void *img, size_t size, const char *format, const char *key) EINA_ARG_NONNULL(1);
+
+ /**
* Delete them item from the toolbar.
*
* @param item The item of toolbar to be deleted.
EAPI Eina_Bool elm_toolbar_item_cursor_engine_only_get(const Elm_Toolbar_Item *item) EINA_ARG_NONNULL(1);
/**
+ * Change a toolbar's orientation
+ * @param obj The toolbar object
+ * @param vertical If @c EINA_TRUE, the toolbar is vertical
+ * By default, a toolbar will be horizontal. Use this function to create a vertical toolbar.
+ * @ingroup Toolbar
+ */
+ EAPI void elm_toolbar_orientation_set(Evas_Object *obj, Eina_Bool vertical) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get a toolbar's orientation
+ * @param obj The toolbar object
+ * @return If @c EINA_TRUE, the toolbar is vertical
+ * By default, a toolbar will be horizontal. Use this function to determine whether a toolbar is vertical.
+ * @ingroup Toolbar
+ */
+ EAPI Eina_Bool elm_toolbar_orientation_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
* @}
*/
- /* tooltip */
+ /**
+ * @defgroup Tooltips Tooltips
+ *
+ * The Tooltip is an (internal, for now) smart object used to show a
+ * content in a frame on mouse hover of objects(or widgets), with
+ * tips/information about them.
+ *
+ * @{
+ */
+
EAPI double elm_tooltip_delay_get(void);
EAPI Eina_Bool elm_tooltip_delay_set(double delay);
EAPI void elm_object_tooltip_show(Evas_Object *obj) EINA_ARG_NONNULL(1);
EAPI void elm_object_tooltip_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
EAPI void elm_object_tooltip_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
EAPI const char *elm_object_tooltip_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_tooltip_size_restrict_disable(Evas_Object *obj, Eina_Bool disable); EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_tooltip_size_restrict_disabled_get(const Evas_Object *obj); EINA_ARG_NONNULL(1);
+
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Cursors Cursors
+ *
+ * The Elementary cursor is an internal smart object used to
+ * customize the mouse cursor displayed over objects (or
+ * widgets). In the most common scenario, the cursor decoration
+ * comes from the graphical @b engine Elementary is running
+ * on. Those engines may provide different decorations for cursors,
+ * and Elementary provides functions to choose them (think of X11
+ * cursors, as an example).
+ *
+ * There's also the possibility of, besides using engine provided
+ * cursors, also use ones coming from Edje theming files. Both
+ * globally and per widget, Elementary makes it possible for one to
+ * make the cursors lookup to be held on engines only or on
+ * Elementary's theme file, too.
+ *
+ * @{
+ */
+
+ /**
+ * Set the cursor to be shown when mouse is over the object
+ *
+ * Set the cursor that will be displayed when mouse is over the
+ * object. The object can have only one cursor set to it, so if
+ * this function is called twice for an object, the previous set
+ * will be unset.
+ * If using X cursors, a definition of all the valid cursor names
+ * is listed on Elementary_Cursors.h. If an invalid name is set
+ * the default cursor will be used.
+ *
+ * @param obj the object being set a cursor.
+ * @param cursor the cursor name to be used.
+ *
+ * @ingroup Cursors
+ */
EAPI void elm_object_cursor_set(Evas_Object *obj, const char *cursor) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the cursor to be shown when mouse is over the object
+ *
+ * @param obj an object with cursor already set.
+ * @return the cursor name.
+ *
+ * @ingroup Cursors
+ */
EAPI const char *elm_object_cursor_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Unset cursor for object
+ *
+ * Unset cursor for object, and set the cursor to default if the mouse
+ * was over this object.
+ *
+ * @param obj Target object
+ * @see elm_object_cursor_set()
+ *
+ * @ingroup Cursors
+ */
EAPI void elm_object_cursor_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Sets a different style for this object cursor.
+ *
+ * @note before you set a style you should define a cursor with
+ * elm_object_cursor_set()
+ *
+ * @param obj an object with cursor already set.
+ * @param style the theme style to use (default, transparent, ...)
+ *
+ * @ingroup Cursors
+ */
EAPI void elm_object_cursor_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the style for this object cursor.
+ *
+ * @param obj an object with cursor already set.
+ * @return style the theme style in use, defaults to "default". If the
+ * object does not have a cursor set, then NULL is returned.
+ *
+ * @ingroup Cursors
+ */
EAPI const char *elm_object_cursor_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set if the cursor set should be searched on the theme or should use
+ * the provided by the engine, only.
+ *
+ * @note before you set if should look on theme you should define a cursor
+ * with elm_object_cursor_set(). By default it will only look for cursors
+ * provided by the engine.
+ *
+ * @param obj an object with cursor already set.
+ * @param engine_only boolean to define it cursors should be looked only
+ * between the provided by the engine or searched on widget's theme as well.
+ *
+ * @ingroup Cursors
+ */
EAPI void elm_object_cursor_engine_only_set(Evas_Object *obj, Eina_Bool engine_only) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the cursor engine only usage for this object cursor.
+ *
+ * @param obj an object with cursor already set.
+ * @return engine_only boolean to define it cursors should be
+ * looked only between the provided by the engine or searched on
+ * widget's theme as well. If the object does not have a cursor
+ * set, then EINA_FALSE is returned.
+ *
+ * @ingroup Cursors
+ */
EAPI Eina_Bool elm_object_cursor_engine_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_tooltip_size_restrict_disable(Evas_Object *obj, Eina_Bool disable); EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_tooltip_size_restrict_disabled_get(const Evas_Object *obj); EINA_ARG_NONNULL(1);
- /* cursors */
+ /**
+ * Get the configured cursor engine only usage
+ *
+ * This gets the globally configured exclusive usage of engine cursors.
+ *
+ * @return 1 if only engine cursors should be used
+ * @ingroup Cursors
+ */
EAPI int elm_cursor_engine_only_get(void);
+
+ /**
+ * Set the configured cursor engine only usage
+ *
+ * This sets the globally configured exclusive usage of engine cursors.
+ * It won't affect cursors set before changing this value.
+ *
+ * @param engine_only If 1 only engine cursors will be enabled, if 0 will
+ * look for them on theme before.
+ * @return EINA_TRUE if value is valid and setted (0 or 1)
+ * @ingroup Cursors
+ */
EAPI Eina_Bool elm_cursor_engine_only_set(int engine_only);
/**
+ * @}
+ */
+
+ /**
* @defgroup Menu Menu
*
* @image html img/widget/menu/preview-00.png
*/
EAPI const char *elm_menu_item_object_icon_name_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
/**
- * @deprecated Use elm_menu_item_object_icon_name_set()
- */
- EAPI void elm_menu_item_icon_set(Elm_Menu_Item *item, const char *icon) EINA_ARG_NONNULL(1, 2) EINA_DEPRECATED;
- /**
- * @deprecated Use elm_menu_item_object_icon_name_get()
- */
- EAPI const char *elm_menu_item_icon_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1) EINA_DEPRECATED;
- /**
* @brief Set the content object of a menu item
*
* @param item The menu item object
*/
EAPI Evas_Object *elm_menu_item_object_content_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
/**
- * @deprecated Use elm_menu_item_object_content_get() instead.
- */
- EAPI Evas_Object *elm_menu_item_object_icon_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1) EINA_DEPRECATED;
- /**
* @brief Set the selected state of @p item.
*
* @param item The menu item object.
* @param policy_v Vertical scrollbar policy.
*
* This sets the scrollbar visibility policy for the given scroller.
- * #ELM_SCROLLER_POLICY_AUTO means the scrollber is made visible if it
+ * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it
* is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns
* it on all the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off.
* This applies respectively for the horizontal and vertical scrollbars.
*
* @ingroup List
*/
- EAPI Evas_Object *elm_list_item_base_get(const Elm_List_Item *item) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_list_item_object_get(const Elm_List_Item *item) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI Evas_Object *elm_list_item_base_get(const Elm_List_Item *item) EINA_ARG_NONNULL(1);
/**
* Get the label of item.
* - @c item_style - This is a constant string and simply defines the name
* of the item style. It @b must be specified and the default should be @c
* "default".
+ * - @c mode_item_style - This is a constant string and simply defines the
+ * name of the style that will be used for mode animations. It can be left
+ * as @c NULL if you don't plan to use Genlist mode. See
+ * elm_genlist_item_mode_set() for more info.
*
* - @c func - A struct with pointers to functions that will be called when
* an item is going to be actually created. All of them receive a @c data
* - @c label_get - The @c part parameter is the name string of one of the
* existing text parts in the Edje group implementing the item's theme.
* This function @b must return a strdup'()ed string, as the caller will
- * free() it when done. See #GenlistItemLabelGetFunc.
+ * free() it when done. See #Elm_Genlist_Item_Label_Get_Cb.
* - @c icon_get - The @c part parameter is the name string of one of the
* existing (icon) swallow parts in the Edje group implementing the item's
* theme. It must return @c NULL, when no icon is desired, or a valid
* object handle, otherwise. The object will be deleted by the genlist on
* its deletion or when the item is "unrealized". See
- * #GenlistItemIconGetFunc.
+ * #Elm_Genlist_Item_Icon_Get_Cb.
* - @c func.state_get - The @c part parameter is the name string of one of
* the state parts in the Edje group implementing the item's theme. Return
* @c EINA_FALSE for false/off or @c EINA_TRUE for true/on. Genlists will
* emit a signal to its theming Edje object with @c "elm,state,XXX,active"
* and @c "elm" as "emission" and "source" arguments, respectively, when
* the state is true (the default is false), where @c XXX is the name of
- * the (state) part. See #GenlistItemStateGetFunc.
+ * the (state) part. See #Elm_Genlist_Item_State_Get_Cb.
* - @c func.del - This is intended for use when genlist items are deleted,
* so any data attached to the item (e.g. its data parameter on creation)
- * can be deleted. See #GenlistItemDelFunc.
+ * can be deleted. See #Elm_Genlist_Item_Del_Cb.
*
* available item styles:
* - default
* elm_genlist_item_disabled_get() to get the disabled state.
*
* In general to indicate how the genlist should expand items horizontally to
- * fill the list area, use elm_genlist_horizontal_mode_set(). Valid modes are
- * ELM_LIST_LIMIT and ELM_LIST_SCROLL . The default is ELM_LIST_SCROLL. This
+ * fill the list area, use elm_genlist_horizontal_set(). Valid modes are
+ * ELM_LIST_LIMIT and ELM_LIST_SCROLL. The default is ELM_LIST_SCROLL. This
* mode means that if items are too wide to fit, the scroller will scroll
* horizontally. Otherwise items are expanded to fill the width of the
* viewport of the scroller. If it is ELM_LIST_LIMIT, items will be expanded
* - @c "drag" - This is called when the item in the list is being dragged.
* - @c "longpressed" - This is called when the item is pressed for a certain
* amount of time. By default it's 1 second.
+ * - @c "scroll,anim,start" - This is called when scrolling animation has
+ * started.
+ * - @c "scroll,anim,stop" - This is called when scrolling animation has
+ * stopped.
+ * - @c "scroll,drag,start" - This is called when dragging the content has
+ * started.
+ * - @c "scroll,drag,stop" - This is called when dragging the content has
+ * stopped.
* - @c "scroll,edge,top" - This is called when the genlist is scrolled until
* the top edge.
* - @c "scroll,edge,bottom" - This is called when the genlist is scrolled
typedef struct _Elm_Genlist_Item_Class Elm_Genlist_Item_Class; /**< Genlist item class definition structs */
typedef struct _Elm_Genlist_Item Elm_Genlist_Item; /**< Item of Elm_Genlist. Sub-type of Elm_Widget_Item */
typedef struct _Elm_Genlist_Item_Class_Func Elm_Genlist_Item_Class_Func; /**< Class functions for genlist item class */
- typedef char *(*GenlistItemLabelGetFunc) (void *data, Evas_Object *obj, const char *part); /**< Label fetching class function for genlist item classes. */
- typedef Evas_Object *(*GenlistItemIconGetFunc) (void *data, Evas_Object *obj, const char *part); /**< Icon fetching class function for genlist item classes. */
- typedef Eina_Bool (*GenlistItemStateGetFunc) (void *data, Evas_Object *obj, const char *part); /**< State fetching class function for genlist item classes. */
- typedef void (*GenlistItemDelFunc) (void *data, Evas_Object *obj); /**< Deletion class function for genlist item classes. */
- typedef void (*GenlistItemMovedFunc) (Evas_Object *obj, Elm_Genlist_Item *item, Elm_Genlist_Item *rel_item, Eina_Bool move_after);
+ typedef char *(*Elm_Genlist_Item_Label_Get_Cb) (void *data, Evas_Object *obj, const char *part); /**< Label fetching class function for genlist item classes. */
+ typedef Evas_Object *(*Elm_Genlist_Item_Icon_Get_Cb) (void *data, Evas_Object *obj, const char *part); /**< Icon fetching class function for genlist item classes. */
+ typedef Eina_Bool (*Elm_Genlist_Item_State_Get_Cb) (void *data, Evas_Object *obj, const char *part); /**< State fetching class function for genlist item classes. */
+ typedef void (*Elm_Genlist_Item_Del_Cb) (void *data, Evas_Object *obj); /**< Deletion class function for genlist item classes. */
+ typedef void (*GenlistItemMovedFunc) (Evas_Object *obj, Elm_Genlist_Item *item, Elm_Genlist_Item *rel_item, Eina_Bool move_after); /** TODO: remove this by SeoZ **/
+
+ typedef char *(*GenlistItemLabelGetFunc) (void *data, Evas_Object *obj, const char *part) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Genlist_Item_Label_Get_Cb instead. */
+ typedef Evas_Object *(*GenlistItemIconGetFunc) (void *data, Evas_Object *obj, const char *part) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Genlist_Item_Icon_Get_Cb instead. */
+ typedef Eina_Bool (*GenlistItemStateGetFunc) (void *data, Evas_Object *obj, const char *part) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Genlist_Item_State_Get_Cb instead. */
+ typedef void (*GenlistItemDelFunc) (void *data, Evas_Object *obj) EINA_DEPRECATED; /** DEPRECATED. Use Elm_Genlist_Item_Del_Cb instead. */
/**
* @struct _Elm_Genlist_Item_Class
const char *item_style; /**< style of this class. */
struct
{
- GenlistItemLabelGetFunc label_get; /**< Label fetching class function for genlist item classes.*/
- GenlistItemIconGetFunc icon_get; /**< Icon fetching class function for genlist item classes. */
- GenlistItemStateGetFunc state_get; /**< State fetching class function for genlist item classes. */
- GenlistItemDelFunc del; /**< Deletion class function for genlist item classes. */
+ Elm_Genlist_Item_Label_Get_Cb label_get; /**< Label fetching class function for genlist item classes.*/
+ Elm_Genlist_Item_Icon_Get_Cb icon_get; /**< Icon fetching class function for genlist item classes. */
+ Elm_Genlist_Item_State_Get_Cb state_get; /**< State fetching class function for genlist item classes. */
+ Elm_Genlist_Item_Del_Cb del; /**< Deletion class function for genlist item classes. */
GenlistItemMovedFunc moved; // TODO: do not use this. change this to smart callback.
} func;
const char *mode_item_style;
* ELM_LIST_LIMIT, items will be expanded to the viewport width and
* limited to that size.
*
- * @see elm_genlist_horizontal_mode_get()
+ * @see elm_genlist_horizontal_get()
*
* @ingroup Genlist
*/
- EAPI void elm_genlist_horizontal_mode_set(Evas_Object *obj, Elm_List_Mode mode) EINA_ARG_NONNULL(1);
+ EAPI void elm_genlist_horizontal_set(Evas_Object *obj, Elm_List_Mode mode) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI void elm_genlist_horizontal_mode_set(Evas_Object *obj, Elm_List_Mode mode) EINA_ARG_NONNULL(1);
/**
* Gets the horizontal stretching mode.
*
* @return The mode to use
* (#ELM_LIST_LIMIT, #ELM_LIST_SCROLL)
*
- * @see elm_genlist_horizontal_mode_set()
+ * @see elm_genlist_horizontal_set()
*
* @ingroup Genlist
*/
- EAPI Elm_List_Mode elm_genlist_horizontal_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI Elm_List_Mode elm_genlist_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EINA_DEPRECATED EAPI Elm_List_Mode elm_genlist_horizontal_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Set the always select mode.
*
* This will enable the compress mode where items are "compressed"
* horizontally to fit the genlist scrollable viewport width. This is
* special for genlist. Do not rely on
- * elm_genlist_horizontal_mode_set() being set to @c ELM_LIST_COMPRESS to
+ * elm_genlist_horizontal_set() being set to @c ELM_LIST_COMPRESS to
* work as genlist needs to handle it specially.
*
* @see elm_genlist_compress_mode_get()
*
* @ingroup Genlist
*/
- EAPI void elm_genlist_realized_items_update(Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_genlist_item_mode_set(Elm_Genlist_Item *it, const char *mode_type, Eina_Bool mode_set) EINA_ARG_NONNULL(1, 2);
- EAPI const char *elm_genlist_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI const Elm_Genlist_Item *elm_genlist_mode_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ EAPI void elm_genlist_realized_items_update(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Activate a genlist mode on an item
+ *
+ * @param item The genlist item
+ * @param mode Mode name
+ * @param mode_set Boolean to define set or unset mode.
+ *
+ * A genlist mode is a different way of selecting an item. Once a mode is
+ * activated on an item, any other selected item is immediately unselected.
+ * This feature provides an easy way of implementing a new kind of animation
+ * for selecting an item, without having to entirely rewrite the item style
+ * theme. However, the elm_genlist_selected_* API can't be used to get what
+ * item is activate for a mode.
+ *
+ * The current item style will still be used, but applying a genlist mode to
+ * an item will select it using a different kind of animation.
+ *
+ * The current active item for a mode can be found by
+ * elm_genlist_mode_item_get().
+ *
+ * The characteristics of genlist mode are:
+ * - Only one mode can be active at any time, and for only one item.
+ * - Genlist handles deactivating other items when one item is activated.
+ * - A mode is defined in the genlist theme (edc), and more modes can easily
+ * be added.
+ * - A mode style and the genlist item style are different things. They
+ * can be combined to provide a default style to the item, with some kind
+ * of animation for that item when the mode is activated.
+ *
+ * When a mode is activated on an item, a new view for that item is created.
+ * The theme of this mode defines the animation that will be used to transit
+ * the item from the old view to the new view. This second (new) view will be
+ * active for that item while the mode is active on the item, and will be
+ * destroyed after the mode is totally deactivated from that item.
+ *
+ * @see elm_genlist_mode_get()
+ * @see elm_genlist_mode_item_get()
+ *
+ * @ingroup Genlist
+ */
+ EAPI void elm_genlist_item_mode_set(Elm_Genlist_Item *it, const char *mode_type, Eina_Bool mode_set) EINA_ARG_NONNULL(1, 2);
+ /**
+ * Get the last (or current) genlist mode used.
+ *
+ * @param obj The genlist object
+ *
+ * This function just returns the name of the last used genlist mode. It will
+ * be the current mode if it's still active.
+ *
+ * @see elm_genlist_item_mode_set()
+ * @see elm_genlist_mode_item_get()
+ *
+ * @ingroup Genlist
+ */
+ EAPI const char *elm_genlist_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * Get active genlist mode item
+ *
+ * @param obj The genlist object
+ * @return The active item for that current mode. Or @c NULL if no item is
+ * activated with any mode.
+ *
+ * This function returns the item that was activated with a mode, by the
+ * function elm_genlist_item_mode_set().
+ *
+ * @see elm_genlist_item_mode_set()
+ * @see elm_genlist_mode_get()
+ *
+ * @ingroup Genlist
+ */
+ EAPI const Elm_Genlist_Item *elm_genlist_mode_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set reorder mode
+ *
+ * @param obj The genlist object
+ * @param reorder_mode The reorder mode
+ * (EINA_TRUE = on, EINA_FALSE = off)
+ *
+ * @ingroup Genlist
+ */
EAPI void elm_genlist_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the reorder mode
+ *
+ * @param obj The genlist object
+ * @return The reorder mode
+ * (EINA_TRUE = on, EINA_FALSE = off)
+ *
+ * @ingroup Genlist
+ */
EAPI Eina_Bool elm_genlist_reorder_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* @defgroup Index Index
*
* @image html img/widget/index/preview-00.png
+ * @image latex img/widget/index/preview-00.eps
*
* An index widget gives you an index for fast access to whichever
* group of other UI items one might have. It's a list of text
* @ingroup Flipselector
*/
EAPI double elm_flipselector_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
- /**
- * @}
- */
-
- /**
- * @addtogroup Animator Animator
- * @ingroup Elementary
- *
- * @brief Functions to ease creation of animations.
- *
- * elm_animator is designed to provide an easy way to create animations.
- * Creating an animation with elm_animator is as simple as setting a
- * duration, an operating callback and telling it to run the animation.
- * However that is not the full extent of elm_animator's ability, animations
- * can be paused and resumed, reversed and the animation need not be linear.
- *
- * To run an animation you must specify at least a duration and operation
- * callback, not setting any other properties will create a linear animation
- * that runs once and is not reversed.
- *
- * @ref elm_animator_example_page_01 "This" example should make all of that
- * very clear.
- *
- * @warning elm_animator is @b not a widget.
- * @{
- */
- /**
- * @brief Type of curve desired for animation.
- *
- * The speed in which an animation happens doesn't have to be linear, some
- * animations will look better if they're accelerating or decelerating, so
- * elm_animator provides four options in this regard:
- *
- * @image html elm_animator_curve_style.png
- * @image latex elm_animator_curve_style.eps width=\textwidth
- * As can be seen in the image the speed of the animation will be:
- * @li ELM_ANIMATOR_CURVE_LINEAR constant
- * @li ELM_ANIMATOR_CURVE_IN_OUT start slow, speed up and then slow down
- * @li ELM_ANIMATOR_CURVE_IN start slow and then speed up
- * @li ELM_ANIMATOR_CURVE_OUT start fast and then slow down
- */
- typedef enum
- {
- ELM_ANIMATOR_CURVE_LINEAR,
- ELM_ANIMATOR_CURVE_IN_OUT,
- ELM_ANIMATOR_CURVE_IN,
- ELM_ANIMATOR_CURVE_OUT
- } Elm_Animator_Curve_Style;
- typedef struct _Elm_Animator Elm_Animator;
- /**
- * Called back per loop of an elementary animators cycle
- * @param data user-data given to elm_animator_operation_callback_set()
- * @param animator the animator being run
- * @param double the position in the animation
- */
- typedef void (*Elm_Animator_Operation_Cb) (void *data, Elm_Animator *animator, double frame);
- /**
- * Called back when an elementary animator finishes
- * @param data user-data given to elm_animator_completion_callback_set()
- */
- typedef void (*Elm_Animator_Completion_Cb) (void *data);
-
- /**
- * @brief Create a new animator.
- *
- * @param[in] parent Parent object
- *
- * The @a parent argument can be set to NULL for no parent. If a parent is set
- * there is no need to call elm_animator_del(), when the parent is deleted it
- * will delete the animator.
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI Elm_Animator* elm_animator_add(Evas_Object *parent);
- /**
- * Deletes the animator freeing any resources it used. If the animator was
- * created with a NULL parent this must be called, otherwise it will be
- * automatically called when the parent is deleted.
- *
- * @param[in] animator Animator object
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_del(Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * Set the duration of the animation.
- *
- * @param[in] animator Animator object
- * @param[in] duration Duration in second
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_duration_set(Elm_Animator *animator, double duration) EINA_ARG_NONNULL(1);
- /**
- * @brief Set the callback function for animator operation.
- *
- * @param[in] animator Animator object
- * @param[in] func @ref Elm_Animator_Operation_Cb "Callback" function pointer
- * @param[in] data Callback function user argument
- *
- * The @p func callback will be called with a frame value in range [0, 1] which
- * indicates how far along the animation should be. It is the job of @p func to
- * actually change the state of any object(or objects) that are being animated.
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_operation_callback_set(Elm_Animator *animator, Elm_Animator_Operation_Cb func, void *data) EINA_ARG_NONNULL(1);
- /**
- * Set the callback function for the when the animation ends.
- *
- * @param[in] animator Animator object
- * @param[in] func Callback function pointe
- * @param[in] data Callback function user argument
- *
- * @warning @a func will not be executed if elm_animator_stop() is called.
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_completion_callback_set(Elm_Animator *animator, Elm_Animator_Completion_Cb func, void *data) EINA_ARG_NONNULL(1);
- /**
- * @brief Stop animator.
- *
- * @param[in] animator Animator object
- *
- * If called before elm_animator_animate() it does nothing. If there is an
- * animation in progress the animation will be stopped(the operation callback
- * will not be executed again) and it can't be restarted using
- * elm_animator_resume().
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_stop(Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * Set the animator repeat count.
- *
- * @param[in] animator Animator object
- * @param[in] repeat_cnt Repeat count
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_repeat_set(Elm_Animator *animator, unsigned int repeat_cnt) EINA_ARG_NONNULL(1);
- /**
- * @brief Start animation.
- *
- * @param[in] animator Animator object
- *
- * This function starts the animation if the nescessary properties(duration
- * and operation callback) have been set. Once started the animation will
- * run until complete or elm_animator_stop() is called.
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_animate(Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * Sets the animation @ref Elm_Animator_Curve_Style "acceleration style".
- *
- * @param[in] animator Animator object
- * @param[in] cs Curve style. Default is ELM_ANIMATOR_CURVE_LINEAR
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_curve_style_set(Elm_Animator *animator, Elm_Animator_Curve_Style cs) EINA_ARG_NONNULL(1);
- /**
- * Gets the animation @ref Elm_Animator_Curve_Style "acceleration style".
- *
- * @param[in] animator Animator object
- * @param[in] cs Curve style. Default is ELM_ANIMATOR_CURVE_LINEAR
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI Elm_Animator_Curve_Style elm_animator_curve_style_get(const Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * @brief Sets wether the animation should be automatically reversed.
- *
- * @param[in] animator Animator object
- * @param[in] reverse Reverse or not
- *
- * This controls wether the animation will be run on reverse imediately after
- * running forward. When this is set together with repetition the animation
- * will run in reverse once for each time it ran forward.@n
- * Runnin an animation in reverse is accomplished by calling the operation
- * callback with a frame value starting at 1 and diminshing until 0.
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_auto_reverse_set(Elm_Animator *animator, Eina_Bool reverse) EINA_ARG_NONNULL(1);
- /**
- * Gets wether the animation will automatically reversed
- *
- * @param[in] animator Animator object
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI Eina_Bool elm_animator_auto_reverse_get(const Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * Gets the status for the animator operation. The status of the animator @b
- * doesn't take in to account elm_animator_pause() or elm_animator_resume(), it
- * only informs if the animation was started and has not ended(either normally
- * or through elm_animator_stop()).
- *
- * @param[in] animator Animator object
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI Eina_Bool elm_animator_operating_get(const Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * Gets how many times the animation will be repeated
- *
- * @param[in] animator Animator object
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI unsigned int elm_animator_repeat_get(const Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * Pause the animator.
- *
- * @param[in] animator Animator object
- *
- * This causes the animation to be temporarily stopped(the operation callback
- * will not be called). If the animation is not yet running this is a no-op.
- * Once an animation has been paused with this function it can be resumed
- * using elm_animator_resume().
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_pause(Elm_Animator *animator) EINA_ARG_NONNULL(1);
- /**
- * @brief Resumes the animator.
- *
- * @param[in] animator Animator object
- *
- * Resumes an animation that was paused using elm_animator_pause(), after
- * calling this function calls to the operation callback will happen
- * normally. If an animation is stopped by means of elm_animator_stop it
- * @b can't be restarted with this function.@n
- *
- * @warning When an animation is resumed it doesn't start from where it was paused, it
- * will go to where it would have been if it had not been paused. If an
- * animation with a duration of 3 seconds is paused after 1 second for 1 second
- * it will resume as if it had ben animating for 2 seconds, the operating
- * callback will be called with a frame value of aproximately 2/3.
- * @deprecated Use @ref Transit instead.
- */
- EINA_DEPRECATED EAPI void elm_animator_resume(Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* @}
*/
/**
- * @defgroup Calendar Calendar
- * @ingroup Elementary
- *
- * @image html img/widget/calendar/preview-00.png
- * @image latex img/widget/calendar/preview-00.eps
- *
- * A calendar is a widget that displays a regular calendar, one
- * month at a time, to the user, and can allows the user to select a date.
- *
- * It has support to adding check marks (holidays and checks are supported
- * by default theme).
- *
- * Weekday names and the function used to format month and year to
- * be displayed can be set, giving more flexibility to this widget.
- *
- * Smart callbacks one can register to:
- * - "changed" - emitted when the user selects a day or changes the
- * displayed month, what actually changes the selected day as well.
- *
- * Available styles for it:
- * - @c "default"
- *
- * List of examples:
- * @li @ref calendar_example_01
- * @li @ref calendar_example_02
- * @li @ref calendar_example_03
- * @li @ref calendar_example_04
- * @li @ref calendar_example_05
- * @li @ref calendar_example_06
- */
-
- /**
* @addtogroup Calendar
* @{
*/
EAPI void elm_diskselector_display_item_num_set(Evas_Object *obj, int num) EINA_ARG_NONNULL(1);
/**
+ * Get the number of items in the diskselector object.
+ *
+ * @param obj The diskselector object.
+ *
+ * @ingroup Diskselector
+ */
+ EAPI int elm_diskselector_display_item_num_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
* Set bouncing behaviour when the scrolled content reaches an edge.
*
* Tell the internal scroller object whether it should bounce or not
* @param policy_v Vertical scrollbar policy.
*
* This sets the scrollbar visibility policy for the given scroller.
- * #ELM_SCROLLER_POLICY_AUTO means the scrollber is made visible if it
+ * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it
* is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns
* it on all the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off.
* This applies respectively for the horizontal and vertical scrollbars.
* @{
*
* @image html img/widget/colorselector/preview-00.png
+ * @image latex img/widget/colorselector/preview-00.eps
*
* @brief Widget for user to select a color.
*
* @ref tutorial_ctxpopup shows the usage of a good deal of the API.
* @{
*/
- typedef struct _Elm_Ctxpopup_Item Elm_Ctxpopup_Item;
-
typedef enum _Elm_Ctxpopup_Direction
{
ELM_CTXPOPUP_DIRECTION_DOWN, /**< ctxpopup show appear below clicked
the clicked area */
ELM_CTXPOPUP_DIRECTION_UP, /**< ctxpopup show appear above the clicked
area */
+ ELM_CTXPOPUP_DIRECTION_UNKNOWN, /**< ctxpopup does not determine it's direction yet*/
} Elm_Ctxpopup_Direction;
/**
*
* @see elm_ctxpopup_content_set()
*/
- Elm_Ctxpopup_Item *elm_ctxpopup_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
+ Elm_Object_Item *elm_ctxpopup_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
/**
* @brief Delete the given item in a ctxpopup object.
*
- * @param item Ctxpopup item to be deleted
+ * @param it Ctxpopup item to be deleted
*
* @see elm_ctxpopup_item_append()
*/
- EAPI void elm_ctxpopup_item_del(Elm_Ctxpopup_Item *item) EINA_ARG_NONNULL(1);
+ EAPI void elm_ctxpopup_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
/**
* @brief Set the ctxpopup item's state as disabled or enabled.
*
- * @param item Ctxpopup item to be enabled/disabled
+ * @param it Ctxpopup item to be enabled/disabled
* @param disabled @c EINA_TRUE to disable it, @c EINA_FALSE to enable it
*
* When disabled the item is greyed out to indicate it's state.
*/
- EAPI void elm_ctxpopup_item_disabled_set(Elm_Ctxpopup_Item *item, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+ EAPI void elm_ctxpopup_item_disabled_set(Elm_Object_Item *it, Eina_Bool disabled) EINA_ARG_NONNULL(1);
/**
* @brief Get the ctxpopup item's disabled/enabled state.
*
- * @param item Ctxpopup item to be enabled/disabled
+ * @param it Ctxpopup item to be enabled/disabled
* @return disabled @c EINA_TRUE, if disabled, @c EINA_FALSE otherwise
*
* @see elm_ctxpopup_item_disabled_set()
*/
- EAPI Eina_Bool elm_ctxpopup_item_disabled_get(const Elm_Ctxpopup_Item *item) EINA_ARG_NONNULL(1);
+ EAPI Eina_Bool elm_ctxpopup_item_disabled_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
/**
* @brief Get the icon object for the given ctxpopup item.
*
- * @param item Ctxpopup item
+ * @param it Ctxpopup item
* @return icon object or @c NULL, if the item does not have icon or an error
* occurred
*
* @see elm_ctxpopup_item_append()
* @see elm_ctxpopup_item_icon_set()
*/
- EAPI Evas_Object *elm_ctxpopup_item_icon_get(const Elm_Ctxpopup_Item *item) EINA_ARG_NONNULL(1);
+ EAPI Evas_Object *elm_ctxpopup_item_icon_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
/**
* @brief Sets the side icon associated with the ctxpopup item
*
- * @param item Ctxpopup item
+ * @param it Ctxpopup item
* @param icon Icon object to be set
*
* Once the icon object is set, a previously set one will be deleted.
*
* @see elm_ctxpopup_item_append()
*/
- EAPI void elm_ctxpopup_item_icon_set(Elm_Ctxpopup_Item *item, Evas_Object *icon) EINA_ARG_NONNULL(1);
+ EAPI void elm_ctxpopup_item_icon_set(Elm_Object_Item *it, Evas_Object *icon) EINA_ARG_NONNULL(1);
/**
* @brief Get the label for the given ctxpopup item.
*
- * @param item Ctxpopup item
+ * @param it Ctxpopup item
* @return label string or @c NULL, if the item does not have label or an
* error occured
*
* @see elm_ctxpopup_item_append()
* @see elm_ctxpopup_item_label_set()
*/
- EAPI const char *elm_ctxpopup_item_label_get(const Elm_Ctxpopup_Item *item) EINA_ARG_NONNULL(1);
+ EAPI const char *elm_ctxpopup_item_label_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
/**
* @brief (Re)set the label on the given ctxpopup item.
*
- * @param item Ctxpopup item
+ * @param it Ctxpopup item
* @param label String to set as label
*/
- EAPI void elm_ctxpopup_item_label_set(Elm_Ctxpopup_Item *item, const char *label) EINA_ARG_NONNULL(1);
+ EAPI void elm_ctxpopup_item_label_set(Elm_Object_Item *it, const char *label) EINA_ARG_NONNULL(1);
/**
* @brief Set an elm widget as the content of the ctxpopup.
*
* @see elm_ctxpopup_direction_priority_set() for more information.
*/
EAPI void elm_ctxpopup_direction_priority_get(Evas_Object *obj, Elm_Ctxpopup_Direction *first, Elm_Ctxpopup_Direction *second, Elm_Ctxpopup_Direction *third, Elm_Ctxpopup_Direction *fourth) EINA_ARG_NONNULL(1);
+
+ /**
+ * @brief Get the current direction of a ctxpopup.
+ *
+ * @param obj Ctxpopup object
+ * @return current direction of a ctxpopup
+ *
+ * @warning Once the ctxpopup showed up, the direction would be determined
+ */
+ EAPI Elm_Ctxpopup_Direction elm_ctxpopup_direction_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
/**
* @}
*/
* positioned at left.
*
* @see elm_segment_control_item_add()
- * @see elm_segment_control_count_get()
+ * @see elm_segment_control_item_count_get()
* @see elm_segment_control_item_del()
*
* @ingroup SegmentControl
* @}
*/
+ /**
+ * @defgroup Grid Grid
+ *
+ * The grid is a grid layout widget that lays out a series of children as a
+ * fixed "grid" of widgets using a given percentage of the grid width and
+ * height each using the child object.
+ *
+ * The Grid uses a "Virtual resolution" that is stretched to fill the grid
+ * widgets size itself. The default is 100 x 100, so that means the
+ * position and sizes of children will effectively be percentages (0 to 100)
+ * of the width or height of the grid widget
+ *
+ * @{
+ */
+ /**
+ * Add a new grid to the parent
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ *
+ * @ingroup Grid
+ */
EAPI Evas_Object *elm_grid_add(Evas_Object *parent);
+
+ /**
+ * Set the virtual size of the grid
+ *
+ * @param obj The grid object
+ * @param w The virtual width of the grid
+ * @param h The virtual height of the grid
+ *
+ * @ingroup Grid
+ */
EAPI void elm_grid_size_set(Evas_Object *obj, int w, int h);
+
+ /**
+ * Get the virtual size of the grid
+ *
+ * @param obj The grid object
+ * @param w Pointer to integer to store the virtual width of the grid
+ * @param h Pointer to integer to store the virtual height of the grid
+ *
+ * @ingroup Grid
+ */
EAPI void elm_grid_size_get(Evas_Object *obj, int *w, int *h);
+
+ /**
+ * Pack child at given position and size
+ *
+ * @param obj The grid object
+ * @param subobj The child to pack
+ * @param x The virtual x coord at which to pack it
+ * @param y The virtual y coord at which to pack it
+ * @param w The virtual width at which to pack it
+ * @param h The virtual height at which to pack it
+ *
+ * @ingroup Grid
+ */
EAPI void elm_grid_pack(Evas_Object *obj, Evas_Object *subobj, int x, int y, int w, int h);
+
+ /**
+ * Unpack a child from a grid object
+ *
+ * @param obj The grid object
+ * @param subobj The child to unpack
+ *
+ * @ingroup Grid
+ */
EAPI void elm_grid_unpack(Evas_Object *obj, Evas_Object *subobj);
+
+ /**
+ * Faster way to remove all child objects from a grid object.
+ *
+ * @param obj The grid object
+ * @param clear If true, it will delete just removed children
+ *
+ * @ingroup Grid
+ */
EAPI void elm_grid_clear(Evas_Object *obj, Eina_Bool clear);
+
+ /**
+ * Set packing of an existing child at to position and size
+ *
+ * @param subobj The child to set packing of
+ * @param x The virtual x coord at which to pack it
+ * @param y The virtual y coord at which to pack it
+ * @param w The virtual width at which to pack it
+ * @param h The virtual height at which to pack it
+ *
+ * @ingroup Grid
+ */
EAPI void elm_grid_pack_set(Evas_Object *subobj, int x, int y, int w, int h);
+
+ /**
+ * get packing of a child
+ *
+ * @param subobj The child to query
+ * @param x Pointer to integer to store the virtual x coord
+ * @param y Pointer to integer to store the virtual y coord
+ * @param w Pointer to integer to store the virtual width
+ * @param h Pointer to integer to store the virtual height
+ *
+ * @ingroup Grid
+ */
EAPI void elm_grid_pack_get(Evas_Object *subobj, int *x, int *y, int *w, int *h);
- EAPI Evas_Object *elm_genscroller_add(Evas_Object *parent);
- EAPI void elm_genscroller_world_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
+ /**
+ * @}
+ */
+
+ EAPI Evas_Object *elm_factory_add(Evas_Object *parent);
+ EAPI void elm_factory_content_set(Evas_Object *obj, Evas_Object *content);
+ EAPI Evas_Object *elm_factory_content_get(const Evas_Object *obj);
+ EAPI void elm_factory_maxmin_mode_set(Evas_Object *obj, Eina_Bool enabled);
+ EAPI Eina_Bool elm_factory_maxmin_mode_get(const Evas_Object *obj);
+ EAPI void elm_factory_maxmin_reset_set(Evas_Object *obj);
+ /**
+ * @defgroup Video Video
+ *
+ * This object display an player that let you control an Elm_Video
+ * object. It take care of updating it's content according to what is
+ * going on inside the Emotion object. It does activate the remember
+ * function on the linked Elm_Video object.
+ *
+ * Signals that you can add callback for are :
+ *
+ * "forward,clicked" - the user clicked the forward button.
+ * "info,clicked" - the user clicked the info button.
+ * "next,clicked" - the user clicked the next button.
+ * "pause,clicked" - the user clicked the pause button.
+ * "play,clicked" - the user clicked the play button.
+ * "prev,clicked" - the user clicked the prev button.
+ * "rewind,clicked" - the user clicked the rewind button.
+ * "stop,clicked" - the user clicked the stop button.
+ */
EAPI Evas_Object *elm_video_add(Evas_Object *parent);
EAPI void elm_video_file_set(Evas_Object *video, const char *filename);
EAPI void elm_video_uri_set(Evas_Object *video, const char *uri);
EAPI Evas_Object *elm_player_add(Evas_Object *parent);
EAPI void elm_player_video_set(Evas_Object *player, Evas_Object *video);
- /* naviframe */
- typedef struct _Elm_Naviframe_Item Elm_Naviframe_Item;
-
- typedef enum
- {
- ELM_NAVIFRAME_PREV_BUTTON,
- ELM_NAVIFRAME_NEXT_BUTTON
- } Elm_Naviframe_Button_Type;
-
+ /**
+ * @defgroup Naviframe Naviframe
+ *
+ * @brief Naviframe is a kind of view manager for the applications.
+ *
+ * Naviframe provides functions to switch different pages with stack
+ * mechanism. It means if one page(item) needs to be changed to the new one,
+ * then naviframe would push the new page to it's internal stack. Of course,
+ * it can be back to the previous page by popping the top page. Naviframe
+ * provides some transition effect while the pages are switching (same as
+ * pager).
+ *
+ * Since each item could keep the different styles, users could keep the
+ * same look & feel for the pages or different styles for the items in it's
+ * application.
+ *
+ * Signals that you can add callback for are:
+ *
+ * @li "transition,finished" - When the transition is finished in changing
+ * the item
+ * @li "title,clicked" - User clicked title area
+ *
+ * Default contents parts for the naviframe items that you can use for are:
+ *
+ * @li "elm.swallow.content" - The main content of the page
+ * @li "elm.swallow.prev_btn" - The button to go to the previous page
+ * @li "elm.swallow.next_btn" - The button to go to the next page
+ *
+ * Default text parts of naviframe items that you can be used are:
+ *
+ * @li "elm.text.title" - The title label in the title area
+ *
+ * @ref tutorial_naviframe gives a good overview of the usage of the API.
+ * @{
+ */
+ /**
+ * @brief Add a new Naviframe object to the parent.
+ *
+ * @param parent Parent object
+ * @return New object or @c NULL, if it cannot be created
+ */
EAPI Evas_Object *elm_naviframe_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- EAPI Elm_Naviframe_Item *elm_naviframe_item_push(Evas_Object *obj, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style) EINA_ARG_NONNULL(1, 5);
+ /**
+ * @brief Push a new item to the top of the naviframe stack (and show it).
+ *
+ * @param obj The naviframe object
+ * @param title_label The label in the title area. The name of the title
+ * label part is "elm.text.title"
+ * @param prev_btn The button to go to the previous item. If it is NULL,
+ * then naviframe will create a back button automatically. The name of
+ * the prev_btn part is "elm.swallow.prev_btn"
+ * @param next_btn The button to go to the next item. Or It could be just an
+ * extra function button. The name of the next_btn part is
+ * "elm.swallow.next_btn"
+ * @param content The main content object. The name of content part is
+ * "elm.swallow.content"
+ * @param item_style The current item style name. @c NULL would be default.
+ * @return The created item or @c NULL upon failure.
+ *
+ * The item pushed becomes one page of the naviframe, this item will be
+ * deleted when it is popped.
+ *
+ * @see also elm_naviframe_item_style_set()
+ *
+ * The following styles are available for this item:
+ * @li @c "default"
+ */
+ EAPI Elm_Object_Item *elm_naviframe_item_push(Evas_Object *obj, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style) EINA_ARG_NONNULL(1, 5);
+ /**
+ * @brief Pop an item that is on top of the stack
+ *
+ * @param obj The naviframe object
+ * @return @c NULL or the content object(if the
+ * elm_naviframe_content_preserve_on_pop_get is true).
+ *
+ * This pops an item that is on the top(visible) of the naviframe, makes it
+ * disappear, then deletes the item. The item that was underneath it on the
+ * stack will become visible.
+ *
+ * @see also elm_naviframe_content_preserve_on_pop_get()
+ */
EAPI Evas_Object *elm_naviframe_item_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Pop the items between the top and the above one on the given item.
+ *
+ * @param it The naviframe item
+ */
+ EAPI void elm_naviframe_item_pop_to(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+ /**
+ * @brief preserve the content objects when items are popped.
+ *
+ * @param obj The naviframe object
+ * @param preserve Enable the preserve mode if EINA_TRUE, disable otherwise
+ *
+ * @see also elm_naviframe_content_preserve_on_pop_get()
+ */
EAPI void elm_naviframe_content_preserve_on_pop_set(Evas_Object *obj, Eina_Bool preserve) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get a value whether preserve mode is enabled or not.
+ *
+ * @param obj The naviframe object
+ * @return If @c EINA_TRUE, preserve mode is enabled
+ *
+ * @see also elm_naviframe_content_preserve_on_pop_set()
+ */
EAPI Eina_Bool elm_naviframe_content_preserve_on_pop_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_naviframe_item_content_set(Elm_Naviframe_Item *item, Evas_Object *content) EINA_ARG_NONNULL(1);
- EAPI Evas_Object *elm_naviframe_item_content_get(const Elm_Naviframe_Item *it) EINA_ARG_NONNULL(1);
- EAPI void elm_naviframe_item_title_label_set(Elm_Naviframe_Item *it, const char *label) EINA_ARG_NONNULL(1);
- EAPI const char *elm_naviframe_item_title_label_get(const Elm_Naviframe_Item *it) EINA_ARG_NONNULL(1);
- EAPI void elm_naviframe_item_subtitle_label_set(Elm_Naviframe_Item *it, const char *label) EINA_ARG_NONNULL(1);
- EAPI const char *elm_naviframe_item_subtitle_label_get(const Elm_Naviframe_Item *it) EINA_ARG_NONNULL(1);
- EAPI Elm_Naviframe_Item *elm_naviframe_top_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Elm_Naviframe_Item *elm_naviframe_bottom_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_naviframe_item_button_set(Elm_Naviframe_Item *it, Evas_Object *btn, Elm_Naviframe_Button_Type btn_type) EINA_ARG_NONNULL(1);
- EAPI Evas_Object *elm_naviframe_item_button_get(const Elm_Naviframe_Item *it, Elm_Naviframe_Button_Type btn_type) EINA_ARG_NONNULL(1);
- EAPI void elm_naviframe_item_icon_set(Elm_Naviframe_Item *it, Evas_Object *icon) EINA_ARG_NONNULL(1);
- EAPI Evas_Object *elm_naviframe_item_icon_get(const Elm_Naviframe_Item *it) EINA_ARG_NONNULL(1);
- EAPI void elm_naviframe_item_style_set(Elm_Naviframe_Item *it, const char *item_style) EINA_ARG_NONNULL(1);
- EAPI const char *elm_naviframe_item_style_get(const Elm_Naviframe_Item *it) EINA_ARG_NONNULL(1);
- EAPI void elm_naviframe_item_title_visible_set(Elm_Naviframe_Item *it, Eina_Bool visible) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_naviframe_item_title_visible_get(const Elm_Naviframe_Item *it) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get a top item on the naviframe stack
+ *
+ * @param obj The naviframe object
+ * @return The top item on the naviframe stack or @c NULL, if the stack is
+ * empty
+ */
+ EAPI Elm_Object_Item *elm_naviframe_top_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get a bottom item on the naviframe stack
+ *
+ * @param obj The naviframe object
+ * @return The bottom item on the naviframe stack or @c NULL, if the stack is
+ * empty
+ */
+ EAPI Elm_Object_Item *elm_naviframe_bottom_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set an item style
+ *
+ * @param obj The naviframe item
+ * @param item_style The current item style name. @c NULL would be default
+ *
+ * The following styles are available for this item:
+ * @li @c "default"
+ *
+ * @see also elm_naviframe_item_style_get()
+ */
+ EAPI void elm_naviframe_item_style_set(Elm_Object_Item *it, const char *item_style) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get an item style
+ *
+ * @param obj The naviframe item
+ * @return The current item style name
+ *
+ * @see also elm_naviframe_item_style_set()
+ */
+ EAPI const char *elm_naviframe_item_style_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Show/Hide the title area
+ *
+ * @param it The naviframe item
+ * @param visible If @c EINA_TRUE, title area will be visible, hidden
+ * otherwise
+ *
+ * When the title area is invisible, then the controls would be hidden so as * to expand the content area to full-size.
+ *
+ * @see also elm_naviframe_item_title_visible_get()
+ */
+ EAPI void elm_naviframe_item_title_visible_set(Elm_Object_Item *it, Eina_Bool visible) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get a value whether title area is visible or not.
+ *
+ * @param it The naviframe item
+ * @return If @c EINA_TRUE, title area is visible
+ *
+ * @see also elm_naviframe_item_title_visible_set()
+ */
+ EAPI Eina_Bool elm_naviframe_item_title_visible_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+
+ /**
+ * @}
+ */
#ifdef __cplusplus
}
projects / framework / uifw / elementary.git / blobdiff