src/lib/elm_menu.h

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