src/lib/elm_menu.h

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