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                 *elm_menu_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  32
  33 /**
  34  * @brief Set the parent for the given menu widget
  35  *
  36  * @param obj The menu object.
  37  * @param parent The new parent.
  38  */
  39 EAPI void                         elm_menu_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
  40
  41 /**
  42  * @brief Get the parent for the given menu widget
  43  *
  44  * @param obj The menu object.
  45  * @return The parent.
  46  *
  47  * @see elm_menu_parent_set()
  48  */
  49 EAPI Evas_Object                 *elm_menu_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  50
  51 /**
  52  * @brief Move the menu to a new position
  53  *
  54  * @param obj The menu object.
  55  * @param x The new position.
  56  * @param y The new position.
  57  *
  58  * Sets the top-left position of the menu to (@p x,@p y).
  59  *
  60  * @note @p x and @p y coordinates are relative to parent.
  61  */
  62 EAPI void                         elm_menu_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
  63
  64 /**
  65  * @brief Close a opened menu
  66  *
  67  * @param obj the menu object
  68  * @return void
  69  *
  70  * Hides the menu and all it's sub-menus.
  71  */
  72 EAPI void                         elm_menu_close(Evas_Object *obj) EINA_ARG_NONNULL(1);
  73
  74 /**
  75  * @brief Returns a list of @p item's items.
  76  *
  77  * @param obj The menu object
  78  * @return An Eina_List* of @p item's items
  79  */
  80 EAPI const Eina_List             *elm_menu_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  81
  82 /**
  83  * @brief Get the Evas_Object of an Elm_Object_Item
  84  *
  85  * @param it The menu item object.
  86  * @return The edje object containing the swallowed content
  87  *
  88  * @warning Don't manipulate this object!
  89  *
  90  */
  91 EAPI Evas_Object                 *elm_menu_item_object_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
  92
  93 /**
  94  * @brief Add an item at the end of the given menu widget
  95  *
  96  * @param obj The menu object.
  97  * @param parent The parent menu item (optional)
  98  * @param icon An icon display on the item. The icon will be destryed by the menu.
  99  * @param label The label of the item.
 100  * @param func Function called when the user select the item.
 101  * @param data Data sent by the callback.
 102  * @return Returns the new item.
 103  */
 104 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);
 105
 106 /**
 107  * @brief Add an object swallowed in an item at the end of the given menu
 108  * widget
 109  *
 110  * @param obj The menu object.
 111  * @param parent The parent menu item (optional)
 112  * @param subobj The object to swallow
 113  * @param func Function called when the user select the item.
 114  * @param data Data sent by the callback.
 115  * @return Returns the new item.
 116  *
 117  * Add an evas object as an item to the menu.
 118  */
 119 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);
 120
 121 /**
 122  * @brief Set the icon of a menu item to the standard icon with name @p icon
 123  *
 124  * @param it The menu item object.
 125  * @param icon The icon object to set for the content of @p item
 126  *
 127  * Once this icon is set, any previously set icon will be deleted.
 128  */
 129 EAPI void                         elm_menu_item_object_icon_name_set(Elm_Object_Item *it, const char *icon) EINA_ARG_NONNULL(1, 2);
 130
 131 /**
 132  * @brief Get the string representation from the icon of a menu item
 133  *
 134  * @param it The menu item object.
 135  * @return The string representation of @p item's icon or NULL
 136  *
 137  * @see elm_menu_item_object_icon_name_set()
 138  */
 139 EAPI const char                  *elm_menu_item_object_icon_name_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 140
 141 /**
 142  * @brief Set the selected state of @p item.
 143  *
 144  * @param it The menu item object.
 145  * @param selected The selected/unselected state of the item
 146  */
 147 EAPI void                         elm_menu_item_selected_set(Elm_Object_Item *it, Eina_Bool selected) EINA_ARG_NONNULL(1);
 148
 149 /**
 150  * @brief Get the selected state of @p item.
 151  *
 152  * @param it The menu item object.
 153  * @return The selected/unselected state of the item
 154  *
 155  * @see elm_menu_item_selected_set()
 156  */
 157 EAPI Eina_Bool                    elm_menu_item_selected_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 158
 159 /**
 160  * @brief Add a separator item to menu @p obj under @p parent.
 161  *
 162  * @param obj The menu object
 163  * @param parent The item to add the separator under
 164  * @return The created item or NULL on failure
 165  *
 166  * This is item is a @ref Separator.
 167  */
 168 EAPI Elm_Object_Item             *elm_menu_item_separator_add(Evas_Object *obj, Elm_Object_Item *parent) EINA_ARG_NONNULL(1);
 169
 170 /**
 171  * @brief Returns whether @p item is a separator.
 172  *
 173  * @param it The item to check
 174  * @return If true, @p item is a separator
 175  *
 176  * @see elm_menu_item_separator_add()
 177  */
 178 EAPI Eina_Bool                    elm_menu_item_is_separator(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 179
 180 /**
 181  * @brief Deletes an item from the menu.
 182  *
 183  * @param it The item to delete.
 184  *
 185  * @see elm_menu_item_add()
 186  */
 187 EAPI void                         elm_menu_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 188
 189 /**
 190  * @brief Set the function called when a menu item is deleted.
 191  *
 192  * @param it The item to set the callback on
 193  * @param func The function called
 194  *
 195  * @see elm_menu_item_add()
 196  * @see elm_menu_item_del()
 197  */
 198 EAPI void                         elm_menu_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
 199
 200 /**
 201  * @brief Returns a list of @p item's subitems.
 202  *
 203  * @param it The item
 204  * @return An Eina_List* of @p item's subitems
 205  *
 206  * @see elm_menu_add()
 207  */
 208 EAPI const Eina_List             *elm_menu_item_subitems_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 209
 210 /**
 211  * @brief Get the position of a menu item
 212  *
 213  * @param it The menu item
 214  * @return The item's index
 215  *
 216  * This function returns the index position of a menu item in a menu.
 217  * For a sub-menu, this number is relative to the first item in the sub-menu.
 218  *
 219  * @note Index values begin with 0
 220  */
 221 EAPI unsigned int                 elm_menu_item_index_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
 222
 223 /**
 224  * @brief @brief Return a menu item's owner menu
 225  *
 226  * @param it The menu item
 227  * @return The menu object owning @p item, or NULL on failure
 228  *
 229  * Use this function to get the menu object owning an item.
 230  */
 231 EAPI Evas_Object                 *elm_menu_item_menu_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
 232
 233 /**
 234  * @brief Get the selected item in the menu
 235  *
 236  * @param obj The menu object
 237  * @return The selected item, or NULL if none
 238  *
 239  * @see elm_menu_item_selected_get()
 240  * @see elm_menu_item_selected_set()
 241  */
 242 EAPI Elm_Object_Item             *elm_menu_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 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 EAPI Elm_Object_Item             *elm_menu_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 251
 252 /**
 253  * @brief Get the first item in the menu
 254  *
 255  * @param obj The menu object
 256  * @return The first item, or NULL if none
 257  */
 258 EAPI Elm_Object_Item             *elm_menu_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 259
 260 /**
 261  * @brief Get the next item in the menu.
 262  *
 263  * @param it The menu item object.
 264  * @return The item after it, or NULL if none
 265  */
 266 EAPI Elm_Object_Item             *elm_menu_item_next_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 267
 268 /**
 269  * @brief Get the previous item in the menu.
 270  *
 271  * @param it The menu item object.
 272  * @return The item before it, or NULL if none
 273  */
 274 EAPI Elm_Object_Item             *elm_menu_item_prev_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 275
 276 /**
 277  * @}
 278  */