2 * @defgroup Hoversel Hoversel
4 * @image html img/widget/hoversel/preview-00.png
5 * @image latex img/widget/hoversel/preview-00.eps
7 * A hoversel is a button that pops up a list of items (automatically
8 * choosing the direction to display) that have a label and, optionally, an
9 * icon to select from. It is a convenience widget to avoid the need to do
10 * all the piecing together yourself. It is intended for a small number of
11 * items in the hoversel menu (no more than 8), though is capable of many
14 * Signals that you can add callbacks for are:
15 * "clicked" - the user clicked the hoversel button and popped up the sel
16 * "selected" - an item in the hoversel list is selected. event_info is the item
17 * "dismissed" - the hover is dismissed
19 * Default contents parts of the hoversel widget that you can use for are:
20 * @li "icon" - An icon of the hoversel
22 * Default text parts of the hoversel widget that you can use for are:
23 * @li "default" - Label of the hoversel
25 * Supported elm_object common APIs.
26 * @li elm_object_disabled_set
27 * @li elm_object_disabled_get
28 * @li elm_object_part_text_set
29 * @li elm_object_part_text_get
30 * @li elm_object_part_content_set
31 * @li elm_object_part_content_unset
33 * Supported elm_object_item common APIs.
34 * @li elm_object_item_part_text_get
36 * See @ref tutorial_hoversel for an example.
41 * @brief Add a new Hoversel object
43 * @param parent The parent object
44 * @return The new object or NULL if it cannot be created
46 EAPI Evas_Object *elm_hoversel_add(Evas_Object *parent);
49 * @brief This sets the hoversel to expand horizontally.
51 * @param obj The hoversel object
52 * @param horizontal If true, the hover will expand horizontally to the
55 * @note The initial button will display horizontally regardless of this
58 EAPI void elm_hoversel_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
61 * @brief This returns whether the hoversel is set to expand horizontally.
63 * @param obj The hoversel object
64 * @return If true, the hover will expand horizontally to the right.
66 * @see elm_hoversel_horizontal_set()
68 EAPI Eina_Bool elm_hoversel_horizontal_get(const Evas_Object *obj);
71 * @brief Set the Hover parent
73 * @param obj The hoversel object
74 * @param parent The parent to use
76 * Sets the hover parent object, the area that will be darkened when the
77 * hoversel is clicked. Should probably be the window that the hoversel is
78 * in. See @ref Hover objects for more information.
80 EAPI void elm_hoversel_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
82 * @brief Get the Hover parent
84 * @param obj The hoversel object
85 * @return The used parent
87 * Gets the hover parent object.
89 * @see elm_hoversel_hover_parent_set()
91 EAPI Evas_Object *elm_hoversel_hover_parent_get(const Evas_Object *obj);
94 * @brief This triggers the hoversel popup from code, the same as if the user
95 * had clicked the button.
97 * @param obj The hoversel object
99 EAPI void elm_hoversel_hover_begin(Evas_Object *obj);
102 * @brief This dismisses the hoversel popup as if the user had clicked
105 * @param obj The hoversel object
107 EAPI void elm_hoversel_hover_end(Evas_Object *obj);
110 * @brief Returns whether the hoversel is expanded.
112 * @param obj The hoversel object
113 * @return This will return EINA_TRUE if the hoversel is expanded or
114 * EINA_FALSE if it is not expanded.
116 EAPI Eina_Bool elm_hoversel_expanded_get(const Evas_Object *obj);
119 * @brief This will remove all the children items from the hoversel.
121 * @param obj The hoversel object
123 * @warning Should @b not be called while the hoversel is active; use
124 * elm_hoversel_expanded_get() to check first.
126 * @see elm_hoversel_item_del()
128 EAPI void elm_hoversel_clear(Evas_Object *obj);
131 * @brief Get the list of items within the given hoversel.
133 * @param obj The hoversel object
134 * @return Returns a list of Elm_Object_Item*
136 * @see elm_hoversel_item_add()
138 EAPI const Eina_List *elm_hoversel_items_get(const Evas_Object *obj);
141 * @brief Add an item to the hoversel button
143 * @param obj The hoversel object
144 * @param label The text label to use for the item (NULL if not desired)
145 * @param icon_file An image file path on disk to use for the icon or standard
146 * icon name (NULL if not desired)
147 * @param icon_type The icon type if relevant
148 * @param func Convenience function to call when this item is selected
149 * @param data Data to pass to item-related functions
150 * @return A handle to the item added.
152 * This adds an item to the hoversel to show when it is clicked. Note: if you
153 * need to use an icon from an edje file then use
154 * elm_hoversel_item_icon_set() right after the this function, and set
155 * icon_file to NULL here.
157 * For more information on what @p icon_file and @p icon_type are see the
158 * @ref Icon "icon documentation".
160 EAPI Elm_Object_Item *elm_hoversel_item_add(Evas_Object *obj, const char *label, const char *icon_file, Elm_Icon_Type icon_type, Evas_Smart_Cb func, const void *data);
163 * @brief Delete an item from the hoversel
165 * @param it The item to delete
167 * This deletes the item from the hoversel (should not be called while the
168 * hoversel is active; use elm_hoversel_expanded_get() to check first).
170 * @see elm_hoversel_item_add()
172 EAPI void elm_hoversel_item_del(Elm_Object_Item *it);
175 * @brief This sets the icon for the given hoversel item.
177 * @param it The item to set the icon
178 * @param icon_file An image file path on disk to use for the icon or standard
180 * @param icon_group The edje group to use if @p icon_file is an edje file. Set this
181 * to NULL if the icon is not an edje file
182 * @param icon_type The icon type
184 * The icon can be loaded from the standard set, from an image file, or from
187 * @see elm_hoversel_item_add()
189 EAPI void elm_hoversel_item_icon_set(Elm_Object_Item *it, const char *icon_file, const char *icon_group, Elm_Icon_Type icon_type);
192 * @brief Get the icon object of the hoversel item
194 * @param it The item to get the icon from
195 * @param icon_file The image file path on disk used for the icon or standard
197 * @param icon_group The edje group used if @p icon_file is an edje file. NULL
198 * if the icon is not an edje file
199 * @param icon_type The icon type
201 * @see elm_hoversel_item_icon_set()
202 * @see elm_hoversel_item_add()
204 EAPI void elm_hoversel_item_icon_get(const Elm_Object_Item *it, const char **icon_file, const char **icon_group, Elm_Icon_Type *icon_type);