Elementary migration revision 69832
[framework/uifw/elementary.git] / src / lib / elm_menu.h
1 /**
2  * @defgroup Menu Menu
3  *
4  * @image html img/widget/menu/preview-00.png
5  * @image latex img/widget/menu/preview-00.eps
6  *
7  * A menu is a list of items displayed above its parent. When the menu is
8  * showing its parent is darkened. Each item can have a sub-menu. The menu
9  * object can be used to display a menu on a right click event, in a toolbar,
10  * anywhere.
11  *
12  * Signals that you can add callbacks for are:
13  * @li "clicked" - the user clicked the empty space in the menu to dismiss.
14  *
15  * Default content parts of the menu items that you can use for are:
16  * @li "default" - A main content of the menu item
17  *
18  * Default text parts of the menu items that you can use for are:
19  * @li "default" - label in the menu item
20  *
21  * Supported elm_object_item common APIs.
22  * @li elm_object_item_part_text_set
23  * @li elm_object_item_part_text_get
24  * @li elm_object_item_part_content_set
25  * @li elm_object_item_part_content_get
26  * @li elm_object_item_disabled_set
27  * @li elm_object_item_disabled_get
28  *
29  * @see @ref tutorial_menu
30  * @{
31  */
32
33 /**
34  * @brief Add a new menu to the parent
35  *
36  * @param parent The parent object.
37  * @return The new object or NULL if it cannot be created.
38  */
39 EAPI Evas_Object                 *elm_menu_add(Evas_Object *parent);
40
41 /**
42  * @brief Set the parent for the given menu widget
43  *
44  * @param obj The menu object.
45  * @param parent The new parent.
46  */
47 EAPI void                         elm_menu_parent_set(Evas_Object *obj, Evas_Object *parent);
48
49 /**
50  * @brief Get the parent for the given menu widget
51  *
52  * @param obj The menu object.
53  * @return The parent.
54  *
55  * @see elm_menu_parent_set()
56  */
57 EAPI Evas_Object                 *elm_menu_parent_get(const Evas_Object *obj);
58
59 /**
60  * @brief Move the menu to a new position
61  *
62  * @param obj The menu object.
63  * @param x The new position.
64  * @param y The new position.
65  *
66  * Sets the top-left position of the menu to (@p x,@p y).
67  *
68  * @note @p x and @p y coordinates are relative to parent.
69  */
70 EAPI void                         elm_menu_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y);
71
72 /**
73  * @brief Close a opened menu
74  *
75  * @param obj the menu object
76  * @return void
77  *
78  * Hides the menu and all it's sub-menus.
79  */
80 EAPI void                         elm_menu_close(Evas_Object *obj);
81
82 /**
83  * @brief Returns a list of @p item's items.
84  *
85  * @param obj The menu object
86  * @return An Eina_List* of @p item's items
87  */
88 EAPI const Eina_List             *elm_menu_items_get(const Evas_Object *obj);
89
90 /**
91  * @brief Get the Evas_Object of an Elm_Object_Item
92  *
93  * @param it The menu item object.
94  * @return The edje object containing the swallowed content
95  *
96  * @warning Don't manipulate this object!
97  *
98  */
99 EAPI Evas_Object                 *elm_menu_item_object_get(const Elm_Object_Item *it);
100
101 /**
102  * @brief Add an item at the end of the given menu widget
103  *
104  * @param obj The menu object.
105  * @param parent The parent menu item (optional)
106  * @param icon An icon display on the item. The icon will be destroyed by the menu.
107  * @param label The label of the item.
108  * @param func Function called when the user select the item.
109  * @param data Data sent by the callback.
110  * @return Returns the new item.
111  */
112 EAPI Elm_Object_Item             *elm_menu_item_add(Evas_Object *obj, Elm_Object_Item *parent, const char *icon, const char *label, Evas_Smart_Cb func, const void *data);
113
114 /**
115  * @brief Set the icon of a menu item to the standard icon with name @p icon
116  *
117  * @param it The menu item object.
118  * @param icon The name of icon object to set for the content of @p item
119  *
120  * Once this icon is set, any previously set icon will be deleted.
121  */
122 EAPI void                         elm_menu_item_icon_name_set(Elm_Object_Item *it, const char *icon);
123
124 /**
125  * @brief Get the string representation from the icon of a menu item
126  *
127  * @param it The menu item object.
128  * @return The string representation of @p item's icon or NULL
129  *
130  * @see elm_menu_item_icon_name_set()
131  */
132 EAPI const char                  *elm_menu_item_icon_name_get(const Elm_Object_Item *it);
133
134 /**
135  * @brief Set the selected state of @p item.
136  *
137  * @param it The menu item object.
138  * @param selected The selected/unselected state of the item
139  */
140 EAPI void                         elm_menu_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
141
142 /**
143  * @brief Get the selected state of @p item.
144  *
145  * @param it The menu item object.
146  * @return The selected/unselected state of the item
147  *
148  * @see elm_menu_item_selected_set()
149  */
150 EAPI Eina_Bool                    elm_menu_item_selected_get(const Elm_Object_Item *it);
151
152 /**
153  * @brief Add a separator item to menu @p obj under @p parent.
154  *
155  * @param obj The menu object
156  * @param parent The item to add the separator under
157  * @return The created item or NULL on failure
158  *
159  * This is item is a @ref Separator.
160  */
161 EAPI Elm_Object_Item             *elm_menu_item_separator_add(Evas_Object *obj, Elm_Object_Item *parent);
162
163 /**
164  * @brief Returns whether @p item is a separator.
165  *
166  * @param it The item to check
167  * @return If true, @p item is a separator
168  *
169  * @see elm_menu_item_separator_add()
170  */
171 EAPI Eina_Bool                    elm_menu_item_is_separator(Elm_Object_Item *it);
172
173 /**
174  * @brief Returns a list of @p item's subitems.
175  *
176  * @param it The item
177  * @return An Eina_List* of @p item's subitems
178  *
179  * @see elm_menu_add()
180  */
181 EAPI const Eina_List             *elm_menu_item_subitems_get(const Elm_Object_Item *it);
182
183 /**
184  * @brief Get the position of a menu item
185  *
186  * @param it The menu item
187  * @return The item's index
188  *
189  * This function returns the index position of a menu item in a menu.
190  * For a sub-menu, this number is relative to the first item in the sub-menu.
191  *
192  * @note Index values begin with 0
193  */
194 EAPI unsigned int                 elm_menu_item_index_get(const Elm_Object_Item *it);
195
196 /**
197  * @brief Get the selected item in the menu
198  *
199  * @param obj The menu object
200  * @return The selected item, or NULL if none
201  *
202  * @see elm_menu_item_selected_get()
203  * @see elm_menu_item_selected_set()
204  */
205 EAPI Elm_Object_Item             *elm_menu_selected_item_get(const Evas_Object *obj);
206
207 /**
208  * @brief Get the last item in the menu
209  *
210  * @param obj The menu object
211  * @return The last item, or NULL if none
212  */
213 EAPI Elm_Object_Item             *elm_menu_last_item_get(const Evas_Object *obj);
214
215 /**
216  * @brief Get the first item in the menu
217  *
218  * @param obj The menu object
219  * @return The first item, or NULL if none
220  */
221 EAPI Elm_Object_Item             *elm_menu_first_item_get(const Evas_Object *obj);
222
223 /**
224  * @brief Get the next item in the menu.
225  *
226  * @param it The menu item object.
227  * @return The item after it, or NULL if none
228  */
229 EAPI Elm_Object_Item             *elm_menu_item_next_get(const Elm_Object_Item *it);
230
231 /**
232  * @brief Get the previous item in the menu.
233  *
234  * @param it The menu item object.
235  * @return The item before it, or NULL if none
236  */
237 EAPI Elm_Object_Item             *elm_menu_item_prev_get(const Elm_Object_Item *it);
238
239 /**
240  * @}
241  */