* @}
*/
- /* pager */
+ /**
+ * @defgroup Pager Pager
+ *
+ * @image html img/widget/pager/preview-00.png
+ * @image latex img/widget/pager/preview-00.eps
+ *
+ * @brief Widget that allows flipping between 1 or more “pages” of objects.
+ *
+ * The flipping between “pages” of objects is animated. All content in pager
+ * is kept in a stack, the last content to be added will be on the top of the
+ * stack(be visible).
+ *
+ * Objects can be pushed or popped from the stack or deleted as normal.
+ * Pushes and pops will animate (and a pop will delete the object once the
+ * animation is finished). Any object already in the pager can be promoted to
+ * the top(from its current stacking position) through the use of
+ * elm_pager_content_promote(). Objects are pushed to the top with
+ * elm_pager_content_push() and when the top item is no longer wanted, simply
+ * pop it with elm_pager_content_pop() and it will also be deleted. If an
+ * object is no longer needed and is not the top item, just delete it as
+ * normal. You can query which objects are the top and bottom with
+ * elm_pager_content_bottom_get() and elm_pager_content_top_get().
+ *
+ * Signals that you can add callbacks for are:
+ * "hide,finished" - when the previous page is hided
+ *
+ * This widget has the following styles available:
+ * @li default
+ * @li fade
+ * @li fade_translucide
+ * @li fade_invisible
+ * @note This styles affect only the flipping animations, the appearance when
+ * not animating is unaffected by styles.
+ *
+ * @ref tutorial_pager gives a good overview of the usage of the API.
+ * @{
+ */
+ /**
+ * Add a new pager to the parent
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ *
+ * @ingroup Pager
+ */
EAPI Evas_Object *elm_pager_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Push an object to the top of the pager stack (and show it).
+ *
+ * @param obj The pager object
+ * @param content The object to push
+ *
+ * The object pushed becomes a child of the pager, it will be controlled and
+ * deleted when the pager is deleted.
+ *
+ * @note If the content is already in the stack use
+ * elm_pager_content_promote().
+ * @warning Using this function on @p content already in the stack results in
+ * undefined behavior.
+ */
EAPI void elm_pager_content_push(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Pop the object that is on top of the stack
+ *
+ * @param obj The pager object
+ *
+ * This pops the object that is on the top(visible) of the pager, makes it
+ * disappear, then deletes the object. The object that was underneath it on
+ * the stack will become visible.
+ */
EAPI void elm_pager_content_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Moves an object already in the pager stack to the top of the stack.
+ *
+ * @param obj The pager object
+ * @param content The object to promote
+ *
+ * This will take the @p content and move it to the top of the stack as
+ * if it had been pushed there.
+ *
+ * @note If the content isn't already in the stack use
+ * elm_pager_content_push().
+ * @warning Using this function on @p content not already in the stack
+ * results in undefined behavior.
+ */
EAPI void elm_pager_content_promote(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Return the object at the bottom of the pager stack
+ *
+ * @param obj The pager object
+ * @return The bottom object or NULL if none
+ */
EAPI Evas_Object *elm_pager_content_bottom_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Return the object at the top of the pager stack
+ *
+ * @param obj The pager object
+ * @return The top object or NULL if none
+ */
EAPI Evas_Object *elm_pager_content_top_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
EAPI void elm_pager_to_content_pop(Evas_Object *obj, Evas_Object *content); EINA_ARG_NONNULL(1);
EAPI void elm_pager_animation_disabled_set(Evas_Object *obj, Eina_Bool disable); EINA_ARG_NONNULL(1);
- /* available item styles:
- * default
- * fade
- * fade_translucide
- * fade_invisible
+ /**
+ * @}
*/
- /* smart callbacks called:
- * "hide,finished" - when the previous page is hided
+
+ /**
+ * @defgroup Slideshow Slideshow
+ *
+ * @image html img/widget/slideshow/preview-00.png
+ * @image latex img/widget/slideshow/preview-00.eps
+ *
+ * This widget, as the name indicates, is a pre-made image
+ * slideshow panel, with API functions acting on (child) image
+ * items presentation. Between those actions, are:
+ * - advance to next/previous image
+ * - select the style of image transition animation
+ * - set the exhibition time for each image
+ * - start/stop the slideshow
+ *
+ * The transition animations are defined in the widget's theme,
+ * consequently new animations can be added without having to
+ * update the widget's code.
+ *
+ * @section Slideshow_Items Slideshow items
+ *
+ * For slideshow items, just like for @ref Genlist "genlist" ones,
+ * the user defines a @b classes, specifying functions that will be
+ * called on the item's creation and deletion times.
+ *
+ * The #Elm_Slideshow_Item_Class structure contains the following
+ * members:
+ *
+ * - @c func.get - When an item is displayed, this function is
+ * called, and it's where one should create the item object, de
+ * facto. For example, the object can be a pure Evas image object
+ * or an Elementary @ref Photocam "photocam" widget. See
+ * #SlideshowItemGetFunc.
+ * - @c func.del - When an item is no more displayed, this function
+ * is called, where the user must delete any data associated to
+ * the item. See #SlideshowItemDelFunc.
+ *
+ * @section Slideshow_Caching Slideshow caching
+ *
+ * The slideshow provides facilities to have items adjacent to the
+ * one being displayed <b>already "realized"</b> (i.e. loaded) for
+ * you, so that the system does not have to decode image data
+ * anymore at the time it has to actually switch images on its
+ * viewport. The user is able to set the numbers of items to be
+ * cached @b before and @b after the current item, in the widget's
+ * item list.
+ *
+ * Smart events one can add callbacks for are:
+ *
+ * - @c "changed" - when the slideshow switches its view to a new
+ * item
+ *
+ * List of examples for the slideshow widget:
+ * @li @ref slideshow_example
+ */
+
+ /**
+ * @addtogroup Slideshow
+ * @{
*/
- typedef struct _Elm_Slideshow_Item_Class Elm_Slideshow_Item_Class;
- typedef struct _Elm_Slideshow_Item_Class_Func Elm_Slideshow_Item_Class_Func;
- typedef struct _Elm_Slideshow_Item Elm_Slideshow_Item; /**< Item of Elm_Slideshow. Sub-type of Elm_Widget_Item */
- typedef Evas_Object *(*SlideshowItemGetFunc) (void *data, Evas_Object *obj);
- typedef void (*SlideshowItemDelFunc) (void *data, Evas_Object *obj);
+ typedef struct _Elm_Slideshow_Item_Class Elm_Slideshow_Item_Class; /**< Slideshow item class definition struct */
+ typedef struct _Elm_Slideshow_Item_Class_Func Elm_Slideshow_Item_Class_Func; /**< Class functions for slideshow item classes. */
+ typedef struct _Elm_Slideshow_Item Elm_Slideshow_Item; /**< Slideshow item handle */
+ typedef Evas_Object *(*SlideshowItemGetFunc) (void *data, Evas_Object *obj); /**< Image fetching class function for slideshow item classes. */
+ typedef void (*SlideshowItemDelFunc) (void *data, Evas_Object *obj); /**< Deletion class function for slideshow item classes. */
+ /**
+ * @struct _Elm_Slideshow_Item_Class
+ *
+ * Slideshow item class definition. See @ref Slideshow_Items for
+ * field details.
+ */
struct _Elm_Slideshow_Item_Class
{
struct _Elm_Slideshow_Item_Class_Func
SlideshowItemGetFunc get;
SlideshowItemDelFunc del;
} func;
- };
+ }; /**< #Elm_Slideshow_Item_Class member definitions */
+ /**
+ * Add a new slideshow widget to the given parent Elementary
+ * (container) object
+ *
+ * @param parent The parent object
+ * @return A new slideshow widget handle or @c NULL, on errors
+ *
+ * This function inserts a new slideshow widget on the canvas.
+ *
+ * @ingroup Slideshow
+ */
EAPI Evas_Object *elm_slideshow_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Add (append) a new item in a given slideshow widget.
+ *
+ * @param obj The slideshow object
+ * @param itc The item class for the item
+ * @param data The item's data
+ * @return A handle to the item added or @c NULL, on errors
+ *
+ * Add a new item to @p obj's internal list of items, appending it.
+ * The item's class must contain the function really fetching the
+ * image object to show for this item, which could be an Evas image
+ * object or an Elementary photo, for example. The @p data
+ * parameter is going to be passed to both class functions of the
+ * item.
+ *
+ * @see #Elm_Slideshow_Item_Class
+ * @see elm_slideshow_item_sorted_insert()
+ *
+ * @ingroup Slideshow
+ */
EAPI Elm_Slideshow_Item *elm_slideshow_item_add(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data) EINA_ARG_NONNULL(1);
+
+ /**
+ * Insert a new item into the given slideshow widget, using the @p func
+ * function to sort items (by item handles).
+ *
+ * @param obj The slideshow object
+ * @param itc The item class for the item
+ * @param data The item's data
+ * @param func The comparing function to be used to sort slideshow
+ * items <b>by #Elm_Slideshow_Item item handles</b>
+ * @return Returns The slideshow item handle, on success, or
+ * @c NULL, on errors
+ *
+ * Add a new item to @p obj's internal list of items, in a position
+ * determined by the @p func comparing function. The item's class
+ * must contain the function really fetching the image object to
+ * show for this item, which could be an Evas image object or an
+ * Elementary photo, for example. The @p data parameter is going to
+ * be passed to both class functions of the item.
+ *
+ * @see #Elm_Slideshow_Item_Class
+ * @see elm_slideshow_item_add()
+ *
+ * @ingroup Slideshow
+ */
EAPI Elm_Slideshow_Item *elm_slideshow_item_sorted_insert(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data, Eina_Compare_Cb func) EINA_ARG_NONNULL(1);
+
+ /**
+ * Display a given slideshow widget's item, programmatically.
+ *
+ * @param obj The slideshow object
+ * @param item The item to display on @p obj's viewport
+ *
+ * The change between the current item and @p item will use the
+ * transition @p obj is set to use (@see
+ * elm_slideshow_transition_set()).
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_show(Elm_Slideshow_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Slide to the @b next item, in a given slideshow widget
+ *
+ * @param obj The slideshow object
+ *
+ * The sliding animation @p obj is set to use will be the
+ * transition effect used, after this call is issued.
+ *
+ * @note If the end of the slideshow's internal list of items is
+ * reached, it'll wrap around to the list's beginning, again.
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_next(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Slide to the @b previous item, in a given slideshow widget
+ *
+ * @param obj The slideshow object
+ *
+ * The sliding animation @p obj is set to use will be the
+ * transition effect used, after this call is issued.
+ *
+ * @note If the beginning of the slideshow's internal list of items
+ * is reached, it'll wrap around to the list's end, again.
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_previous(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Returns the list of sliding transition/effect names available, for a
+ * given slideshow widget.
+ *
+ * @param obj The slideshow object
+ * @return The list of transitions (list of @b stringshared strings
+ * as data)
+ *
+ * The transitions, which come from @p obj's theme, must be an EDC
+ * data item named @c "transitions" on the theme file, with (prefix)
+ * names of EDC programs actually implementing them.
+ *
+ * The available transitions for slideshows on the default theme are:
+ * - @c "fade" - the current item fades out, while the new one
+ * fades in to the slideshow's viewport.
+ * - @c "black_fade" - the current item fades to black, and just
+ * then, the new item will fade in.
+ * - @c "horizontal" - the current item slides horizontally, until
+ * it gets out of the slideshow's viewport, while the new item
+ * comes from the left to take its place.
+ * - @c "vertical" - the current item slides vertically, until it
+ * gets out of the slideshow's viewport, while the new item comes
+ * from the bottom to take its place.
+ * - @c "square" - the new item starts to appear from the middle of
+ * the current one, but with a tiny size, growing until its
+ * target (full) size and covering the old one.
+ *
+ * @warning The stringshared strings get no new references
+ * exclusive to the user grabbing the list, here, so if you'd like
+ * to use them out of this call's context, you'd better @c
+ * eina_stringshare_ref() them.
+ *
+ * @see elm_slideshow_transition_set()
+ *
+ * @ingroup Slideshow
+ */
EAPI const Eina_List *elm_slideshow_transitions_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the current slide transition/effect in use for a given
+ * slideshow widget
+ *
+ * @param obj The slideshow object
+ * @param transition The new transition's name string
+ *
+ * If @p transition is implemented in @p obj's theme (i.e., is
+ * contained in the list returned by
+ * elm_slideshow_transitions_get()), this new sliding effect will
+ * be used on the widget.
+ *
+ * @see elm_slideshow_transitions_get() for more details
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_transition_set(Evas_Object *obj, const char *transition) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the current slide transition/effect in use for a given
+ * slideshow widget
+ *
+ * @param obj The slideshow object
+ * @return The current transition's name
+ *
+ * @see elm_slideshow_transition_set() for more details
+ *
+ * @ingroup Slideshow
+ */
EAPI const char *elm_slideshow_transition_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the interval between each image transition on a given
+ * slideshow widget, <b>and start the slideshow, itself</b>
+ *
+ * @param obj The slideshow object
+ * @param timeout The new displaying timeout for images
+ *
+ * After this call, the slideshow widget will start cycling its
+ * view, sequentially and automatically, with the images of the
+ * items it has. The time between each new image displayed is going
+ * to be @p timeout, in @b seconds. If a different timeout was set
+ * previously and an slideshow was in progress, it will continue
+ * with the new time between transitions, after this call.
+ *
+ * @note A value less than or equal to 0 on @p timeout will disable
+ * the widget's internal timer, thus halting any slideshow which
+ * could be happening on @p obj.
+ *
+ * @see elm_slideshow_timeout_get()
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the interval set for image transitions on a given slideshow
+ * widget.
+ *
+ * @param obj The slideshow object
+ * @return Returns the timeout set on it
+ *
+ * @see elm_slideshow_timeout_set() for more details
+ *
+ * @ingroup Slideshow
+ */
EAPI double elm_slideshow_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set if, after a slideshow is started, for a given slideshow
+ * widget, its items should be displayed cyclically or not.
+ *
+ * @param obj The slideshow object
+ * @param loop Use @c EINA_TRUE to make it cycle through items or
+ * @c EINA_FALSE for it to stop at the end of @p obj's internal
+ * list of items
+ *
+ * @note elm_slideshow_next() and elm_slideshow_previous() will @b
+ * ignore what is set by this functions, i.e., they'll @b always
+ * cycle through items. This affects only the "automatic"
+ * slideshow, as set by elm_slideshow_timeout_set().
+ *
+ * @see elm_slideshow_loop_get()
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_loop_set(Evas_Object *obj, Eina_Bool loop) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get if, after a slideshow is started, for a given slideshow
+ * widget, its items are to be displayed cyclically or not.
+ *
+ * @param obj The slideshow object
+ * @return @c EINA_TRUE, if the items in @p obj will be cycled
+ * through or @c EINA_FALSE, otherwise
+ *
+ * @see elm_slideshow_loop_set() for more details
+ *
+ * @ingroup Slideshow
+ */
EAPI Eina_Bool elm_slideshow_loop_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Remove all items from a given slideshow widget
+ *
+ * @param obj The slideshow object
+ *
+ * This removes (and deletes) all items in @p obj, leaving it
+ * empty.
+ *
+ * @see elm_slideshow_item_del(), to remove just one item.
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the internal list of items in a given slideshow widget.
+ *
+ * @param obj The slideshow object
+ * @return The list of items (#Elm_Slideshow_Item as data) or
+ * @c NULL on errors.
+ *
+ * This list is @b not to be modified in any way and must not be
+ * freed. Use the list members with functions like
+ * elm_slideshow_item_del(), elm_slideshow_item_data_get().
+ *
+ * @warning This list is only valid until @p obj object's internal
+ * items list is changed. It should be fetched again with another
+ * call to this function when changes happen.
+ *
+ * @ingroup Slideshow
+ */
EAPI const Eina_List *elm_slideshow_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Delete a given item from a slideshow widget.
+ *
+ * @param item The slideshow item
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_item_del(Elm_Slideshow_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Return the data associated with a given slideshow item
+ *
+ * @param item The slideshow item
+ * @return Returns the data associated to this item
+ *
+ * @ingroup Slideshow
+ */
EAPI void *elm_slideshow_item_data_get(const Elm_Slideshow_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Returns the currently displayed item, in a given slideshow widget
+ *
+ * @param obj The slideshow object
+ * @return A handle to the item being displayed in @p obj or
+ * @c NULL, if none is (and on errors)
+ *
+ * @ingroup Slideshow
+ */
EAPI Elm_Slideshow_Item *elm_slideshow_item_current_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the real Evas object created to implement the view of a
+ * given slideshow item
+ *
+ * @param item The slideshow item.
+ * @return the Evas object implementing this item's view.
+ *
+ * This returns the actual Evas object used to implement the
+ * specified slideshow 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 slideshow. <b>Do not modify this object</b> (move, resize,
+ * show, hide, etc.), as the slideshow 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_slideshow_item_data_get()
+ *
+ * @ingroup Slideshow
+ */
EAPI Evas_Object* elm_slideshow_item_object_get(const Elm_Slideshow_Item* item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the the item, in a given slideshow widget, placed at
+ * position @p nth, in its internal items list
+ *
+ * @param obj The slideshow object
+ * @param nth The number of the item to grab a handle to (0 being
+ * the first)
+ * @return The item stored in @p obj at position @p nth or @c NULL,
+ * if there's no item with that index (and on errors)
+ *
+ * @ingroup Slideshow
+ */
EAPI Elm_Slideshow_Item *elm_slideshow_item_nth_get(const Evas_Object *obj, unsigned int nth) EINA_ARG_NONNULL(1);
- EAPI const char *elm_slideshow_layout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the current slide layout in use for a given slideshow widget
+ *
+ * @param obj The slideshow object
+ * @param layout The new layout's name string
+ *
+ * If @p layout is implemented in @p obj's theme (i.e., is contained
+ * in the list returned by elm_slideshow_layouts_get()), this new
+ * images layout will be used on the widget.
+ *
+ * @see elm_slideshow_layouts_get() for more details
+ *
+ * @ingroup Slideshow
+ */
EAPI void elm_slideshow_layout_set(Evas_Object *obj, const char *layout) EINA_ARG_NONNULL(1);
- EAPI const Eina_List *elm_slideshow_layouts_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_slideshow_cache_before_set(Evas_Object *obj, int count) EINA_ARG_NONNULL(1);
- EAPI int elm_slideshow_cache_before_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_slideshow_cache_after_set(Evas_Object *obj, int count) EINA_ARG_NONNULL(1);
- EAPI int elm_slideshow_cache_after_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI unsigned int elm_slideshow_count_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "changed" - when the slideshow switch to another item
+
+ /**
+ * Get the current slide layout in use for a given slideshow widget
+ *
+ * @param obj The slideshow object
+ * @return The current layout's name
+ *
+ * @see elm_slideshow_layout_set() for more details
+ *
+ * @ingroup Slideshow
*/
+ EAPI const char *elm_slideshow_layout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* file selector */
- typedef enum _Elm_Fileselector_Mode
- {
- ELM_FILESELECTOR_LIST = 0,
- ELM_FILESELECTOR_GRID,
- ELM_FILESELECTOR_LAST
- } Elm_Fileselector_Mode;
+ /**
+ * Returns the list of @b layout names available, for a given
+ * slideshow widget.
+ *
+ * @param obj The slideshow object
+ * @return The list of layouts (list of @b stringshared strings
+ * as data)
+ *
+ * Slideshow layouts will change how the widget is to dispose each
+ * image item in its viewport, with regard to cropping, scaling,
+ * etc.
+ *
+ * The layouts, which come from @p obj's theme, must be an EDC
+ * data item name @c "layouts" on the theme file, with (prefix)
+ * names of EDC programs actually implementing them.
+ *
+ * The available layouts for slideshows on the default theme are:
+ * - @c "fullscreen" - item images with original aspect, scaled to
+ * touch top and down slideshow borders or, if the image's heigh
+ * is not enough, left and right slideshow borders.
+ * - @c "not_fullscreen" - the same behavior as the @c "fullscreen"
+ * one, but always leaving 10% of the slideshow's dimensions of
+ * distance between the item image's borders and the slideshow
+ * borders, for each axis.
+ *
+ * @warning The stringshared strings get no new references
+ * exclusive to the user grabbing the list, here, so if you'd like
+ * to use them out of this call's context, you'd better @c
+ * eina_stringshare_ref() them.
+ *
+ * @see elm_slideshow_layout_set()
+ *
+ * @ingroup Slideshow
+ */
+ EAPI const Eina_List *elm_slideshow_layouts_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Evas_Object *elm_fileselector_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
- EAPI void elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_fileselector_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only) EINA_ARG_NONNULL(1);
+ /**
+ * Set the number of items to cache, on a given slideshow widget,
+ * <b>before the current item</b>
+ *
+ * @param obj The slideshow object
+ * @param count Number of items to cache before the current one
+ *
+ * The default value for this property is @c 2. See
+ * @ref Slideshow_Caching "slideshow caching" for more details.
+ *
+ * @see elm_slideshow_cache_before_get()
+ *
+ * @ingroup Slideshow
+ */
+ EAPI void elm_slideshow_cache_before_set(Evas_Object *obj, int count) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the number of items to cache, on a given slideshow widget,
+ * <b>before the current item</b>
+ *
+ * @param obj The slideshow object
+ * @return The number of items set to be cached before the current one
+ *
+ * @see elm_slideshow_cache_before_set() for more details
+ *
+ * @ingroup Slideshow
+ */
+ EAPI int elm_slideshow_cache_before_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the number of items to cache, on a given slideshow widget,
+ * <b>after the current item</b>
+ *
+ * @param obj The slideshow object
+ * @param count Number of items to cache after the current one
+ *
+ * The default value for this property is @c 2. See
+ * @ref Slideshow_Caching "slideshow caching" for more details.
+ *
+ * @see elm_slideshow_cache_after_get()
+ *
+ * @ingroup Slideshow
+ */
+ EAPI void elm_slideshow_cache_after_set(Evas_Object *obj, int count) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the number of items to cache, on a given slideshow widget,
+ * <b>after the current item</b>
+ *
+ * @param obj The slideshow object
+ * @return The number of items set to be cached after the current one
+ *
+ * @see elm_slideshow_cache_after_set() for more details
+ *
+ * @ingroup Slideshow
+ */
+ EAPI int elm_slideshow_cache_after_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the number of items stored in a given slideshow widget
+ *
+ * @param obj The slideshow object
+ * @return The number of items on @p obj, at the moment of this call
+ *
+ * @ingroup Slideshow
+ */
+ EAPI unsigned int elm_slideshow_count_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Fileselector File Selector
+ *
+ * @image html img/widget/fileselector/preview-00.png
+ * @image latex img/widget/fileselector/preview-00.eps
+ *
+ * A file selector is a widget that allows a user to navigate
+ * through a file system, reporting file selections back via its
+ * API.
+ *
+ * It contains shortcut buttons for home directory (@c ~) and to
+ * jump one directory upwards (..), as well as cancel/ok buttons to
+ * confirm/cancel a given selection. After either one of those two
+ * former actions, the file selector will issue its @c "done" smart
+ * callback.
+ *
+ * There's a text entry on it, too, showing the name of the current
+ * selection. There's the possibility of making it editable, so it
+ * is useful on file saving dialogs on applications, where one
+ * gives a file name to save contents to, in a given directory in
+ * the system. This custom file name will be reported on the @c
+ * "done" smart callback (explained in sequence).
+ *
+ * Finally, it has a view to display file system items into in two
+ * possible forms:
+ * - list
+ * - grid
+ *
+ * If Elementary is built with support of the Ethumb thumbnailing
+ * library, the second form of view will display preview thumbnails
+ * of files which it supports.
+ *
+ * Smart callbacks one can register to:
+ *
+ * - @c "selected" - the user has clicked on a file (when not in
+ * folders-only mode) or directory (when in folders-only mode)
+ * - @c "directory,open" - the list has been populated with new
+ * content (@c event_info is a pointer to the directory's
+ * path, a @b stringshared string)
+ * - @c "done" - the user has clicked on the "ok" or "cancel"
+ * buttons (@c event_info is a pointer to the selection's
+ * path, a @b stringshared string)
+ *
+ * Here is an example on its usage:
+ * @li @ref fileselector_example
+ */
+
+ /**
+ * @addtogroup Fileselector
+ * @{
+ */
+
+ /**
+ * Defines how a file selector widget is to layout its contents
+ * (file system entries).
+ */
+ typedef enum _Elm_Fileselector_Mode
+ {
+ ELM_FILESELECTOR_LIST = 0, /**< layout as a list */
+ ELM_FILESELECTOR_GRID, /**< layout as a grid */
+ ELM_FILESELECTOR_LAST /**< sentinel (helper) value, not used */
+ } Elm_Fileselector_Mode;
+
+ /**
+ * Add a new file selector widget to the given parent Elementary
+ * (container) object
+ *
+ * @param parent The parent object
+ * @return a new file selector widget handle or @c NULL, on errors
+ *
+ * This function inserts a new file selector widget on the canvas.
+ *
+ * @ingroup Fileselector
+ */
+ EAPI Evas_Object *elm_fileselector_add(Evas_Object *parent) 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 widget
+ *
+ * @param obj The file selector object
+ * @param is_save @c EINA_TRUE to make the file selector a "saving
+ * dialog", @c EINA_FALSE otherwise
+ *
+ * Having the entry editable is useful on file saving dialogs on
+ * applications, where one gives a file name to save contents to,
+ * in a given directory in the system. This custom file name will
+ * be reported on the @c "done" smart callback.
+ *
+ * @see elm_fileselector_is_save_get()
+ *
+ * @ingroup Fileselector
+ */
+ EAPI void elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether the given file selector is in "saving dialog" mode
+ *
+ * @param obj The file selector object
+ * @return @c EINA_TRUE, if the file selector is in "saving dialog"
+ * mode, @c EINA_FALSE otherwise (and on errors)
+ *
+ * @see elm_fileselector_is_save_set() for more details
+ *
+ * @ingroup Fileselector
+ */
+ EAPI Eina_Bool elm_fileselector_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable/disable folder-only view for a given file selector widget
+ *
+ * @param obj The file selector object
+ * @param only @c EINA_TRUE to make @p obj only display
+ * directories, @c EINA_FALSE to make files to be displayed in it
+ * too
+ *
+ * If enabled, the widget's view will only display folder items,
+ * naturally.
+ *
+ * @see elm_fileselector_folder_only_get()
+ *
+ * @ingroup Fileselector
+ */
+ EAPI void elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether folder-only view is set for a given file selector
+ * widget
+ *
+ * @param obj The file selector object
+ * @return only @c EINA_TRUE if @p obj is only displaying
+ * directories, @c EINA_FALSE if files are being displayed in it
+ * too (and on errors)
+ *
+ * @see elm_fileselector_folder_only_get()
+ *
+ * @ingroup Fileselector
+ */
EAPI Eina_Bool elm_fileselector_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable/disable the "ok" and "cancel" buttons on a given file
+ * selector widget
+ *
+ * @param obj The file selector object
+ * @param only @c EINA_TRUE to show them, @c EINA_FALSE to hide.
+ *
+ * @note A file selector without those buttons will never emit the
+ * @c "done" smart event, and is only usable if one is just hooking
+ * to the other two events.
+ *
+ * @see elm_fileselector_buttons_ok_cancel_get()
+ *
+ * @ingroup Fileselector
+ */
EAPI void elm_fileselector_buttons_ok_cancel_set(Evas_Object *obj, Eina_Bool buttons) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether the "ok" and "cancel" buttons on a given file
+ * selector widget are being shown.
+ *
+ * @param obj The file selector object
+ * @return @c EINA_TRUE if they are being shown, @c EINA_FALSE
+ * otherwise (and on errors)
+ *
+ * @see elm_fileselector_buttons_ok_cancel_set() for more details
+ *
+ * @ingroup Fileselector
+ */
EAPI Eina_Bool elm_fileselector_buttons_ok_cancel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_fileselector_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Enable/disable a tree view in the given file selector widget,
+ * <b>if it's in @c #ELM_FILESELECTOR_LIST mode</b>
+ *
+ * @param obj The file selector object
+ * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
+ * disable
+ *
+ * In a tree view, arrows are created on the sides of directories,
+ * allowing them to expand in place.
+ *
+ * @note If it's in other mode, the changes made by this function
+ * will only be visible when one switches back to "list" mode.
+ *
+ * @see elm_fileselector_expandable_get()
+ *
+ * @ingroup Fileselector
+ */
EAPI void elm_fileselector_expandable_set(Evas_Object *obj, Eina_Bool expand) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether tree view is enabled for the given file selector
+ * widget
+ *
+ * @param obj The file selector object
+ * @return @c EINA_TRUE if @p obj is in tree view, @c EINA_FALSE
+ * otherwise (and or errors)
+ *
+ * @see elm_fileselector_expandable_set() for more details
+ *
+ * @ingroup Fileselector
+ */
+ EAPI Eina_Bool elm_fileselector_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set, programmatically, the @b directory that a given file
+ * selector widget will display contents from
+ *
+ * @param obj The file selector object
+ * @param path The path to display in @p obj
+ *
+ * This will change the @b directory that @p obj is displaying. It
+ * will also clear the text entry area on the @p obj object, which
+ * displays select files' names.
+ *
+ * @see elm_fileselector_path_get()
+ *
+ * @ingroup Fileselector
+ */
EAPI void elm_fileselector_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the parent directory's path that a given file selector
+ * widget is displaying
+ *
+ * @param obj The file selector object
+ * @return The (full) path of the directory the file selector is
+ * displaying, a @b stringshared string
+ *
+ * @see elm_fileselector_path_set()
+ *
+ * @ingroup Fileselector
+ */
EAPI const char *elm_fileselector_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI const char *elm_fileselector_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set, programmatically, the currently selected file/directory in
+ * the given file selector widget
+ *
+ * @param obj The file selector object
+ * @param path The (full) path to a file or directory
+ * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. The
+ * latter case occurs if the directory or file pointed to do not
+ * exist.
+ *
+ * @see elm_fileselector_selected_get()
+ *
+ * @ingroup Fileselector
+ */
EAPI Eina_Bool elm_fileselector_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the currently selected item's (full) path, in the given file
+ * selector widget
+ *
+ * @param obj The file selector object
+ * @return The absolute path of the selected item, a @b
+ * stringshared string
+ *
+ * @note Custom editions on @p obj object's text entry, if made,
+ * will appear on the return string of this function, naturally.
+ *
+ * @see elm_fileselector_selected_set() for more details
+ *
+ * @ingroup Fileselector
+ */
+ EAPI const char *elm_fileselector_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the mode in which a given file selector widget will display
+ * (layout) file system entries in its view
+ *
+ * @param obj The file selector object
+ * @param mode The mode of the fileselector, being it one of
+ * #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The
+ * first one, naturally, will display the files in a list. The
+ * latter will make the widget to display its entries in a grid
+ * form.
+ *
+ * @note By using elm_fileselector_expandable_set(), the user may
+ * trigger a tree view for that list.
+ *
+ * @note If Elementary is built with support of the Ethumb
+ * thumbnailing library, the second form of view will display
+ * preview thumbnails of files which it supports. You must have
+ * elm_need_ethumb() called in your Elementary for thumbnailing to
+ * work, though.
+ *
+ * @see elm_fileselector_expandable_set().
+ * @see elm_fileselector_mode_get().
+ *
+ * @ingroup Fileselector
+ */
EAPI void elm_fileselector_mode_set(Evas_Object *obj, Elm_Fileselector_Mode mode) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the mode in which a given file selector widget is displaying
+ * (layouting) file system entries in its view
+ *
+ * @param obj The fileselector object
+ * @return The mode in which the fileselector is at
+ *
+ * @see elm_fileselector_mode_set() for more details
+ *
+ * @ingroup Fileselector
+ */
EAPI Elm_Fileselector_Mode elm_fileselector_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "selected" - the user click on a file
- * "directory,open" - the list is populate with a new content. event_info is a directory.
- * "done" - the user click on the ok or cancel buttons
+
+ /**
+ * @}
*/
- /* progressbar */
+ /**
+ * @defgroup Progressbar Progress bar
+ *
+ * The progress bar is a widget for visually representing the
+ * progress status of a given job/task.
+ *
+ * A progress bar may be horizontal or vertical. It may display an
+ * icon besides it, as well as primary and @b units labels. The
+ * former is meant to label the widget as a whole, while the
+ * latter, which is formatted with floating point values (and thus
+ * accepts a <c>printf</c>-style format string, like <c>"%1.2f
+ * units"</c>), is meant to label the widget's <b>progress
+ * value</b>. Label, icon and unit strings/objects are @b optional
+ * for progress bars.
+ *
+ * A progress bar may be @b inverted, in which state it gets its
+ * values inverted, with high values being on the left or top and
+ * low values on the right or bottom, as opposed to normally have
+ * the low values on the former and high values on the latter,
+ * respectively, for horizontal and vertical modes.
+ *
+ * The @b span of the progress, as set by
+ * elm_progressbar_span_size_set(), is its length (horizontally or
+ * vertically), unless one puts size hints on the widget to expand
+ * on desired directions, by any container. That length will be
+ * scaled by the object or applications scaling factor. At any
+ * point code can query the progress bar for its value with
+ * elm_progressbar_value_get().
+ *
+ * Available widget styles for progress bars:
+ * - @c "default"
+ * - @c "wheel" (simple style, no text, no progression, only
+ * "pulse" effect is available)
+ *
+ * Default contents parts of the progressbar widget that you can use for are:
+ * @li "elm.swallow.content" - A icon of the progressbar
+ *
+ * Here is an example on its usage:
+ * @li @ref progressbar_example
+ */
+
+ /**
+ * Add a new progress bar widget to the given parent Elementary
+ * (container) object
+ *
+ * @param parent The parent object
+ * @return a new progress bar widget handle or @c NULL, on errors
+ *
+ * This function inserts a new progress bar widget on the canvas.
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Object *elm_progressbar_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given progress bar widget is at "pulsing mode" or
+ * not.
+ *
+ * @param obj The progress bar object
+ * @param pulse @c EINA_TRUE to put @p obj in pulsing mode,
+ * @c EINA_FALSE to put it back to its default one
+ *
+ * By default, progress bars will display values from the low to
+ * high value boundaries. There are, though, contexts in which the
+ * state of progression of a given task is @b unknown. For those,
+ * one can set a progress bar widget to a "pulsing state", to give
+ * the user an idea that some computation is being held, but
+ * without exact progress values. In the default theme it will
+ * animate its bar with the contents filling in constantly and back
+ * to non-filled, in a loop. To start and stop this pulsing
+ * animation, one has to explicitly call elm_progressbar_pulse().
+ *
+ * @see elm_progressbar_pulse_get()
+ * @see elm_progressbar_pulse()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_pulse_set(Evas_Object *obj, Eina_Bool pulse) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given progress bar widget is at "pulsing mode" or
+ * not.
+ *
+ * @param obj The progress bar object
+ * @return @c EINA_TRUE, if @p obj is in pulsing mode, @c EINA_FALSE
+ * if it's in the default one (and on errors)
+ *
+ * @ingroup Progressbar
+ */
EAPI Eina_Bool elm_progressbar_pulse_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Start/stop a given progress bar "pulsing" animation, if its
+ * under that mode
+ *
+ * @param obj The progress bar object
+ * @param state @c EINA_TRUE, to @b start the pulsing animation,
+ * @c EINA_FALSE to @b stop it
+ *
+ * @note This call won't do anything if @p obj is not under "pulsing mode".
+ *
+ * @see elm_progressbar_pulse_set() for more details.
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_pulse(Evas_Object *obj, Eina_Bool state) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the progress value (in percentage) on a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @param val The progress value (@b must be between @c 0.0 and @c
+ * 1.0)
+ *
+ * Use this call to set progress bar levels.
+ *
+ * @note If you passes a value out of the specified range for @p
+ * val, it will be interpreted as the @b closest of the @b boundary
+ * values in the range.
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the progress value (in percentage) on a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @return The value of the progressbar
+ *
+ * @see elm_progressbar_value_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI double elm_progressbar_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the label of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @param label The text label string, in UTF-8
+ *
+ * @ingroup Progressbar
+ * @deprecated use elm_object_text_set() instead.
+ */
EINA_DEPRECATED EAPI void elm_progressbar_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the label of a given progress bar widget
+ *
+ * @param obj The progressbar object
+ * @return The text label string, in UTF-8
+ *
+ * @ingroup Progressbar
+ * @deprecated use elm_object_text_set() instead.
+ */
EINA_DEPRECATED EAPI const char *elm_progressbar_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the icon object of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @param icon The icon object
+ *
+ * Use this call to decorate @p obj with an icon next to it.
+ *
+ * @note 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_progressbar_icon_unset() function.
+ *
+ * @see elm_progressbar_icon_get()
+ * @deprecated use elm_object_content_set() instead.
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the icon object set for a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @return The icon object's handle, if @p obj had one set, or @c NULL,
+ * otherwise (and on errors)
+ *
+ * @see elm_progressbar_icon_set() for more details
+ * @deprecated use elm_object_content_set() instead.
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Object *elm_progressbar_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Unset an icon set on a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @return The icon object that was being used, if any was set, or
+ * @c NULL, otherwise (and on errors)
+ *
+ * This call will unparent and return the icon object which was set
+ * for this widget, previously, on success.
+ *
+ * @see elm_progressbar_icon_set() for more details
+ * @deprecated use elm_object_content_unset() instead.
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Object *elm_progressbar_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the (exact) length of the bar region of a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @param size The length of the progress bar's bar region
+ *
+ * This sets the minimum width (when in horizontal mode) or height
+ * (when in vertical mode) of the actual bar area of the progress
+ * bar @p obj. This in turn affects the object's minimum size. Use
+ * this when you're not setting other size hints expanding on the
+ * given direction (like weight and alignment hints) and you would
+ * like it to have a specific size.
+ *
+ * @note Icon, label and unit text around @p obj will require their
+ * own space, which will make @p obj to require more the @p size,
+ * actually.
+ *
+ * @see elm_progressbar_span_size_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the length set for the bar region of a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @return The length of the progress bar's bar region
+ *
+ * If that size was not set previously, with
+ * elm_progressbar_span_size_set(), this call will return @c 0.
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Coord elm_progressbar_span_size_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the format string for a given progress bar widget's units
+ * label
+ *
+ * @param obj The progress bar object
+ * @param format The format string for @p obj's units label
+ *
+ * If @c NULL is passed on @p format, it will make @p obj's units
+ * area to be hidden completely. If not, it'll set the <b>format
+ * string</b> for the units label's @b text. The units label is
+ * provided a floating point value, so the units text is up display
+ * at most one floating point falue. Note that the units label is
+ * optional. Use a format string such as "%1.2f meters" for
+ * example.
+ *
+ * @note The default format string for a progress bar is an integer
+ * percentage, as in @c "%.0f %%".
+ *
+ * @see elm_progressbar_unit_format_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_unit_format_set(Evas_Object *obj, const char *format) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the format string set for a given progress bar widget's
+ * units label
+ *
+ * @param obj The progress bar object
+ * @return The format set string for @p obj's units label or
+ * @c NULL, if none was set (and on errors)
+ *
+ * @see elm_progressbar_unit_format_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI const char *elm_progressbar_unit_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the orientation of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @param horizontal Use @c EINA_TRUE to make @p obj to be
+ * @b horizontal, @c EINA_FALSE to make it @b vertical
+ *
+ * Use this function to change how your progress bar is to be
+ * disposed: vertically or horizontally.
+ *
+ * @see elm_progressbar_horizontal_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the orientation of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
+ * @c EINA_FALSE if it's @b vertical (and on errors)
+ *
+ * @see elm_progressbar_horizontal_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI Eina_Bool elm_progressbar_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Invert a given progress bar widget's displaying values order
+ *
+ * @param obj The progress bar object
+ * @param inverted Use @c EINA_TRUE to make @p obj inverted,
+ * @c EINA_FALSE to bring it back to default, non-inverted values.
+ *
+ * A progress bar may be @b inverted, in which state it gets its
+ * values inverted, with high values being on the left or top and
+ * low values on the right or bottom, as opposed to normally have
+ * the low values on the former and high values on the latter,
+ * respectively, for horizontal and vertical modes.
+ *
+ * @see elm_progressbar_inverted_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given progress bar widget's displaying values are
+ * inverted or not
+ *
+ * @param obj The progress bar object
+ * @return @c EINA_TRUE, if @p obj has inverted values,
+ * @c EINA_FALSE otherwise (and on errors)
+ *
+ * @see elm_progressbar_inverted_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI Eina_Bool elm_progressbar_inverted_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
+
+ /**
+ * @defgroup Separator Separator
+ *
+ * @brief Separator is a very thin object used to separate other objects.
+ *
+ * A separator can be vertical or horizontal.
+ *
+ * @ref tutorial_separator is a good example of how to use a separator.
+ * @{
*/
- /* available item styles:
- * default
- * wheel (simple style, no text, no progression, only pulse is available)
+ /**
+ * @brief Add a separator object to @p parent
+ *
+ * @param parent The parent object
+ *
+ * @return The separator object, or NULL upon failure
*/
-
- /* separator */
EAPI Evas_Object *elm_separator_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the horizontal mode of a separator object
+ *
+ * @param obj The separator object
+ * @param horizontal If true, the separator is horizontal
+ */
EAPI void elm_separator_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the horizontal mode of a separator object
+ *
+ * @param obj The separator object
+ * @return If true, the separator is horizontal
+ *
+ * @see elm_separator_horizontal_set()
+ */
EAPI Eina_Bool elm_separator_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
+ /**
+ * @}
+ */
+
+ /**
+ * @addtogroup Spinner
+ * @{
*/
- /* spinner */
+ /**
+ * Add a new spinner widget to the given parent Elementary
+ * (container) object.
+ *
+ * @param parent The parent object.
+ * @return a new spinner widget handle or @c NULL, on errors.
+ *
+ * This function inserts a new spinner widget on the canvas.
+ *
+ * @ingroup Spinner
+ *
+ */
EAPI Evas_Object *elm_spinner_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the format string of the displayed label.
+ *
+ * @param obj The spinner object.
+ * @param fmt The format string for the label display.
+ *
+ * If @c NULL, this sets the format to "%.0f". If not it sets the format
+ * string for the label text. The label text is provided a floating point
+ * value, so the label text can display up to 1 floating point value.
+ * Note that this is optional.
+ *
+ * Use a format string such as "%1.2f meters" for example, and it will
+ * display values like: "3.14 meters" for a value equal to 3.14159.
+ *
+ * Default is "%0.f".
+ *
+ * @see elm_spinner_label_format_get()
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the label format of the spinner.
+ *
+ * @param obj The spinner object.
+ * @return The text label format string in UTF-8.
+ *
+ * @see elm_spinner_label_format_set() for details.
+ *
+ * @ingroup Spinner
+ */
EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the minimum and maximum values for the spinner.
+ *
+ * @param obj The spinner object.
+ * @param min The minimum value.
+ * @param max The maximum value.
+ *
+ * Define the allowed range of values to be selected by the user.
+ *
+ * If actual value is less than @p min, it will be updated to @p min. If it
+ * is bigger then @p max, will be updated to @p max. Actual value can be
+ * get with elm_spinner_value_get().
+ *
+ * By default, min is equal to 0, and max is equal to 100.
+ *
+ * @warning Maximum must be greater than minimum.
+ *
+ * @see elm_spinner_min_max_get()
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the minimum and maximum values of the spinner.
+ *
+ * @param obj The spinner object.
+ * @param min Pointer where to store the minimum value.
+ * @param max Pointer where to store the maximum value.
+ *
+ * @note If only one value is needed, the other pointer can be passed
+ * as @c NULL.
+ *
+ * @see elm_spinner_min_max_set() for details.
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the step used to increment or decrement the spinner value.
+ *
+ * @param obj The spinner object.
+ * @param step The step value.
+ *
+ * This value will be incremented or decremented to the displayed value.
+ * It will be incremented while the user keep right or top arrow pressed,
+ * and will be decremented while the user keep left or bottom arrow pressed.
+ *
+ * The interval to increment / decrement can be set with
+ * elm_spinner_interval_set().
+ *
+ * By default step value is equal to 1.
+ *
+ * @see elm_spinner_step_get()
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_step_set(Evas_Object *obj, double step) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the step used to increment or decrement the spinner value.
+ *
+ * @param obj The spinner object.
+ * @return The step value.
+ *
+ * @see elm_spinner_step_get() for more details.
+ *
+ * @ingroup Spinner
+ */
EAPI double elm_spinner_step_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the value the spinner displays.
+ *
+ * @param obj The spinner object.
+ * @param val The value to be displayed.
+ *
+ * Value will be presented on the label following format specified with
+ * elm_spinner_format_set().
+ *
+ * @warning The value must to be between min and max values. This values
+ * are set by elm_spinner_min_max_set().
+ *
+ * @see elm_spinner_value_get().
+ * @see elm_spinner_format_set().
+ * @see elm_spinner_min_max_set().
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the value displayed by the spinner.
+ *
+ * @param obj The spinner object.
+ * @return The value displayed.
+ *
+ * @see elm_spinner_value_set() for details.
+ *
+ * @ingroup Spinner
+ */
EAPI double elm_spinner_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether the spinner should wrap when it reaches its
+ * minimum or maximum value.
+ *
+ * @param obj The spinner object.
+ * @param wrap @c EINA_TRUE to enable wrap or @c EINA_FALSE to
+ * disable it.
+ *
+ * Disabled by default. If disabled, when the user tries to increment the
+ * value,
+ * but displayed value plus step value is bigger than maximum value,
+ * the spinner
+ * won't allow it. The same happens when the user tries to decrement it,
+ * but the value less step is less than minimum value.
+ *
+ * When wrap is enabled, in such situations it will allow these changes,
+ * but will get the value that would be less than minimum and subtracts
+ * from maximum. Or add the value that would be more than maximum to
+ * the minimum.
+ *
+ * E.g.:
+ * @li min value = 10
+ * @li max value = 50
+ * @li step value = 20
+ * @li displayed value = 20
+ *
+ * When the user decrement value (using left or bottom arrow), it will
+ * displays @c 40, because max - (min - (displayed - step)) is
+ * @c 50 - (@c 10 - (@c 20 - @c 20)) = @c 40.
+ *
+ * @see elm_spinner_wrap_get().
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether the spinner should wrap when it reaches its
+ * minimum or maximum value.
+ *
+ * @param obj The spinner object
+ * @return @c EINA_TRUE means wrap is enabled. @c EINA_FALSE indicates
+ * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
+ *
+ * @see elm_spinner_wrap_set() for details.
+ *
+ * @ingroup Spinner
+ */
EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether the spinner can be directly edited by the user or not.
+ *
+ * @param obj The spinner object.
+ * @param editable @c EINA_TRUE to allow users to edit it or @c EINA_FALSE to
+ * don't allow users to edit it directly.
+ *
+ * Spinner objects can have edition @b disabled, in which state they will
+ * be changed only by arrows.
+ * Useful for contexts
+ * where you don't want your users to interact with it writting the value.
+ * Specially
+ * when using special values, the user can see real value instead
+ * of special label on edition.
+ *
+ * It's enabled by default.
+ *
+ * @see elm_spinner_editable_get()
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether the spinner can be directly edited by the user or not.
+ *
+ * @param obj The spinner object.
+ * @return @c EINA_TRUE means edition is enabled. @c EINA_FALSE indicates
+ * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
+ *
+ * @see elm_spinner_editable_set() for details.
+ *
+ * @ingroup Spinner
+ */
EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set a special string to display in the place of the numerical value.
+ *
+ * @param obj The spinner object.
+ * @param value The value to be replaced.
+ * @param label The label to be used.
+ *
+ * It's useful for cases when a user should select an item that is
+ * better indicated by a label than a value. For example, weekdays or months.
+ *
+ * E.g.:
+ * @code
+ * sp = elm_spinner_add(win);
+ * elm_spinner_min_max_set(sp, 1, 3);
+ * elm_spinner_special_value_add(sp, 1, "January");
+ * elm_spinner_special_value_add(sp, 2, "February");
+ * elm_spinner_special_value_add(sp, 3, "March");
+ * evas_object_show(sp);
+ * @endcode
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the interval on time updates for an user mouse button hold
+ * on spinner widgets' arrows.
+ *
+ * @param obj The spinner 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 spinner's value.
+ *
+ * This helps the user to get to a given value distant from the
+ * current one easier/faster, as it will start to change quicker and
+ * quicker on mouse button holds.
+ *
+ * The calculation for the next change interval value, starting from
+ * the one set with this call, is the previous interval divided by
+ * @c 1.05, so it decreases a little bit.
+ *
+ * The default starting interval value for automatic changes is
+ * @c 0.85 seconds.
+ *
+ * @see elm_spinner_interval_get()
+ *
+ * @ingroup Spinner
+ */
EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the interval on time updates for an user mouse button hold
+ * on spinner widgets' arrows.
+ *
+ * @param obj The spinner object.
+ * @return The (first) interval value, in seconds, set on it.
+ *
+ * @see elm_spinner_interval_set() for more details.
+ *
+ * @ingroup Spinner
+ */
EAPI double elm_spinner_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "changed" - when the spinner value changes
- * "delay,changed" - when the spinner value changed, but a small time after a change (use this if you only want to respond to a change once the spinner is held still for a short while).
+
+ /**
+ * @}
*/
- /* available item styles:
- * default
- * vertical (two up/down buttons at the right side and text left aligned)
+
+ /**
+ * @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
+ * items (usually letters, for alphabetically ordered access).
+ *
+ * Index widgets are by default hidden and just appear when the
+ * user clicks over it's reserved area in the canvas. In its
+ * default theme, it's an area one @ref Fingers "finger" wide on
+ * the right side of the index widget's container.
+ *
+ * When items on the index are selected, smart callbacks get
+ * called, so that its user can make other container objects to
+ * show a given area or child object depending on the index item
+ * selected. You'd probably be using an index together with @ref
+ * List "lists", @ref Genlist "generic lists" or @ref Gengrid
+ * "general grids".
+ *
+ * Smart events one can add callbacks for are:
+ * - @c "changed" - When the selected index item changes. @c
+ * event_info is the selected item's data pointer.
+ * - @c "delay,changed" - When the selected index item changes, but
+ * after a small idling period. @c event_info is the selected
+ * item's data pointer.
+ * - @c "selected" - When the user releases a mouse button and
+ * selects an item. @c event_info is the selected item's data
+ * pointer.
+ * - @c "level,up" - when the user moves a finger from the first
+ * level to the second level
+ * - @c "level,down" - when the user moves a finger from the second
+ * level to the first level
+ *
+ * The @c "delay,changed" event is so that it'll wait a small time
+ * before actually reporting those events and, moreover, just the
+ * last event happening on those time frames will actually be
+ * reported.
+ *
+ * Here are some examples on its usage:
+ * @li @ref index_example_01
+ * @li @ref index_example_02
+ */
+
+ /**
+ * @addtogroup Index
+ * @{
+ */
+
+ typedef struct _Elm_Index_Item Elm_Index_Item; /**< Opaque handle for items of Elementary index widgets */
+
+ /**
+ * Add a new index widget to the given parent Elementary
+ * (container) object
+ *
+ * @param parent The parent object
+ * @return a new index widget handle or @c NULL, on errors
+ *
+ * This function inserts a new index widget on the canvas.
+ *
+ * @ingroup Index
*/
-
- /* index */
- typedef struct _Elm_Index_Item Elm_Index_Item; /**< Item of Elm_Index. Sub-type of Elm_Widget_Item */
-
EAPI Evas_Object *elm_index_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given index widget is or not visible,
+ * programatically.
+ *
+ * @param obj The index object
+ * @param active @c EINA_TRUE to show it, @c EINA_FALSE to hide it
+ *
+ * Not to be confused with visible as in @c evas_object_show() --
+ * visible with regard to the widget's auto hiding feature.
+ *
+ * @see elm_index_active_get()
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_active_set(Evas_Object *obj, Eina_Bool active) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given index widget is currently visible or not.
+ *
+ * @param obj The index object
+ * @return @c EINA_TRUE, if it's shown, @c EINA_FALSE otherwise
+ *
+ * @see elm_index_active_set() for more details
+ *
+ * @ingroup Index
+ */
EAPI Eina_Bool elm_index_active_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the items level for a given index widget.
+ *
+ * @param obj The index object.
+ * @param level @c 0 or @c 1, the currently implemented levels.
+ *
+ * @see elm_index_item_level_get()
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_level_set(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the items level set for a given index widget.
+ *
+ * @param obj The index object.
+ * @return @c 0 or @c 1, which are the levels @p obj might be at.
+ *
+ * @see elm_index_item_level_set() for more information
+ *
+ * @ingroup Index
+ */
EAPI int elm_index_item_level_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Returns the last selected item's data, for a given index widget.
+ *
+ * @param obj The index object.
+ * @return The item @b data associated to the last selected item on
+ * @p obj (or @c NULL, on errors).
+ *
+ * @warning The returned value is @b not an #Elm_Index_Item item
+ * handle, but the data associated to it (see the @c item parameter
+ * in elm_index_item_append(), as an example).
+ *
+ * @ingroup Index
+ */
EAPI void *elm_index_item_selected_get(const Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
+
+ /**
+ * Append a new item on a given index widget.
+ *
+ * @param obj The index object.
+ * @param letter Letter under which the item should be indexed
+ * @param item The item data to set for the index's item
+ *
+ * Despite the most common usage of the @p letter argument is for
+ * single char strings, one could use arbitrary strings as index
+ * entries.
+ *
+ * @c item will be the pointer returned back on @c "changed", @c
+ * "delay,changed" and @c "selected" smart events.
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_append(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Prepend a new item on a given index widget.
+ *
+ * @param obj The index object.
+ * @param letter Letter under which the item should be indexed
+ * @param item The item data to set for the index's item
+ *
+ * Despite the most common usage of the @p letter argument is for
+ * single char strings, one could use arbitrary strings as index
+ * entries.
+ *
+ * @c item will be the pointer returned back on @c "changed", @c
+ * "delay,changed" and @c "selected" smart events.
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Append a new item, on a given index widget, <b>after the item
+ * having @p relative as data</b>.
+ *
+ * @param obj The index object.
+ * @param letter Letter under which the item should be indexed
+ * @param item The item data to set for the index's item
+ * @param relative The item data of the index item to be the
+ * predecessor of this new one
+ *
+ * Despite the most common usage of the @p letter argument is for
+ * single char strings, one could use arbitrary strings as index
+ * entries.
+ *
+ * @c item will be the pointer returned back on @c "changed", @c
+ * "delay,changed" and @c "selected" smart events.
+ *
+ * @note If @p relative is @c NULL or if it's not found to be data
+ * set on any previous item on @p obj, this function will behave as
+ * elm_index_item_append().
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void *item, const void *relative) EINA_ARG_NONNULL(1);
+
+ /**
+ * Prepend a new item, on a given index widget, <b>after the item
+ * having @p relative as data</b>.
+ *
+ * @param obj The index object.
+ * @param letter Letter under which the item should be indexed
+ * @param item The item data to set for the index's item
+ * @param relative The item data of the index item to be the
+ * successor of this new one
+ *
+ * Despite the most common usage of the @p letter argument is for
+ * single char strings, one could use arbitrary strings as index
+ * entries.
+ *
+ * @c item will be the pointer returned back on @c "changed", @c
+ * "delay,changed" and @c "selected" smart events.
+ *
+ * @note If @p relative is @c NULL or if it's not found to be data
+ * set on any previous item on @p obj, this function will behave as
+ * elm_index_item_prepend().
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void *item, const void *relative) EINA_ARG_NONNULL(1);
+
+ /**
+ * Insert a new item into the given index widget, using @p cmp_func
+ * function to sort items (by item handles).
+ *
+ * @param obj The index object.
+ * @param letter Letter under which the item should be indexed
+ * @param item The item data to set for the index's item
+ * @param cmp_func The comparing function to be used to sort index
+ * items <b>by #Elm_Index_Item item handles</b>
+ * @param cmp_data_func A @b fallback function to be called for the
+ * sorting of index items <b>by item data</b>). It will be used
+ * when @p cmp_func returns @c 0 (equality), which means an index
+ * item with provided item data already exists. To decide which
+ * data item should be pointed to by the index item in question, @p
+ * cmp_data_func will be used. If @p cmp_data_func returns a
+ * non-negative value, the previous index item data will be
+ * replaced by the given @p item pointer. If the previous data need
+ * to be freed, it should be done by the @p cmp_data_func function,
+ * because all references to it will be lost. If this function is
+ * not provided (@c NULL is given), index items will be @b
+ * duplicated, if @p cmp_func returns @c 0.
+ *
+ * Despite the most common usage of the @p letter argument is for
+ * single char strings, one could use arbitrary strings as index
+ * entries.
+ *
+ * @c item will be the pointer returned back on @c "changed", @c
+ * "delay,changed" and @c "selected" smart events.
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_sorted_insert(Evas_Object *obj, const char *letter, const void *item, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func) EINA_ARG_NONNULL(1);
+
+ /**
+ * Remove an item from a given index widget, <b>to be referenced by
+ * it's data value</b>.
+ *
+ * @param obj The index object
+ * @param item The item's data pointer for the item to be removed
+ * from @p obj
+ *
+ * If a deletion callback is set, via elm_index_item_del_cb_set(),
+ * that callback function will be called by this one.
+ *
+ * @warning The item to be removed from @p obj will be found via
+ * its item data pointer, and not by an #Elm_Index_Item handle.
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_del(Evas_Object *obj, const void *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Find a given index widget's item, <b>using item data</b>.
+ *
+ * @param obj The index object
+ * @param item The item data pointed to by the desired index item
+ * @return The index item handle, if found, or @c NULL otherwise
+ *
+ * @ingroup Index
+ */
EAPI Elm_Index_Item *elm_index_item_find(Evas_Object *obj, const void *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Removes @b all items from a given index widget.
+ *
+ * @param obj The index object.
+ *
+ * If deletion callbacks are set, via elm_index_item_del_cb_set(),
+ * that callback function will be called for each item in @p obj.
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Go to a given items level on a index widget
+ *
+ * @param obj The index object
+ * @param level The index level (one of @c 0 or @c 1)
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_go(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
+
+ /**
+ * Return the data associated with a given index widget item
+ *
+ * @param it The index widget item handle
+ * @return The data associated with @p it
+ *
+ * @see elm_index_item_data_set()
+ *
+ * @ingroup Index
+ */
EAPI void *elm_index_item_data_get(const Elm_Index_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the data associated with a given index widget item
+ *
+ * @param it The index widget item handle
+ * @param data The new data pointer to set to @p it
+ *
+ * This sets new item data on @p it.
+ *
+ * @warning The old data pointer won't be touched by this function, so
+ * the user had better to free that old data himself/herself.
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_data_set(Elm_Index_Item *it, const void *data) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the function to be called when a given index widget item is freed.
+ *
+ * @param it The item to set the callback on
+ * @param func The function to call on the item's deletion
+ *
+ * When called, @p func will have both @c data and @c event_info
+ * arguments with the @p it item's data value and, naturally, the
+ * @c obj argument with a handle to the parent index widget.
+ *
+ * @ingroup Index
+ */
EAPI void elm_index_item_del_cb_set(Elm_Index_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the letter (string) set on a given index widget item.
+ *
+ * @param it The index item handle
+ * @return The letter string set on @p it
+ *
+ * @ingroup Index
+ */
EAPI const char *elm_index_item_letter_get(const Elm_Index_Item *item) EINA_ARG_NONNULL(1);
+
+ /**
+ */
EAPI void elm_index_button_image_invisible_set(Evas_Object *obj, Eina_Bool invisible) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "changed" - when the selected index item changes
- * "delay,changed" - when the selected index item changes, but after some small idle period
- * "selected" - when the user releases a finger and selects an item
- * "level,up" - when the user moves a finger from the first level to the second level
- * "level,down" - when the user moves a finger from the second level to the first level
+
+ /**
+ * @}
*/
- /* photocam */
+ /**
+ * @defgroup Photocam Photocam
+ *
+ * @image html img/widget/photocam/preview-00.png
+ * @image latex img/widget/photocam/preview-00.eps
+ *
+ * This is a widget specifically for displaying high-resolution digital
+ * camera photos giving speedy feedback (fast load), low memory footprint
+ * and zooming and panning as well as fitting logic. It is entirely focused
+ * on jpeg images, and takes advantage of properties of the jpeg format (via
+ * evas loader features in the jpeg loader).
+ *
+ * Signals that you can add callbacks for are:
+ * @li "clicked" - This is called when a user has clicked the photo without
+ * dragging around.
+ * @li "press" - This is called when a user has pressed down on the photo.
+ * @li "longpressed" - This is called when a user has pressed down on the
+ * photo for a long time without dragging around.
+ * @li "clicked,double" - This is called when a user has double-clicked the
+ * photo.
+ * @li "load" - Photo load begins.
+ * @li "loaded" - This is called when the image file load is complete for the
+ * first view (low resolution blurry version).
+ * @li "load,detail" - Photo detailed data load begins.
+ * @li "loaded,detail" - This is called when the image file load is complete
+ * for the detailed image data (full resolution needed).
+ * @li "zoom,start" - Zoom animation started.
+ * @li "zoom,stop" - Zoom animation stopped.
+ * @li "zoom,change" - Zoom changed when using an auto zoom mode.
+ * @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
+ *
+ * @ref tutorial_photocam shows the API in action.
+ * @{
+ */
+ /**
+ * @brief Types of zoom available.
+ */
typedef enum _Elm_Photocam_Zoom_Mode
{
- ELM_PHOTOCAM_ZOOM_MODE_MANUAL = 0,
- ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT,
- ELM_PHOTOCAM_ZOOM_MODE_AUTO_FILL,
+ ELM_PHOTOCAM_ZOOM_MODE_MANUAL = 0, /**< Zoom controled normally by elm_photocam_zoom_set */
+ ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT, /**< Zoom until photo fits in photocam */
+ ELM_PHOTOCAM_ZOOM_MODE_AUTO_FILL, /**< Zoom until photo fills photocam */
ELM_PHOTOCAM_ZOOM_MODE_LAST
} Elm_Photocam_Zoom_Mode;
-
+ /**
+ * @brief Add a new Photocam object
+ *
+ * @param parent The parent object
+ * @return The new object or NULL if it cannot be created
+ */
EAPI Evas_Object *elm_photocam_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the photo file to be shown
+ *
+ * @param obj The photocam object
+ * @param file The photo file
+ * @return The return error (see EVAS_LOAD_ERROR_NONE, EVAS_LOAD_ERROR_GENERIC etc.)
+ *
+ * This sets (and shows) the specified file (with a relative or absolute
+ * path) and will return a load error (same error that
+ * evas_object_image_load_error_get() will return). The image will change and
+ * adjust its size at this point and begin a background load process for this
+ * photo that at some time in the future will be displayed at the full
+ * quality needed.
+ */
EAPI Evas_Load_Error elm_photocam_file_set(Evas_Object *obj, const char *file) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Returns the path of the current image file
+ *
+ * @param obj The photocam object
+ * @return Returns the path
+ *
+ * @see elm_photocam_file_set()
+ */
EAPI const char *elm_photocam_file_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the zoom level of the photo
+ *
+ * @param obj The photocam object
+ * @param zoom The zoom level to set
+ *
+ * This sets the zoom level. 1 will be 1:1 pixel for pixel. 2 will be 2:1
+ * (that is 2x2 photo pixels will display as 1 on-screen pixel). 4:1 will be
+ * 4x4 photo pixels as 1 screen pixel, and so on. The @p zoom parameter must
+ * be greater than 0. It is usggested to stick to powers of 2. (1, 2, 4, 8,
+ * 16, 32, etc.).
+ */
EAPI void elm_photocam_zoom_set(Evas_Object *obj, double zoom) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the zoom level of the photo
+ *
+ * @param obj The photocam object
+ * @return The current zoom level
+ *
+ * This returns the current zoom level of the photocam object. Note that if
+ * you set the fill mode to other than ELM_PHOTOCAM_ZOOM_MODE_MANUAL
+ * (which is the default), the zoom level may be changed at any time by the
+ * photocam object itself to account for photo size and photocam viewpoer
+ * size.
+ *
+ * @see elm_photocam_zoom_set()
+ * @see elm_photocam_zoom_mode_set()
+ */
EAPI double elm_photocam_zoom_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the zoom mode
+ *
+ * @param obj The photocam object
+ * @param mode The desired mode
+ *
+ * This sets the zoom mode to manual or one of several automatic levels.
+ * Manual (ELM_PHOTOCAM_ZOOM_MODE_MANUAL) means that zoom is set manually by
+ * elm_photocam_zoom_set() and will stay at that level until changed by code
+ * or until zoom mode is changed. This is the default mode. The Automatic
+ * modes will allow the photocam object to automatically adjust zoom mode
+ * based on properties. ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT) will adjust zoom so
+ * the photo fits EXACTLY inside the scroll frame with no pixels outside this
+ * area. ELM_PHOTOCAM_ZOOM_MODE_AUTO_FILL will be similar but ensure no
+ * pixels within the frame are left unfilled.
+ */
EAPI void elm_photocam_zoom_mode_set(Evas_Object *obj, Elm_Photocam_Zoom_Mode mode) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the zoom mode
+ *
+ * @param obj The photocam object
+ * @return The current zoom mode
+ *
+ * This gets the current zoom mode of the photocam object.
+ *
+ * @see elm_photocam_zoom_mode_set()
+ */
EAPI Elm_Photocam_Zoom_Mode elm_photocam_zoom_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the current image pixel width and height
+ *
+ * @param obj The photocam object
+ * @param w A pointer to the width return
+ * @param h A pointer to the height return
+ *
+ * This gets the current photo pixel width and height (for the original).
+ * The size will be returned in the integers @p w and @p h that are pointed
+ * to.
+ */
EAPI void elm_photocam_image_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the area of the image that is currently shown
+ *
+ * @param obj
+ * @param x A pointer to the X-coordinate of region
+ * @param y A pointer to the Y-coordinate of region
+ * @param w A pointer to the width
+ * @param h A pointer to the height
+ *
+ * @see elm_photocam_image_region_show()
+ * @see elm_photocam_image_region_bring_in()
+ */
EAPI void elm_photocam_region_get(const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the viewed portion of the image
+ *
+ * @param obj The photocam object
+ * @param x X-coordinate of region in image original pixels
+ * @param y Y-coordinate of region in image original pixels
+ * @param w Width of region in image original pixels
+ * @param h Height of region in image original pixels
+ *
+ * This shows the region of the image without using animation.
+ */
EAPI void elm_photocam_image_region_show(Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Bring in the viewed portion of the image
+ *
+ * @param obj The photocam object
+ * @param x X-coordinate of region in image original pixels
+ * @param y Y-coordinate of region in image original pixels
+ * @param w Width of region in image original pixels
+ * @param h Height of region in image original pixels
+ *
+ * This shows the region of the image using animation.
+ */
EAPI void elm_photocam_image_region_bring_in(Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the paused state for photocam
+ *
+ * @param obj The photocam object
+ * @param paused The pause state to set
+ *
+ * This sets the paused state to on(EINA_TRUE) or off (EINA_FALSE) for
+ * photocam. The default is off. This will stop zooming using animation on
+ * zoom levels changes and change instantly. This will stop any existing
+ * animations that are running.
+ */
EAPI void elm_photocam_paused_set(Evas_Object *obj, Eina_Bool paused) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the paused state for photocam
+ *
+ * @param obj The photocam object
+ * @return The current paused state
+ *
+ * This gets the current paused state for the photocam object.
+ *
+ * @see elm_photocam_paused_set()
+ */
EAPI Eina_Bool elm_photocam_paused_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the internal low-res image used for photocam
+ *
+ * @param obj The photocam object
+ * @return The internal image object handle, or NULL if none exists
+ *
+ * This gets the internal image object inside photocam. Do not modify it. It
+ * is for inspection only, and hooking callbacks to. Nothing else. It may be
+ * deleted at any time as well.
+ */
EAPI Evas_Object *elm_photocam_internal_image_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Set the photocam scrolling bouncing.
+ *
+ * @param obj The photocam object
+ * @param h_bounce bouncing for horizontal
+ * @param v_bounce bouncing for vertical
+ */
EAPI void elm_photocam_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
+ /**
+ * @brief Get the photocam scrolling bouncing.
+ *
+ * @param obj The photocam object
+ * @param h_bounce bouncing for horizontal
+ * @param v_bounce bouncing for vertical
+ *
+ * @see elm_photocam_bounce_set()
+ */
EAPI void elm_photocam_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "clicked" - when image clicked
- * "press" - when mouse/finger held down initially on image
- * "longpressed" - when mouse/finger held for long time on image
- * "clicked,double" - when mouse/finger double-clicked
- * "load" - when photo load begins
- * "loaded" - when photo load done
- * "load,detail" - when detailed image load begins
- * "loaded,detail" - when detailed image load done
- * "zoom,start" - when zooming started
- * "zoom,stop" - when zooming stopped
- * "zoom,change" - when auto zoom mode changed zoom level
- * "scroll - the content has been scrolled (moved)
- * "scroll,anim,start" - scrolling animation has started
- * "scroll,anim,stop" - scrolling animation has stopped
- * "scroll,drag,start" - dragging the contents around has started
- * "scroll,drag,stop" - dragging the contents around has stopped
- */
-
- /* map */
+ /**
+ * @}
+ */
+
+ /**
+ * @defgroup Map Map
+ * @ingroup Elementary
+ *
+ * @image html img/widget/map/preview-00.png
+ * @image latex img/widget/map/preview-00.eps
+ *
+ * This is a widget specifically for displaying a map. It uses basically
+ * OpenStreetMap provider http://www.openstreetmap.org/,
+ * but custom providers can be added.
+ *
+ * It supports some basic but yet nice features:
+ * @li zoom and scroll
+ * @li markers with content to be displayed when user clicks over it
+ * @li group of markers
+ * @li routes
+ *
+ * Smart callbacks one can listen to:
+ *
+ * - "clicked" - This is called when a user has clicked the map without
+ * dragging around.
+ * - "press" - This is called when a user has pressed down on the map.
+ * - "longpressed" - This is called when a user has pressed down on the map
+ * for a long time without dragging around.
+ * - "clicked,double" - This is called when a user has double-clicked
+ * the map.
+ * - "load,detail" - Map detailed data load begins.
+ * - "loaded,detail" - This is called when all currently visible parts of
+ * the map are loaded.
+ * - "zoom,start" - Zoom animation started.
+ * - "zoom,stop" - Zoom animation stopped.
+ * - "zoom,change" - Zoom changed when using an auto zoom mode.
+ * - "scroll" - the content has been scrolled (moved).
+ * - "scroll,anim,start" - scrolling animation has started.
+ * - "scroll,anim,stop" - scrolling animation has stopped.
+ * - "scroll,drag,start" - dragging the contents around has started.
+ * - "scroll,drag,stop" - dragging the contents around has stopped.
+ * - "downloaded" - This is called when all currently required map images
+ * are downloaded.
+ * - "route,load" - This is called when route request begins.
+ * - "route,loaded" - This is called when route request ends.
+ * - "name,load" - This is called when name request begins.
+ * - "name,loaded- This is called when name request ends.
+ *
+ * Available style for map widget:
+ * - @c "default"
+ *
+ * Available style for markers:
+ * - @c "radio"
+ * - @c "radio2"
+ * - @c "empty"
+ *
+ * Available style for marker bubble:
+ * - @c "default"
+ *
+ * List of examples:
+ * @li @ref map_example_01
+ * @li @ref map_example_02
+ * @li @ref map_example_03
+ */
+
+ /**
+ * @addtogroup Map
+ * @{
+ */
+
+ /**
+ * @enum _Elm_Map_Zoom_Mode
+ * @typedef Elm_Map_Zoom_Mode
+ *
+ * Set map's zoom behavior. It can be set to manual or automatic.
+ *
+ * Default value is #ELM_MAP_ZOOM_MODE_MANUAL.
+ *
+ * Values <b> don't </b> work as bitmask, only one can be choosen.
+ *
+ * @note Valid sizes are 2^zoom, consequently the map may be smaller
+ * than the scroller view.
+ *
+ * @see elm_map_zoom_mode_set()
+ * @see elm_map_zoom_mode_get()
+ *
+ * @ingroup Map
+ */
typedef enum _Elm_Map_Zoom_Mode
{
- ELM_MAP_ZOOM_MODE_MANUAL,
- ELM_MAP_ZOOM_MODE_AUTO_FIT,
- ELM_MAP_ZOOM_MODE_AUTO_FILL,
+ ELM_MAP_ZOOM_MODE_MANUAL, /**< Zoom controled manually by elm_map_zoom_set(). It's set by default. */
+ ELM_MAP_ZOOM_MODE_AUTO_FIT, /**< Zoom until map fits inside the scroll frame with no pixels outside this area. */
+ ELM_MAP_ZOOM_MODE_AUTO_FILL, /**< Zoom until map fills scroll, ensuring no pixels are left unfilled. */
ELM_MAP_ZOOM_MODE_LAST
} Elm_Map_Zoom_Mode;
+ /**
+ * @enum _Elm_Map_Route_Sources
+ * @typedef Elm_Map_Route_Sources
+ *
+ * Set route service to be used. By default used source is
+ * #ELM_MAP_ROUTE_SOURCE_YOURS.
+ *
+ * @see elm_map_route_source_set()
+ * @see elm_map_route_source_get()
+ *
+ * @ingroup Map
+ */
typedef enum _Elm_Map_Route_Sources
{
- ELM_MAP_ROUTE_SOURCE_YOURS,
- ELM_MAP_ROUTE_SOURCE_MONAV,
- ELM_MAP_ROUTE_SOURCE_ORS,
+ ELM_MAP_ROUTE_SOURCE_YOURS, /**< Routing service http://www.yournavigation.org/ . Set by default.*/
+ ELM_MAP_ROUTE_SOURCE_MONAV, /**< MoNav offers exact routing without heuristic assumptions. Its routing core is based on Contraction Hierarchies. It's not working with Map yet. */
+ ELM_MAP_ROUTE_SOURCE_ORS, /**< Open Route Service: http://www.openrouteservice.org/ . It's not working with Map yet. */
ELM_MAP_ROUTE_SOURCE_LAST
} Elm_Map_Route_Sources;
ELM_MAP_NAME_SOURCE_LAST
} Elm_Map_Name_Sources;
+ /**
+ * @enum _Elm_Map_Route_Type
+ * @typedef Elm_Map_Route_Type
+ *
+ * Set type of transport used on route.
+ *
+ * @see elm_map_route_add()
+ *
+ * @ingroup Map
+ */
typedef enum _Elm_Map_Route_Type
{
- ELM_MAP_ROUTE_TYPE_MOTOCAR,
- ELM_MAP_ROUTE_TYPE_BICYCLE,
- ELM_MAP_ROUTE_TYPE_FOOT,
+ ELM_MAP_ROUTE_TYPE_MOTOCAR, /**< Route should consider an automobile will be used. */
+ ELM_MAP_ROUTE_TYPE_BICYCLE, /**< Route should consider a bicycle will be used by the user. */
+ ELM_MAP_ROUTE_TYPE_FOOT, /**< Route should consider user will be walking. */
ELM_MAP_ROUTE_TYPE_LAST
} Elm_Map_Route_Type;
+ /**
+ * @enum _Elm_Map_Route_Method
+ * @typedef Elm_Map_Route_Method
+ *
+ * Set the routing method, what should be priorized, time or distance.
+ *
+ * @see elm_map_route_add()
+ *
+ * @ingroup Map
+ */
typedef enum _Elm_Map_Route_Method
{
- ELM_MAP_ROUTE_METHOD_FASTEST,
- ELM_MAP_ROUTE_METHOD_SHORTEST,
+ ELM_MAP_ROUTE_METHOD_FASTEST, /**< Route should priorize time. */
+ ELM_MAP_ROUTE_METHOD_SHORTEST, /**< Route should priorize distance. */
ELM_MAP_ROUTE_METHOD_LAST
} Elm_Map_Route_Method;
ELM_MAP_NAME_METHOD_LAST
} Elm_Map_Name_Method;
- typedef struct _Elm_Map_Marker Elm_Map_Marker;
- typedef struct _Elm_Map_Marker_Class Elm_Map_Marker_Class;
- typedef struct _Elm_Map_Group_Class Elm_Map_Group_Class;
- typedef struct _Elm_Map_Route Elm_Map_Route;
- typedef struct _Elm_Map_Name Elm_Map_Name;
+ typedef struct _Elm_Map_Marker Elm_Map_Marker; /**< A marker to be shown in a specific point of the map. Can be created with elm_map_marker_add() and deleted with elm_map_marker_remove(). */
+ typedef struct _Elm_Map_Marker_Class Elm_Map_Marker_Class; /**< Each marker must be associated to a class. It's required to add a mark. The class defines the style of the marker when a marker is displayed alone (not grouped). A new class can be created with elm_map_marker_class_new(). */
+ typedef struct _Elm_Map_Group_Class Elm_Map_Group_Class; /**< Each marker must be associated to a group class. It's required to add a mark. The group class defines the style of the marker when a marker is grouped to other markers. Markers with the same group are grouped if they are close. A new group class can be created with elm_map_marker_group_class_new(). */
+ typedef struct _Elm_Map_Route Elm_Map_Route; /**< A route to be shown in the map. Can be created with elm_map_route_add() and deleted with elm_map_route_remove(). */
+ typedef struct _Elm_Map_Name Elm_Map_Name; /**< A handle for specific coordinates. */
typedef struct _Elm_Map_Track Elm_Map_Track;
- typedef Evas_Object *(*ElmMapMarkerGetFunc) (Evas_Object *obj, Elm_Map_Marker *marker, void *data);
- typedef void (*ElmMapMarkerDelFunc) (Evas_Object *obj, Elm_Map_Marker *marker, void *data, Evas_Object *o);
- typedef Evas_Object *(*ElmMapMarkerIconGetFunc) (Evas_Object *obj, Elm_Map_Marker *marker, void *data);
- typedef Evas_Object *(*ElmMapGroupIconGetFunc) (Evas_Object *obj, void *data);
+ typedef Evas_Object *(*ElmMapMarkerGetFunc) (Evas_Object *obj, Elm_Map_Marker *marker, void *data); /**< Bubble content fetching class function for marker classes. When the user click on a marker, a bubble is displayed with a content. */
+ typedef void (*ElmMapMarkerDelFunc) (Evas_Object *obj, Elm_Map_Marker *marker, void *data, Evas_Object *o); /**< Function to delete bubble content for marker classes. */
+ typedef Evas_Object *(*ElmMapMarkerIconGetFunc) (Evas_Object *obj, Elm_Map_Marker *marker, void *data); /**< Icon fetching class function for marker classes. */
+ typedef Evas_Object *(*ElmMapGroupIconGetFunc) (Evas_Object *obj, void *data); /**< Icon fetching class function for markers group classes. */
typedef char *(*ElmMapModuleSourceFunc) (void);
typedef int (*ElmMapModuleZoomMinFunc) (void);
typedef Eina_Bool (*ElmMapModuleGeoIntoCoordFunc) (const Evas_Object *obj, int zoom, double lon, double lat, int size, int *x, int *y);
typedef Eina_Bool (*ElmMapModuleCoordIntoGeoFunc) (const Evas_Object *obj, int zoom, int x, int y, int size, double *lon, double *lat);
+ /**
+ * Add a new map widget to the given parent Elementary (container) object.
+ *
+ * @param parent The parent object.
+ * @return a new map widget handle or @c NULL, on errors.
+ *
+ * This function inserts a new map widget on the canvas.
+ *
+ * @ingroup Map
+ */
EAPI Evas_Object *elm_map_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the zoom level of the map.
+ *
+ * @param obj The map object.
+ * @param zoom The zoom level to set.
+ *
+ * This sets the zoom level.
+ *
+ * It will respect limits defined by elm_map_source_zoom_min_set() and
+ * elm_map_source_zoom_max_set().
+ *
+ * By default these values are 0 (world map) and 18 (maximum zoom).
+ *
+ * This function should be used when zoom mode is set to
+ * #ELM_MAP_ZOOM_MODE_MANUAL. This is the default mode, and can be set
+ * with elm_map_zoom_mode_set().
+ *
+ * @see elm_map_zoom_mode_set().
+ * @see elm_map_zoom_get().
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_zoom_set(Evas_Object *obj, int zoom) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the zoom level of the map.
+ *
+ * @param obj The map object.
+ * @return The current zoom level.
+ *
+ * This returns the current zoom level of the map object.
+ *
+ * Note that if you set the fill mode to other than #ELM_MAP_ZOOM_MODE_MANUAL
+ * (which is the default), the zoom level may be changed at any time by the
+ * map object itself to account for map size and map viewport size.
+ *
+ * @see elm_map_zoom_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI int elm_map_zoom_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the zoom mode used by the map object.
+ *
+ * @param obj The map object.
+ * @param mode The zoom mode of the map, being it one of
+ * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
+ * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
+ *
+ * This sets the zoom mode to manual or one of the automatic levels.
+ * Manual (#ELM_MAP_ZOOM_MODE_MANUAL) means that zoom is set manually by
+ * elm_map_zoom_set() and will stay at that level until changed by code
+ * or until zoom mode is changed. This is the default mode.
+ *
+ * The Automatic modes will allow the map object to automatically
+ * adjust zoom mode based on properties. #ELM_MAP_ZOOM_MODE_AUTO_FIT will
+ * adjust zoom so the map fits inside the scroll frame with no pixels
+ * outside this area. #ELM_MAP_ZOOM_MODE_AUTO_FILL will be similar but
+ * ensure no pixels within the frame are left unfilled. Do not forget that
+ * the valid sizes are 2^zoom, consequently the map may be smaller than
+ * the scroller view.
+ *
+ * @see elm_map_zoom_set()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_zoom_mode_set(Evas_Object *obj, Elm_Map_Zoom_Mode mode) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the zoom mode used by the map object.
+ *
+ * @param obj The map object.
+ * @return The zoom mode of the map, being it one of
+ * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
+ * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
+ *
+ * This function returns the current zoom mode used by the map object.
+ *
+ * @see elm_map_zoom_mode_set() for more details.
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Zoom_Mode elm_map_zoom_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the current coordinates of the map.
+ *
+ * @param obj The map object.
+ * @param lon Pointer where to store longitude.
+ * @param lat Pointer where to store latitude.
+ *
+ * This gets the current center coordinates of the map object. It can be
+ * set by elm_map_geo_region_bring_in() and elm_map_geo_region_show().
+ *
+ * @see elm_map_geo_region_bring_in()
+ * @see elm_map_geo_region_show()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_geo_region_get(const Evas_Object *obj, double *lon, double *lat) EINA_ARG_NONNULL(1);
+
+ /**
+ * Animatedly bring in given coordinates to the center of the map.
+ *
+ * @param obj The map object.
+ * @param lon Longitude to center at.
+ * @param lat Latitude to center at.
+ *
+ * This causes map to jump to the given @p lat and @p lon coordinates
+ * and show it (by scrolling) in the center of the viewport, if it is not
+ * already centered. This will use animation to do so and take a period
+ * of time to complete.
+ *
+ * @see elm_map_geo_region_show() for a function to avoid animation.
+ * @see elm_map_geo_region_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_geo_region_bring_in(Evas_Object *obj, double lon, double lat) EINA_ARG_NONNULL(1);
+
+ /**
+ * Show the given coordinates at the center of the map, @b immediately.
+ *
+ * @param obj The map object.
+ * @param lon Longitude to center at.
+ * @param lat Latitude to center at.
+ *
+ * This causes map to @b redraw its viewport's contents to the
+ * region contining the given @p lat and @p lon, that will be moved to the
+ * center of the map.
+ *
+ * @see elm_map_geo_region_bring_in() for a function to move with animation.
+ * @see elm_map_geo_region_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_geo_region_show(Evas_Object *obj, double lon, double lat) EINA_ARG_NONNULL(1);
+
+ /**
+ * Pause or unpause the map.
+ *
+ * @param obj The map object.
+ * @param paused Use @c EINA_TRUE to pause the map @p obj or @c EINA_FALSE
+ * to unpause it.
+ *
+ * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
+ * for map.
+ *
+ * The default is off.
+ *
+ * This will stop zooming using animation, changing zoom levels will
+ * change instantly. This will stop any existing animations that are running.
+ *
+ * @see elm_map_paused_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_paused_set(Evas_Object *obj, Eina_Bool paused) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get a value whether map is paused or not.
+ *
+ * @param obj The map object.
+ * @return @c EINA_TRUE means map is pause. @c EINA_FALSE indicates
+ * it is not. If @p obj is @c NULL, @c EINA_FALSE is returned.
+ *
+ * This gets the current paused state for the map object.
+ *
+ * @see elm_map_paused_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI Eina_Bool elm_map_paused_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set to show markers during zoom level changes or not.
+ *
+ * @param obj The map object.
+ * @param paused Use @c EINA_TRUE to @b not show markers or @c EINA_FALSE
+ * to show them.
+ *
+ * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
+ * for map.
+ *
+ * The default is off.
+ *
+ * This will stop zooming using animation, changing zoom levels will
+ * change instantly. This will stop any existing animations that are running.
+ *
+ * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
+ * for the markers.
+ *
+ * The default is off.
+ *
+ * Enabling it will force the map to stop displaying the markers during
+ * zoom level changes. Set to on if you have a large number of markers.
+ *
+ * @see elm_map_paused_markers_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_paused_markers_set(Evas_Object *obj, Eina_Bool paused) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get a value whether markers will be displayed on zoom level changes or not
+ *
+ * @param obj The map object.
+ * @return @c EINA_TRUE means map @b won't display markers or @c EINA_FALSE
+ * indicates it will. If @p obj is @c NULL, @c EINA_FALSE is returned.
+ *
+ * This gets the current markers paused state for the map object.
+ *
+ * @see elm_map_paused_markers_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI Eina_Bool elm_map_paused_markers_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the information of downloading status.
+ *
+ * @param obj The map object.
+ * @param try_num Pointer where to store number of tiles being downloaded.
+ * @param finish_num Pointer where to store number of tiles successfully
+ * downloaded.
+ *
+ * This gets the current downloading status for the map object, the number
+ * of tiles being downloaded and the number of tiles already downloaded.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_utils_downloading_status_get(const Evas_Object *obj, int *try_num, int *finish_num) EINA_ARG_NONNULL(1, 2, 3);
+
+ /**
+ * Convert a pixel coordinate (x,y) into a geographic coordinate
+ * (longitude, latitude).
+ *
+ * @param obj The map object.
+ * @param x the coordinate.
+ * @param y the coordinate.
+ * @param size the size in pixels of the map.
+ * The map is a square and generally his size is : pow(2.0, zoom)*256.
+ * @param lon Pointer where to store the longitude that correspond to x.
+ * @param lat Pointer where to store the latitude that correspond to y.
+ *
+ * @note Origin pixel point is the top left corner of the viewport.
+ * Map zoom and size are taken on account.
+ *
+ * @see elm_map_utils_convert_geo_into_coord() if you need the inverse.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_utils_convert_coord_into_geo(const Evas_Object *obj, int x, int y, int size, double *lon, double *lat) EINA_ARG_NONNULL(1, 5, 6);
+
+ /**
+ * Convert a geographic coordinate (longitude, latitude) into a pixel
+ * coordinate (x, y).
+ *
+ * @param obj The map object.
+ * @param lon the longitude.
+ * @param lat the latitude.
+ * @param size the size in pixels of the map. The map is a square
+ * and generally his size is : pow(2.0, zoom)*256.
+ * @param x Pointer where to store the horizontal pixel coordinate that
+ * correspond to the longitude.
+ * @param y Pointer where to store the vertical pixel coordinate that
+ * correspond to the latitude.
+ *
+ * @note Origin pixel point is the top left corner of the viewport.
+ * Map zoom and size are taken on account.
+ *
+ * @see elm_map_utils_convert_coord_into_geo() if you need the inverse.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_utils_convert_geo_into_coord(const Evas_Object *obj, double lon, double lat, int size, int *x, int *y) EINA_ARG_NONNULL(1, 5, 6);
+
+ /**
+ * Convert a geographic coordinate (longitude, latitude) into a name
+ * (address).
+ *
+ * @param obj The map object.
+ * @param lon the longitude.
+ * @param lat the latitude.
+ * @return name A #Elm_Map_Name handle for this coordinate.
+ *
+ * To get the string for this address, elm_map_name_address_get()
+ * should be used.
+ *
+ * @see elm_map_utils_convert_name_into_coord() if you need the inverse.
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Name *elm_map_utils_convert_coord_into_name(const Evas_Object *obj, double lon, double lat) EINA_ARG_NONNULL(1);
+
+ /**
+ * Convert a name (address) into a geographic coordinate
+ * (longitude, latitude).
+ *
+ * @param obj The map object.
+ * @param name The address.
+ * @return name A #Elm_Map_Name handle for this address.
+ *
+ * To get the longitude and latitude, elm_map_name_region_get()
+ * should be used.
+ *
+ * @see elm_map_utils_convert_coord_into_name() if you need the inverse.
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Name *elm_map_utils_convert_name_into_coord(const Evas_Object *obj, char *address) EINA_ARG_NONNULL(1, 2);
+
+ /**
+ * Convert a pixel coordinate into a rotated pixel coordinate.
+ *
+ * @param obj The map object.
+ * @param x horizontal coordinate of the point to rotate.
+ * @param y vertical coordinate of the point to rotate.
+ * @param cx rotation's center horizontal position.
+ * @param cy rotation's center vertical position.
+ * @param degree amount of degrees from 0.0 to 360.0 to rotate arount Z axis.
+ * @param xx Pointer where to store rotated x.
+ * @param yy Pointer where to store rotated y.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_utils_rotate_coord(const Evas_Object *obj, const Evas_Coord x, const Evas_Coord y, const Evas_Coord cx, const Evas_Coord cy, const double degree, Evas_Coord *xx, Evas_Coord *yy) EINA_ARG_NONNULL(1);
+
+ /**
+ * Add a new marker to the map object.
+ *
+ * @param obj The map object.
+ * @param lon The longitude of the marker.
+ * @param lat The latitude of the marker.
+ * @param clas The class, to use when marker @b isn't grouped to others.
+ * @param clas_group The class group, to use when marker is grouped to others
+ * @param data The data passed to the callbacks.
+ *
+ * @return The created marker or @c NULL upon failure.
+ *
+ * A marker will be created and shown in a specific point of the map, defined
+ * by @p lon and @p lat.
+ *
+ * It will be displayed using style defined by @p class when this marker
+ * is displayed alone (not grouped). A new class can be created with
+ * elm_map_marker_class_new().
+ *
+ * If the marker is grouped to other markers, it will be displayed with
+ * style defined by @p class_group. Markers with the same group are grouped
+ * if they are close. A new group class can be created with
+ * elm_map_marker_group_class_new().
+ *
+ * Markers created with this method can be deleted with
+ * elm_map_marker_remove().
+ *
+ * A marker can have associated content to be displayed by a bubble,
+ * when a user click over it, as well as an icon. These objects will
+ * be fetch using class' callback functions.
+ *
+ * @see elm_map_marker_class_new()
+ * @see elm_map_marker_group_class_new()
+ * @see elm_map_marker_remove()
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Marker *elm_map_marker_add(Evas_Object *obj, double lon, double lat, Elm_Map_Marker_Class *clas, Elm_Map_Group_Class *clas_group, void *data) EINA_ARG_NONNULL(1, 4, 5);
+
+ /**
+ * Set the maximum numbers of markers' content to be displayed in a group.
+ *
+ * @param obj The map object.
+ * @param max The maximum numbers of items displayed in a bubble.
+ *
+ * A bubble will be displayed when the user clicks over the group,
+ * and will place the content of markers that belong to this group
+ * inside it.
+ *
+ * A group can have a long list of markers, consequently the creation
+ * of the content of the bubble can be very slow.
+ *
+ * In order to avoid this, a maximum number of items is displayed
+ * in a bubble.
+ *
+ * By default this number is 30.
+ *
+ * Marker with the same group class are grouped if they are close.
+ *
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_max_marker_per_group_set(Evas_Object *obj, int max) EINA_ARG_NONNULL(1);
+
+ /**
+ * Remove a marker from the map.
+ *
+ * @param marker The marker to remove.
+ *
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_remove(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the current coordinates of the marker.
+ *
+ * @param marker marker.
+ * @param lat Pointer where to store the marker's latitude.
+ * @param lon Pointer where to store the marker's longitude.
+ *
+ * These values are set when adding markers, with function
+ * elm_map_marker_add().
+ *
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_region_get(const Elm_Map_Marker *marker, double *lon, double *lat) EINA_ARG_NONNULL(1);
+
+ /**
+ * Animatedly bring in given marker to the center of the map.
+ *
+ * @param marker The marker to center at.
+ *
+ * This causes map to jump to the given @p marker's coordinates
+ * and show it (by scrolling) in the center of the viewport, if it is not
+ * already centered. This will use animation to do so and take a period
+ * of time to complete.
+ *
+ * @see elm_map_marker_show() for a function to avoid animation.
+ * @see elm_map_marker_region_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_bring_in(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
+
+ /**
+ * Show the given marker at the center of the map, @b immediately.
+ *
+ * @param marker The marker to center at.
+ *
+ * This causes map to @b redraw its viewport's contents to the
+ * region contining the given @p marker's coordinates, that will be
+ * moved to the center of the map.
+ *
+ * @see elm_map_marker_bring_in() for a function to move with animation.
+ * @see elm_map_markers_list_show() if more than one marker need to be
+ * displayed.
+ * @see elm_map_marker_region_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_show(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
+
+ /**
+ * Move and zoom the map to display a list of markers.
+ *
+ * @param markers A list of #Elm_Map_Marker handles.
+ *
+ * The map will be centered on the center point of the markers in the list.
+ * Then the map will be zoomed in order to fit the markers using the maximum
+ * zoom which allows display of all the markers.
+ *
+ * @warning All the markers should belong to the same map object.
+ *
+ * @see elm_map_marker_show() to show a single marker.
+ * @see elm_map_marker_bring_in()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_markers_list_show(Eina_List *markers) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the Evas object returned by the ElmMapMarkerGetFunc callback
+ *
+ * @param marker The marker wich content should be returned.
+ * @return Return the evas object if it exists, else @c NULL.
+ *
+ * To set callback function #ElmMapMarkerGetFunc for the marker class,
+ * elm_map_marker_class_get_cb_set() should be used.
+ *
+ * This content is what will be inside the bubble that will be displayed
+ * when an user clicks over the marker.
+ *
+ * This returns the actual Evas object used to be placed inside
+ * the bubble. This may be @c NULL, as it may
+ * not have been created or may have been deleted, at any time, by
+ * the map. <b>Do not modify this object</b> (move, resize,
+ * show, hide, etc.), as the map 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.
+ *
+ * @ingroup Map
+ */
EAPI Evas_Object *elm_map_marker_object_get(const Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
+
+ /**
+ * Update the marker
+ *
+ * @param marker The marker to be updated.
+ *
+ * If a content is set to this marker, it will call function to delete it,
+ * #ElmMapMarkerDelFunc, and then will fetch the content again with
+ * #ElmMapMarkerGetFunc.
+ *
+ * These functions are set for the marker class with
+ * elm_map_marker_class_get_cb_set() and elm_map_marker_class_del_cb_set().
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_update(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
+
+ /**
+ * Close all the bubbles opened by the user.
+ *
+ * @param obj The map object.
+ *
+ * A bubble is displayed with a content fetched with #ElmMapMarkerGetFunc
+ * when the user clicks on a marker.
+ *
+ * This functions is set for the marker class with
+ * elm_map_marker_class_get_cb_set().
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_bubbles_close(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Create a new group class.
+ *
+ * @param obj The map object.
+ * @return Returns the new group class.
+ *
+ * Each marker must be associated to a group class. Markers in the same
+ * group are grouped if they are close.
+ *
+ * The group class defines the style of the marker when a marker is grouped
+ * to others markers. When it is alone, another class will be used.
+ *
+ * A group class will need to be provided when creating a marker with
+ * elm_map_marker_add().
+ *
+ * Some properties and functions can be set by class, as:
+ * - style, with elm_map_group_class_style_set()
+ * - data - to be associated to the group class. It can be set using
+ * elm_map_group_class_data_set().
+ * - min zoom to display markers, set with
+ * elm_map_group_class_zoom_displayed_set().
+ * - max zoom to group markers, set using
+ * elm_map_group_class_zoom_grouped_set().
+ * - visibility - set if markers will be visible or not, set with
+ * elm_map_group_class_hide_set().
+ * - #ElmMapGroupIconGetFunc - used to fetch icon for markers group classes.
+ * It can be set using elm_map_group_class_icon_cb_set().
+ *
+ * @see elm_map_marker_add()
+ * @see elm_map_group_class_style_set()
+ * @see elm_map_group_class_data_set()
+ * @see elm_map_group_class_zoom_displayed_set()
+ * @see elm_map_group_class_zoom_grouped_set()
+ * @see elm_map_group_class_hide_set()
+ * @see elm_map_group_class_icon_cb_set()
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Group_Class *elm_map_group_class_new(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the marker's style of a group class.
+ *
+ * @param clas The group class.
+ * @param style The style to be used by markers.
+ *
+ * Each marker must be associated to a group class, and will use the style
+ * defined by such class when grouped to other markers.
+ *
+ * The following styles are provided by default theme:
+ * @li @c radio - blue circle
+ * @li @c radio2 - green circle
+ * @li @c empty
+ *
+ * @see elm_map_group_class_new() for more details.
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_group_class_style_set(Elm_Map_Group_Class *clas, const char *style) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the icon callback function of a group class.
+ *
+ * @param clas The group class.
+ * @param icon_get The callback function that will return the icon.
+ *
+ * Each marker must be associated to a group class, and it can display a
+ * custom icon. The function @p icon_get must return this icon.
+ *
+ * @see elm_map_group_class_new() for more details.
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_group_class_icon_cb_set(Elm_Map_Group_Class *clas, ElmMapGroupIconGetFunc icon_get) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the data associated to the group class.
+ *
+ * @param clas The group class.
+ * @param data The new user data.
+ *
+ * This data will be passed for callback functions, like icon get callback,
+ * that can be set with elm_map_group_class_icon_cb_set().
+ *
+ * If a data was previously set, the object will lose the pointer for it,
+ * so if needs to be freed, you must do it yourself.
+ *
+ * @see elm_map_group_class_new() for more details.
+ * @see elm_map_group_class_icon_cb_set()
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_group_class_data_set(Elm_Map_Group_Class *clas, void *data) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the minimum zoom from where the markers are displayed.
+ *
+ * @param clas The group class.
+ * @param zoom The minimum zoom.
+ *
+ * Markers only will be displayed when the map is displayed at @p zoom
+ * or bigger.
+ *
+ * @see elm_map_group_class_new() for more details.
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_group_class_zoom_displayed_set(Elm_Map_Group_Class *clas, int zoom) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the zoom from where the markers are no more grouped.
+ *
+ * @param clas The group class.
+ * @param zoom The maximum zoom.
+ *
+ * Markers only will be grouped when the map is displayed at
+ * less than @p zoom.
+ *
+ * @see elm_map_group_class_new() for more details.
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_group_class_zoom_grouped_set(Elm_Map_Group_Class *clas, int zoom) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set if the markers associated to the group class @clas are hidden or not.
+ *
+ * @param clas The group class.
+ * @param hide Use @c EINA_TRUE to hide markers or @c EINA_FALSE
+ * to show them.
+ *
+ * If @p hide is @c EINA_TRUE the markers will be hidden, but default
+ * is to show them.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_group_class_hide_set(Evas_Object *obj, Elm_Map_Group_Class *clas, Eina_Bool hide) EINA_ARG_NONNULL(1, 2);
+
+ /**
+ * Create a new marker class.
+ *
+ * @param obj The map object.
+ * @return Returns the new group class.
+ *
+ * Each marker must be associated to a class.
+ *
+ * The marker class defines the style of the marker when a marker is
+ * displayed alone, i.e., not grouped to to others markers. When grouped
+ * it will use group class style.
+ *
+ * A marker class will need to be provided when creating a marker with
+ * elm_map_marker_add().
+ *
+ * Some properties and functions can be set by class, as:
+ * - style, with elm_map_marker_class_style_set()
+ * - #ElmMapMarkerIconGetFunc - used to fetch icon for markers classes.
+ * It can be set using elm_map_marker_class_icon_cb_set().
+ * - #ElmMapMarkerGetFunc - used to fetch bubble content for marker classes.
+ * Set using elm_map_marker_class_get_cb_set().
+ * - #ElmMapMarkerDelFunc - used to delete bubble content for marker classes.
+ * Set using elm_map_marker_class_del_cb_set().
+ *
+ * @see elm_map_marker_add()
+ * @see elm_map_marker_class_style_set()
+ * @see elm_map_marker_class_icon_cb_set()
+ * @see elm_map_marker_class_get_cb_set()
+ * @see elm_map_marker_class_del_cb_set()
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Marker_Class *elm_map_marker_class_new(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the marker's style of a marker class.
+ *
+ * @param clas The marker class.
+ * @param style The style to be used by markers.
+ *
+ * Each marker must be associated to a marker class, and will use the style
+ * defined by such class when alone, i.e., @b not grouped to other markers.
+ *
+ * The following styles are provided by default theme:
+ * @li @c radio
+ * @li @c radio2
+ * @li @c empty
+ *
+ * @see elm_map_marker_class_new() for more details.
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_class_style_set(Elm_Map_Marker_Class *clas, const char *style) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the icon callback function of a marker class.
+ *
+ * @param clas The marker class.
+ * @param icon_get The callback function that will return the icon.
+ *
+ * Each marker must be associated to a marker class, and it can display a
+ * custom icon. The function @p icon_get must return this icon.
+ *
+ * @see elm_map_marker_class_new() for more details.
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_class_icon_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerIconGetFunc icon_get) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the bubble content callback function of a marker class.
+ *
+ * @param clas The marker class.
+ * @param get The callback function that will return the content.
+ *
+ * Each marker must be associated to a marker class, and it can display a
+ * a content on a bubble that opens when the user click over the marker.
+ * The function @p get must return this content object.
+ *
+ * If this content will need to be deleted, elm_map_marker_class_del_cb_set()
+ * can be used.
+ *
+ * @see elm_map_marker_class_new() for more details.
+ * @see elm_map_marker_class_del_cb_set()
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_class_get_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerGetFunc get) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the callback function used to delete bubble content of a marker class.
+ *
+ * @param clas The marker class.
+ * @param del The callback function that will delete the content.
+ *
+ * Each marker must be associated to a marker class, and it can display a
+ * a content on a bubble that opens when the user click over the marker.
+ * The function to return such content can be set with
+ * elm_map_marker_class_get_cb_set().
+ *
+ * If this content must be freed, a callback function need to be
+ * set for that task with this function.
+ *
+ * If this callback is defined it will have to delete (or not) the
+ * object inside, but if the callback is not defined the object will be
+ * destroyed with evas_object_del().
+ *
+ * @see elm_map_marker_class_new() for more details.
+ * @see elm_map_marker_class_get_cb_set()
+ * @see elm_map_marker_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_marker_class_del_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerDelFunc del) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the list of available sources.
+ *
+ * @param obj The map object.
+ * @return The source names list.
+ *
+ * It will provide a list with all available sources, that can be set as
+ * current source with elm_map_source_name_set(), or get with
+ * elm_map_source_name_get().
+ *
+ * Available sources:
+ * @li "Mapnik"
+ * @li "Osmarender"
+ * @li "CycleMap"
+ * @li "Maplint"
+ *
+ * @see elm_map_source_name_set() for more details.
+ * @see elm_map_source_name_get()
+ *
+ * @ingroup Map
+ */
EAPI const char **elm_map_source_names_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the source of the map.
+ *
+ * @param obj The map object.
+ * @param source The source to be used.
+ *
+ * Map widget retrieves images that composes the map from a web service.
+ * This web service can be set with this method.
+ *
+ * A different service can return a different maps with different
+ * information and it can use different zoom values.
+ *
+ * The @p source_name need to match one of the names provided by
+ * elm_map_source_names_get().
+ *
+ * The current source can be get using elm_map_source_name_get().
+ *
+ * @see elm_map_source_names_get()
+ * @see elm_map_source_name_get()
+ *
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_source_name_set(Evas_Object *obj, const char *source_name) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the name of currently used source.
+ *
+ * @param obj The map object.
+ * @return Returns the name of the source in use.
+ *
+ * @see elm_map_source_name_set() for more details.
+ *
+ * @ingroup Map
+ */
EAPI const char *elm_map_source_name_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the source of the route service to be used by the map.
+ *
+ * @param obj The map object.
+ * @param source The route service to be used, being it one of
+ * #ELM_MAP_ROUTE_SOURCE_YOURS (default), #ELM_MAP_ROUTE_SOURCE_MONAV,
+ * and #ELM_MAP_ROUTE_SOURCE_ORS.
+ *
+ * Each one has its own algorithm, so the route retrieved may
+ * differ depending on the source route. Now, only the default is working.
+ *
+ * #ELM_MAP_ROUTE_SOURCE_YOURS is the routing service provided at
+ * http://www.yournavigation.org/.
+ *
+ * #ELM_MAP_ROUTE_SOURCE_MONAV, offers exact routing without heuristic
+ * assumptions. Its routing core is based on Contraction Hierarchies.
+ *
+ * #ELM_MAP_ROUTE_SOURCE_ORS, is provided at http://www.openrouteservice.org/
+ *
+ * @see elm_map_route_source_get().
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_route_source_set(Evas_Object *obj, Elm_Map_Route_Sources source) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the current route source.
+ *
+ * @param obj The map object.
+ * @return The source of the route service used by the map.
+ *
+ * @see elm_map_route_source_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Route_Sources elm_map_route_source_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the minimum zoom of the source.
+ *
+ * @param obj The map object.
+ * @param zoom New minimum zoom value to be used.
+ *
+ * By default, it's 0.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_source_zoom_min_set(Evas_Object *obj, int zoom) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the minimum zoom of the source.
+ *
+ * @param obj The map object.
+ * @return Returns the minimum zoom of the source.
+ *
+ * @see elm_map_source_zoom_min_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI int elm_map_source_zoom_min_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the maximum zoom of the source.
+ *
+ * @param obj The map object.
+ * @param zoom New maximum zoom value to be used.
+ *
+ * By default, it's 18.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_source_zoom_max_set(Evas_Object *obj, int zoom) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the maximum zoom of the source.
+ *
+ * @param obj The map object.
+ * @return Returns the maximum zoom of the source.
+ *
+ * @see elm_map_source_zoom_min_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI int elm_map_source_zoom_max_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the user agent used by the map object to access routing services.
+ *
+ * @param obj The map object.
+ * @param user_agent The user agent to be used by the map.
+ *
+ * User agent is a client application implementing a network protocol used
+ * in communications within a client–server distributed computing system
+ *
+ * The @p user_agent identification string will transmitted in a header
+ * field @c User-Agent.
+ *
+ * @see elm_map_user_agent_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_user_agent_set(Evas_Object *obj, const char *user_agent) EINA_ARG_NONNULL(1, 2);
+
+ /**
+ * Get the user agent used by the map object.
+ *
+ * @param obj The map object.
+ * @return The user agent identification string used by the map.
+ *
+ * @see elm_map_user_agent_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI const char *elm_map_user_agent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Add a new route to the map object.
+ *
+ * @param obj The map object.
+ * @param type The type of transport to be considered when tracing a route.
+ * @param method The routing method, what should be priorized.
+ * @param flon The start longitude.
+ * @param flat The start latitude.
+ * @param tlon The destination longitude.
+ * @param tlat The destination latitude.
+ *
+ * @return The created route or @c NULL upon failure.
+ *
+ * A route will be traced by point on coordinates (@p flat, @p flon)
+ * to point on coordinates (@p tlat, @p tlon), using the route service
+ * set with elm_map_route_source_set().
+ *
+ * It will take @p type on consideration to define the route,
+ * depending if the user will be walking or driving, the route may vary.
+ * One of #ELM_MAP_ROUTE_TYPE_MOTOCAR, #ELM_MAP_ROUTE_TYPE_BICYCLE, or
+ * #ELM_MAP_ROUTE_TYPE_FOOT need to be used.
+ *
+ * Another parameter is what the route should priorize, the minor distance
+ * or the less time to be spend on the route. So @p method should be one
+ * of #ELM_MAP_ROUTE_METHOD_SHORTEST or #ELM_MAP_ROUTE_METHOD_FASTEST.
+ *
+ * Routes created with this method can be deleted with
+ * elm_map_route_remove(), colored with elm_map_route_color_set(),
+ * and distance can be get with elm_map_route_distance_get().
+ *
+ * @see elm_map_route_remove()
+ * @see elm_map_route_color_set()
+ * @see elm_map_route_distance_get()
+ * @see elm_map_route_source_set()
+ *
+ * @ingroup Map
+ */
EAPI Elm_Map_Route *elm_map_route_add(Evas_Object *obj, Elm_Map_Route_Type type, Elm_Map_Route_Method method, double flon, double flat, double tlon, double tlat) EINA_ARG_NONNULL(1);
+
+ /**
+ * Remove a route from the map.
+ *
+ * @param route The route to remove.
+ *
+ * @see elm_map_route_add()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_route_remove(Elm_Map_Route *route) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the route color.
+ *
+ * @param route The route object.
+ * @param r Red channel value, from 0 to 255.
+ * @param g Green channel value, from 0 to 255.
+ * @param b Blue channel value, from 0 to 255.
+ * @param a Alpha channel value, from 0 to 255.
+ *
+ * It uses an additive color model, so each color channel represents
+ * how much of each primary colors must to be used. 0 represents
+ * ausence of this color, so if all of the three are set to 0,
+ * the color will be black.
+ *
+ * These component values should be integers in the range 0 to 255,
+ * (single 8-bit byte).
+ *
+ * This sets the color used for the route. By default, it is set to
+ * solid red (r = 255, g = 0, b = 0, a = 255).
+ *
+ * For alpha channel, 0 represents completely transparent, and 255, opaque.
+ *
+ * @see elm_map_route_color_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_route_color_set(Elm_Map_Route *route, int r, int g , int b, int a) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the route color.
+ *
+ * @param route The route object.
+ * @param r Pointer where to store the red channel value.
+ * @param g Pointer where to store the green channel value.
+ * @param b Pointer where to store the blue channel value.
+ * @param a Pointer where to store the alpha channel value.
+ *
+ * @see elm_map_route_color_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_route_color_get(const Elm_Map_Route *route, int *r, int *g , int *b, int *a) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the route distance in kilometers.
+ *
+ * @param route The route object.
+ * @return The distance of route (unit : km).
+ *
+ * @ingroup Map
+ */
EAPI double elm_map_route_distance_get(const Elm_Map_Route *route) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the information of route nodes.
+ *
+ * @param route The route object.
+ * @return Returns a string with the nodes of route.
+ *
+ * @ingroup Map
+ */
EAPI const char *elm_map_route_node_get(const Elm_Map_Route *route) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the information of route waypoint.
+ *
+ * @param route the route object.
+ * @return Returns a string with information about waypoint of route.
+ *
+ * @ingroup Map
+ */
EAPI const char *elm_map_route_waypoint_get(const Elm_Map_Route *route) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the address of the name.
+ *
+ * @param name The name handle.
+ * @return Returns the address string of @p name.
+ *
+ * This gets the coordinates of the @p name, created with one of the
+ * conversion functions.
+ *
+ * @see elm_map_utils_convert_name_into_coord()
+ * @see elm_map_utils_convert_coord_into_name()
+ *
+ * @ingroup Map
+ */
EAPI const char *elm_map_name_address_get(const Elm_Map_Name *name) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the current coordinates of the name.
+ *
+ * @param name The name handle.
+ * @param lat Pointer where to store the latitude.
+ * @param lon Pointer where to store The longitude.
+ *
+ * This gets the coordinates of the @p name, created with one of the
+ * conversion functions.
+ *
+ * @see elm_map_utils_convert_name_into_coord()
+ * @see elm_map_utils_convert_coord_into_name()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_name_region_get(const Elm_Map_Name *name, double *lon, double *lat) EINA_ARG_NONNULL(1);
+
+ /**
+ * Remove a name from the map.
+ *
+ * @param name The name to remove.
+ *
+ * Basically the struct handled by @p name will be freed, so convertions
+ * between address and coordinates will be lost.
+ *
+ * @see elm_map_utils_convert_name_into_coord()
+ * @see elm_map_utils_convert_coord_into_name()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_name_remove(Elm_Map_Name *name) EINA_ARG_NONNULL(1);
+
+ /**
+ * Rotate the map.
+ *
+ * @param obj The map object.
+ * @param degree Angle from 0.0 to 360.0 to rotate arount Z axis.
+ * @param cx Rotation's center horizontal position.
+ * @param cy Rotation's center vertical position.
+ *
+ * @see elm_map_rotate_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_rotate_set(Evas_Object *obj, double degree, Evas_Coord cx, Evas_Coord cy) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the rotate degree of the map
+ *
+ * @param obj The map object
+ * @param degree Pointer where to store degrees from 0.0 to 360.0
+ * to rotate arount Z axis.
+ * @param cx Pointer where to store rotation's center horizontal position.
+ * @param cy Pointer where to store rotation's center vertical position.
+ *
+ * @see elm_map_rotate_set() to set map rotation.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_rotate_get(const Evas_Object *obj, double *degree, Evas_Coord *cx, Evas_Coord *cy) EINA_ARG_NONNULL(1, 2, 3, 4);
+
+ /**
+ * Enable or disable mouse wheel to be used to zoom in / out the map.
+ *
+ * @param obj The map object.
+ * @param disabled Use @c EINA_TRUE to disable mouse wheel or @c EINA_FALSE
+ * to enable it.
+ *
+ * Mouse wheel can be used for the user to zoom in or zoom out the map.
+ *
+ * It's disabled by default.
+ *
+ * @see elm_map_wheel_disabled_get()
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_wheel_disabled_set(Evas_Object *obj, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get a value whether mouse wheel is enabled or not.
+ *
+ * @param obj The map object.
+ * @return @c EINA_TRUE means map is disabled. @c EINA_FALSE indicates
+ * it is enabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
+ *
+ * Mouse wheel can be used for the user to zoom in or zoom out the map.
+ *
+ * @see elm_map_wheel_disabled_set() for details.
+ *
+ * @ingroup Map
+ */
EAPI Eina_Bool elm_map_wheel_disabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
#ifdef ELM_EMAP
+ /**
+ * Add a track on the map
+ *
+ * @param obj The map object.
+ * @param emap The emap route object.
+ * @return The route object. This is an elm object of type Route.
+ *
+ * @see elm_route_add() for details.
+ *
+ * @ingroup Map
+ */
EAPI Evas_Object *elm_map_track_add(Evas_Object *obj, EMap_Route *emap) EINA_ARG_NONNULL(1);
#endif
+
+ /**
+ * Remove a track from the map
+ *
+ * @param obj The map object.
+ * @param route The track to remove.
+ *
+ * @ingroup Map
+ */
EAPI void elm_map_track_remove(Evas_Object *obj, Evas_Object *route) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
- * "clicked" - when image clicked
- * "press" - when mouse/finger held down initially on image
- * "longpressed" - when mouse/finger held for long time on image
- * "clicked,double" - when mouse/finger double-clicked
- * "load,details" - when detailed image load begins
- * "loaded,details" - when detailed image load done
- * "zoom,start" - when zooming started
- * "zoom,stop" - when zooming stopped
- * "zoom,change" - when auto zoom mode changed zoom level
- * "scroll - the content has been scrolled (moved)
- * "scroll,anim,start" - scrolling animation has started
- * "scroll,anim,stop" - scrolling animation has stopped
- * "scroll,drag,start" - dragging the contents around has started
- * "scroll,drag,stop" - dragging the contents around has stopped
+ /**
+ * @}
*/
/* Route */
EAPI double elm_route_lon_max_get(Evas_Object *obj);
EAPI double elm_route_lat_max_get(Evas_Object *obj);
-
/* panel */
typedef enum _Elm_Panel_Orient
{
projects / framework / uifw / elementary.git / commitdiff