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 contents 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  * @see @ref tutorial_menu
  22  * @{
  23  */
  24
  25 /**
  26  * @brief Add a new menu to the parent
  27  *
  28  * @param parent The parent object.
  29  * @return The new object or NULL if it cannot be created.
  30  */
  31 EAPI Evas_Object *
  32                                   elm_menu_add(Evas_Object *parent)
  33 EINA_ARG_NONNULL(1);
  34
  35 /**
  36  * @brief Set the parent for the given menu widget
  37  *
  38  * @param obj The menu object.
  39  * @param parent The new parent.
  40  */
  41 EAPI void                         elm_menu_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
  42
  43 /**
  44  * @brief Get the parent for the given menu widget
  45  *
  46  * @param obj The menu object.
  47  * @return The parent.
  48  *
  49  * @see elm_menu_parent_set()
  50  */
  51 EAPI Evas_Object                 *elm_menu_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  52
  53 /**
  54  * @brief Move the menu to a new position
  55  *
  56  * @param obj The menu object.
  57  * @param x The new position.
  58  * @param y The new position.
  59  *
  60  * Sets the top-left position of the menu to (@p x,@p y).
  61  *
  62  * @note @p x and @p y coordinates are relative to parent.
  63  */
  64 EAPI void                         elm_menu_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
  65
  66 /**
  67  * @brief Close a opened menu
  68  *
  69  * @param obj the menu object
  70  * @return void
  71  *
  72  * Hides the menu and all it's sub-menus.
  73  */
  74 EAPI void                         elm_menu_close(Evas_Object *obj) EINA_ARG_NONNULL(1);
  75
  76 /**
  77  * @brief Returns a list of @p item's items.
  78  *
  79  * @param obj The menu object
  80  * @return An Eina_List* of @p item's items
  81  */
  82 EAPI const Eina_List             *elm_menu_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  83
  84 /**
  85  * @brief Get the Evas_Object of an Elm_Object_Item
  86  *
  87  * @param it The menu item object.
  88  * @return The edje object containing the swallowed content
  89  *
  90  * @warning Don't manipulate this object!
  91  *
  92  */
  93 EAPI Evas_Object                 *elm_menu_item_object_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
  94
  95 /**
  96  * @brief Add an item at the end of the given menu widget
  97  *
  98  * @param obj The menu object.
  99  * @param parent The parent menu item (optional)
 100  * @param icon An icon display on the item. The icon will be destryed by the menu.
 101  * @param label The label of the item.
 102  * @param func Function called when the user select the item.
 103  * @param data Data sent by the callback.
 104  * @return Returns the new item.
 105  */
 106 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) EINA_ARG_NONNULL(1);
 107
 108 /**
 109  * @brief Add an object swallowed in an item at the end of the given menu
 110  * widget
 111  *
 112  * @param obj The menu object.
 113  * @param parent The parent menu item (optional)
 114  * @param subobj The object to swallow
 115  * @param func Function called when the user select the item.
 116  * @param data Data sent by the callback.
 117  * @return Returns the new item.
 118  *
 119  * Add an evas object as an item to the menu.
 120  */
 121 EAPI Elm_Object_Item             *elm_menu_item_add_object(Evas_Object *obj, Elm_Object_Item *parent, Evas_Object *subobj, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 122
 123 /**
 124  * @brief Set the label of a menu item
 125  *
 126  * @param it The menu item object.
 127  * @param label The label to set for @p item
 128  *
 129  * @warning Don't use this funcion on items created with
 130  * elm_menu_item_add_object() or elm_menu_item_separator_add().
 131  *
 132  * @deprecated Use elm_object_item_text_set() instead
 133  */
 134 EINA_DEPRECATED EAPI void         elm_menu_item_label_set(Elm_Object_Item *it, const char *label) EINA_ARG_NONNULL(1);
 135
 136 /**
 137  * @brief Get the label of a menu item
 138  *
 139  * @param it The menu item object.
 140  * @return The label of @p item
 141  * @deprecated Use elm_object_item_text_get() instead
 142  */
 143 EINA_DEPRECATED EAPI const char  *elm_menu_item_label_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 144
 145 /**
 146  * @brief Set the icon of a menu item to the standard icon with name @p icon
 147  *
 148  * @param it The menu item object.
 149  * @param icon The icon object to set for the content of @p item
 150  *
 151  * Once this icon is set, any previously set icon will be deleted.
 152  */
 153 EAPI void                         elm_menu_item_object_icon_name_set(Elm_Object_Item *it, const char *icon) EINA_ARG_NONNULL(1, 2);
 154
 155 /**
 156  * @brief Get the string representation from the icon of a menu item
 157  *
 158  * @param it The menu item object.
 159  * @return The string representation of @p item's icon or NULL
 160  *
 161  * @see elm_menu_item_object_icon_name_set()
 162  */
 163 EAPI const char                  *elm_menu_item_object_icon_name_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 164
 165 /**
 166  * @brief Set the content object of a menu item
 167  *
 168  * @param it The menu item object
 169  * @param The content object or NULL
 170  * @return EINA_TRUE on success, else EINA_FALSE
 171  *
 172  * Use this function to change the object swallowed by a menu item, deleting
 173  * any previously swallowed object.
 174  *
 175  * @deprecated Use elm_object_item_content_set() instead
 176  */
 177 EINA_DEPRECATED EAPI Eina_Bool    elm_menu_item_object_content_set(Elm_Object_Item *it, Evas_Object *obj) EINA_ARG_NONNULL(1);
 178
 179 /**
 180  * @brief Get the content object of a menu item
 181  *
 182  * @param it The menu item object
 183  * @return The content object or NULL
 184  * @note If @p item was added with elm_menu_item_add_object, this
 185  * function will return the object passed, else it will return the
 186  * icon object.
 187  *
 188  * @see elm_menu_item_object_content_set()
 189  *
 190  * @deprecated Use elm_object_item_content_get() instead
 191  */
 192 EINA_DEPRECATED EAPI Evas_Object *elm_menu_item_object_content_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 193
 194 /**
 195  * @brief Set the selected state of @p item.
 196  *
 197  * @param it The menu item object.
 198  * @param selected The selected/unselected state of the item
 199  */
 200 EAPI void                         elm_menu_item_selected_set(Elm_Object_Item *it, Eina_Bool selected) EINA_ARG_NONNULL(1);
 201
 202 /**
 203  * @brief Get the selected state of @p item.
 204  *
 205  * @param it The menu item object.
 206  * @return The selected/unselected state of the item
 207  *
 208  * @see elm_menu_item_selected_set()
 209  */
 210 EAPI Eina_Bool                    elm_menu_item_selected_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 211
 212 /**
 213  * @brief Set the disabled state of @p item.
 214  *
 215  * @param it The menu item object.
 216  * @param disabled The enabled/disabled state of the item
 217  * @deprecated Use elm_object_item_disabled_set() instead
 218  */
 219 EINA_DEPRECATED EAPI void         elm_menu_item_disabled_set(Elm_Object_Item *it, Eina_Bool disabled) EINA_ARG_NONNULL(1);
 220
 221 /**
 222  * @brief Get the disabled state of @p item.
 223  *
 224  * @param it The menu item object.
 225  * @return The enabled/disabled state of the item
 226  *
 227  * @see elm_menu_item_disabled_set()
 228  * @deprecated Use elm_object_item_disabled_get() instead
 229  */
 230 EINA_DEPRECATED EAPI Eina_Bool    elm_menu_item_disabled_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 231
 232 /**
 233  * @brief Add a separator item to menu @p obj under @p parent.
 234  *
 235  * @param obj The menu object
 236  * @param parent The item to add the separator under
 237  * @return The created item or NULL on failure
 238  *
 239  * This is item is a @ref Separator.
 240  */
 241 EAPI Elm_Object_Item             *elm_menu_item_separator_add(Evas_Object *obj, Elm_Object_Item *parent) EINA_ARG_NONNULL(1);
 242
 243 /**
 244  * @brief Returns whether @p item is a separator.
 245  *
 246  * @param it The item to check
 247  * @return If true, @p item is a separator
 248  *
 249  * @see elm_menu_item_separator_add()
 250  */
 251 EAPI Eina_Bool                    elm_menu_item_is_separator(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 252
 253 /**
 254  * @brief Deletes an item from the menu.
 255  *
 256  * @param it The item to delete.
 257  *
 258  * @see elm_menu_item_add()
 259  */
 260 EAPI void                         elm_menu_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 261
 262 /**
 263  * @brief Set the function called when a menu item is deleted.
 264  *
 265  * @param it The item to set the callback on
 266  * @param func The function called
 267  *
 268  * @see elm_menu_item_add()
 269  * @see elm_menu_item_del()
 270  */
 271 EAPI void                         elm_menu_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
 272
 273 /**
 274  * @brief Returns the data associated with menu item @p item.
 275  *
 276  * @param it The item
 277  * @return The data associated with @p item or NULL if none was set.
 278  *
 279  * This is the data set with elm_menu_add() or elm_menu_item_data_set().
 280  *
 281  * @deprecated Use elm_object_item_data_get() instead
 282  */
 283 EINA_DEPRECATED EAPI void        *elm_menu_item_data_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 284
 285 /**
 286  * @brief Sets the data to be associated with menu item @p item.
 287  *
 288  * @param it The item
 289  * @param data The data to be associated with @p item
 290  *
 291  * @deprecated Use elm_object_item_data_set() instead
 292  */
 293 EINA_DEPRECATED EAPI void         elm_menu_item_data_set(Elm_Object_Item *it, const void *data) EINA_ARG_NONNULL(1);
 294
 295 /**
 296  * @brief Returns a list of @p item's subitems.
 297  *
 298  * @param it The item
 299  * @return An Eina_List* of @p item's subitems
 300  *
 301  * @see elm_menu_add()
 302  */
 303 EAPI const Eina_List             *elm_menu_item_subitems_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 304
 305 /**
 306  * @brief Get the position of a menu item
 307  *
 308  * @param it The menu item
 309  * @return The item's index
 310  *
 311  * This function returns the index position of a menu item in a menu.
 312  * For a sub-menu, this number is relative to the first item in the sub-menu.
 313  *
 314  * @note Index values begin with 0
 315  */
 316 EAPI unsigned int                 elm_menu_item_index_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
 317
 318 /**
 319  * @brief @brief Return a menu item's owner menu
 320  *
 321  * @param it The menu item
 322  * @return The menu object owning @p item, or NULL on failure
 323  *
 324  * Use this function to get the menu object owning an item.
 325  */
 326 EAPI Evas_Object                 *elm_menu_item_menu_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
 327
 328 /**
 329  * @brief Get the selected item in the menu
 330  *
 331  * @param obj The menu object
 332  * @return The selected item, or NULL if none
 333  *
 334  * @see elm_menu_item_selected_get()
 335  * @see elm_menu_item_selected_set()
 336  */
 337 EAPI Elm_Object_Item             *elm_menu_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 338
 339 /**
 340  * @brief Get the last item in the menu
 341  *
 342  * @param obj The menu object
 343  * @return The last item, or NULL if none
 344  */
 345 EAPI Elm_Object_Item             *elm_menu_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 346
 347 /**
 348  * @brief Get the first item in the menu
 349  *
 350  * @param obj The menu object
 351  * @return The first item, or NULL if none
 352  */
 353 EAPI Elm_Object_Item             *elm_menu_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 354
 355 /**
 356  * @brief Get the next item in the menu.
 357  *
 358  * @param it The menu item object.
 359  * @return The item after it, or NULL if none
 360  */
 361 EAPI Elm_Object_Item             *elm_menu_item_next_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 362
 363 /**
 364  * @brief Get the previous item in the menu.
 365  *
 366  * @param it The menu item object.
 367  * @return The item before it, or NULL if none
 368  */
 369 EAPI Elm_Object_Item             *elm_menu_item_prev_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 370
 371 /**
 372  * @}
 373  */