src/lib/elm_menu.h

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