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