2 * @defgroup Ctxpopup Ctxpopup
5 * @image html ctxpopup_inheritance_tree.png
6 * @image latex ctxpopup_inheritance_tree.eps
8 * @image html img/widget/ctxpopup/preview-00.png
9 * @image latex img/widget/ctxpopup/preview-00.eps
11 * @brief Context popup widget.
13 * A ctxpopup is a widget that, when shown, pops up a list of items.
14 * It automatically chooses an area inside its parent object's view
15 * (set via elm_ctxpopup_add() and elm_ctxpopup_hover_parent_set()) to
16 * optimally fit into it. In the default theme, it will also point an
17 * arrow to it's top left position at the time one shows it. Ctxpopup
18 * items have a label and/or an icon. It is intended for a small
19 * number of items (hence the use of list, not genlist).
21 * This widget inherits from the @ref Layout one, so that all the
22 * functions acting on it also work for context popup objects
25 * This widget emits the following signals, besides the ones sent from
27 * - @c "dismissed" - this is called when the outside of ctxpopup was clicked or
28 * it's parent area is changed or the language is changed. and then ctxpopup is
31 * Default content parts of the ctxpopup widget that you can use for are:
32 * @li "default" - A content of the ctxpopup
34 * Default content parts of the ctxpopup items that you can use for are:
35 * @li "icon" - An icon in the title area
37 * Default text parts of the ctxpopup items that you can use for are:
38 * @li "default" - Title label in the title area
40 * Supported elm_object common APIs.
41 * @li @ref elm_object_disabled_set
42 * @li @ref elm_object_disabled_get
44 * Supported elm_object_item common APIs.
45 * @li @ref elm_object_item_disabled_set
46 * @li @ref elm_object_item_disabled_get
47 * @li @ref elm_object_item_part_text_set
48 * @li @ref elm_object_item_part_text_get
49 * @li @ref elm_object_item_part_content_set
50 * @li @ref elm_object_item_part_content_get
51 * @li @ref elm_object_item_signal_emit
53 * @ref tutorial_ctxpopup shows the usage of a good deal of the API.
59 ELM_CTXPOPUP_DIRECTION_DOWN, /**< ctxpopup show appear below clicked area */
60 ELM_CTXPOPUP_DIRECTION_RIGHT, /**< ctxpopup show appear to the right of the clicked area */
61 ELM_CTXPOPUP_DIRECTION_LEFT, /**< ctxpopup show appear to the left of the clicked area */
62 ELM_CTXPOPUP_DIRECTION_UP, /**< ctxpopup show appear above the clicked area */
63 ELM_CTXPOPUP_DIRECTION_UNKNOWN, /**< ctxpopup does not determine it's direction yet*/
64 } Elm_Ctxpopup_Direction; /**< Direction in which to show the popup */
67 * @brief Add a new Ctxpopup object to the parent.
69 * @param parent Parent object
70 * @return New object or @c NULL, if it cannot be created
74 EAPI Evas_Object *elm_ctxpopup_add(Evas_Object *parent);
77 * @brief Set the Ctxpopup's parent
79 * @param obj The ctxpopup object
80 * @param parent The parent to use
82 * Set the parent object.
84 * @note elm_ctxpopup_add() will automatically call this function
85 * with its @c parent argument.
87 * @see elm_ctxpopup_add()
88 * @see elm_hover_parent_set()
92 EAPI void elm_ctxpopup_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
95 * @brief Get the Ctxpopup's parent
97 * @param obj The ctxpopup object
99 * @see elm_ctxpopup_hover_parent_set() for more information
103 EAPI Evas_Object *elm_ctxpopup_hover_parent_get(const Evas_Object *obj);
106 * @brief Clear all items in the given ctxpopup object.
108 * @param obj Ctxpopup object
112 EAPI void elm_ctxpopup_clear(Evas_Object *obj);
115 * @brief Change the ctxpopup's orientation to horizontal or vertical.
117 * @param obj Ctxpopup object
118 * @param horizontal @c EINA_TRUE for horizontal mode, @c EINA_FALSE for vertical
122 EAPI void elm_ctxpopup_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
125 * @brief Get the value of current ctxpopup object's orientation.
127 * @param obj Ctxpopup object
128 * @return @c EINA_TRUE for horizontal mode, @c EINA_FALSE for vertical mode (or errors)
130 * @see elm_ctxpopup_horizontal_set()
134 EAPI Eina_Bool elm_ctxpopup_horizontal_get(const Evas_Object *obj);
137 * @brief Add a new item to a ctxpopup object.
139 * @param obj Ctxpopup object
140 * @param icon Icon to be set on new item
141 * @param label The Label of the new item
142 * @param func Convenience function called when item selected
143 * @param data Data passed to @p func
144 * @return A handle to the item added or @c NULL, on errors
146 * @warning Ctxpopup can't hold both an item list and a content at the same
147 * time. When an item is added, any previous content will be removed.
149 * @see elm_object_content_set()
153 EAPI Elm_Object_Item *elm_ctxpopup_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data);
156 * @brief Set the direction priority of a ctxpopup.
158 * @param obj Ctxpopup object
159 * @param first 1st priority of direction
160 * @param second 2nd priority of direction
161 * @param third 3th priority of direction
162 * @param fourth 4th priority of direction
164 * This functions gives a chance to user to set the priority of ctxpopup
165 * showing direction. This doesn't guarantee the ctxpopup will appear in the
166 * requested direction.
168 * @see Elm_Ctxpopup_Direction
172 EAPI void elm_ctxpopup_direction_priority_set(Evas_Object *obj, Elm_Ctxpopup_Direction first, Elm_Ctxpopup_Direction second, Elm_Ctxpopup_Direction third, Elm_Ctxpopup_Direction fourth);
175 * @brief Get the direction priority of a ctxpopup.
177 * @param obj Ctxpopup object
178 * @param first 1st priority of direction to be returned
179 * @param second 2nd priority of direction to be returned
180 * @param third 3th priority of direction to be returned
181 * @param fourth 4th priority of direction to be returned
183 * @see elm_ctxpopup_direction_priority_set() for more information.
187 EAPI void elm_ctxpopup_direction_priority_get(Evas_Object *obj, Elm_Ctxpopup_Direction *first, Elm_Ctxpopup_Direction *second, Elm_Ctxpopup_Direction *third, Elm_Ctxpopup_Direction *fourth);
190 * @brief Get the current direction of a ctxpopup.
192 * @param obj Ctxpopup object
193 * @return current direction of a ctxpopup
195 * @warning Once the ctxpopup showed up, the direction would be determined
199 EAPI Elm_Ctxpopup_Direction elm_ctxpopup_direction_get(const Evas_Object *obj);
202 * @brief Dismiss a ctxpopup object
204 * @param obj The ctxpopup object
205 * Use this function to simulate clicking outside the ctxpopup to dismiss it.
206 * In this way, the ctxpopup will be hidden and the "clicked" signal will be
211 EAPI void elm_ctxpopup_dismiss(Evas_Object *obj);
214 * @brief Set whether ctxpopup hide automatically or not when parent of ctxpopup is resized
216 * @param obj Ctxpopup object
217 * @param disabled @c EINA_TRUE for not hiding, @c EINA_FALSE for hiding automatically
219 * Use this function when user wants ctxpopup not to hide automatically.
220 * In default, ctxpopup is dismissed whenever mouse clicked its background area, language is changed,
221 * and its parent geometry is updated(changed).
222 * Not to hide ctxpopup automatically, disable auto hide function by calling this API,
223 * then ctxpopup won't be dismissed in those scenarios.
225 * Default value of disabled is EINA_FALSE.
229 EAPI void elm_ctxpopup_auto_hide_disabled_set(Evas_Object *obj, Eina_Bool disabled);