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