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 label of a menu item
 123     *
 124     * @param it The menu item object.
 125     * @param label The label to set for @p item
 126     *
 127     * @warning Don't use this funcion on items created with
 128     * elm_menu_item_add_object() or elm_menu_item_separator_add().
 129     *
 130     * @deprecated Use elm_object_item_text_set() instead
 131     */
 132    EINA_DEPRECATED EAPI void               elm_menu_item_label_set(Elm_Object_Item *it, const char *label) EINA_ARG_NONNULL(1);
 133
 134    /**
 135     * @brief Get the label of a menu item
 136     *
 137     * @param it The menu item object.
 138     * @return The label of @p item
 139          * @deprecated Use elm_object_item_text_get() instead
 140     */
 141    EINA_DEPRECATED EAPI const char        *elm_menu_item_label_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 142
 143    /**
 144     * @brief Set the icon of a menu item to the standard icon with name @p icon
 145     *
 146     * @param it The menu item object.
 147     * @param icon The icon object to set for the content of @p item
 148     *
 149     * Once this icon is set, any previously set icon will be deleted.
 150     */
 151    EAPI void               elm_menu_item_object_icon_name_set(Elm_Object_Item *it, const char *icon) EINA_ARG_NONNULL(1, 2);
 152
 153    /**
 154     * @brief Get the string representation from the icon of a menu item
 155     *
 156     * @param it The menu item object.
 157     * @return The string representation of @p item's icon or NULL
 158     *
 159     * @see elm_menu_item_object_icon_name_set()
 160     */
 161    EAPI const char        *elm_menu_item_object_icon_name_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 162
 163    /**
 164     * @brief Set the content object of a menu item
 165     *
 166     * @param it The menu item object
 167     * @param The content object or NULL
 168     * @return EINA_TRUE on success, else EINA_FALSE
 169     *
 170     * Use this function to change the object swallowed by a menu item, deleting
 171     * any previously swallowed object.
 172     *
 173     * @deprecated Use elm_object_item_content_set() instead
 174     */
 175    EINA_DEPRECATED EAPI Eina_Bool          elm_menu_item_object_content_set(Elm_Object_Item *it, Evas_Object *obj) EINA_ARG_NONNULL(1);
 176
 177    /**
 178     * @brief Get the content object of a menu item
 179     *
 180     * @param it The menu item object
 181     * @return The content object or NULL
 182     * @note If @p item was added with elm_menu_item_add_object, this
 183     * function will return the object passed, else it will return the
 184     * icon object.
 185     *
 186     * @see elm_menu_item_object_content_set()
 187     *
 188     * @deprecated Use elm_object_item_content_get() instead
 189     */
 190    EINA_DEPRECATED EAPI Evas_Object *elm_menu_item_object_content_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 191
 192    /**
 193     * @brief Set the selected state of @p item.
 194     *
 195     * @param it The menu item object.
 196     * @param selected The selected/unselected state of the item
 197     */
 198    EAPI void               elm_menu_item_selected_set(Elm_Object_Item *it, Eina_Bool selected) EINA_ARG_NONNULL(1);
 199
 200    /**
 201     * @brief Get the selected state of @p item.
 202     *
 203     * @param it The menu item object.
 204     * @return The selected/unselected state of the item
 205     *
 206     * @see elm_menu_item_selected_set()
 207     */
 208    EAPI Eina_Bool          elm_menu_item_selected_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 209
 210    /**
 211     * @brief Set the disabled state of @p item.
 212     *
 213     * @param it The menu item object.
 214     * @param disabled The enabled/disabled state of the item
 215     * @deprecated Use elm_object_item_disabled_set() instead
 216     */
 217    EINA_DEPRECATED EAPI void               elm_menu_item_disabled_set(Elm_Object_Item *it, Eina_Bool disabled) EINA_ARG_NONNULL(1);
 218
 219    /**
 220     * @brief Get the disabled state of @p item.
 221     *
 222     * @param it The menu item object.
 223     * @return The enabled/disabled state of the item
 224     *
 225     * @see elm_menu_item_disabled_set()
 226     * @deprecated Use elm_object_item_disabled_get() instead
 227     */
 228    EINA_DEPRECATED EAPI Eina_Bool          elm_menu_item_disabled_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 229
 230    /**
 231     * @brief Add a separator item to menu @p obj under @p parent.
 232     *
 233     * @param obj The menu object
 234     * @param parent The item to add the separator under
 235     * @return The created item or NULL on failure
 236     *
 237     * This is item is a @ref Separator.
 238     */
 239    EAPI Elm_Object_Item     *elm_menu_item_separator_add(Evas_Object *obj, Elm_Object_Item *parent) EINA_ARG_NONNULL(1);
 240
 241    /**
 242     * @brief Returns whether @p item is a separator.
 243     *
 244     * @param it The item to check
 245     * @return If true, @p item is a separator
 246     *
 247     * @see elm_menu_item_separator_add()
 248     */
 249    EAPI Eina_Bool          elm_menu_item_is_separator(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 250
 251    /**
 252     * @brief Deletes an item from the menu.
 253     *
 254     * @param it The item to delete.
 255     *
 256     * @see elm_menu_item_add()
 257     */
 258    EAPI void               elm_menu_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 259
 260    /**
 261     * @brief Set the function called when a menu item is deleted.
 262     *
 263     * @param it The item to set the callback on
 264     * @param func The function called
 265     *
 266     * @see elm_menu_item_add()
 267     * @see elm_menu_item_del()
 268     */
 269    EAPI void               elm_menu_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
 270
 271    /**
 272     * @brief Returns the data associated with menu item @p item.
 273     *
 274     * @param it The item
 275     * @return The data associated with @p item or NULL if none was set.
 276     *
 277     * This is the data set with elm_menu_add() or elm_menu_item_data_set().
 278     *
 279     * @deprecated Use elm_object_item_data_get() instead
 280     */
 281    EINA_DEPRECATED EAPI void              *elm_menu_item_data_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 282
 283    /**
 284     * @brief Sets the data to be associated with menu item @p item.
 285     *
 286     * @param it The item
 287     * @param data The data to be associated with @p item
 288     *
 289     * @deprecated Use elm_object_item_data_set() instead
 290     */
 291    EINA_DEPRECATED EAPI void               elm_menu_item_data_set(Elm_Object_Item *it, const void *data) EINA_ARG_NONNULL(1);
 292
 293    /**
 294     * @brief Returns a list of @p item's subitems.
 295     *
 296     * @param it The item
 297     * @return An Eina_List* of @p item's subitems
 298     *
 299     * @see elm_menu_add()
 300     */
 301    EAPI const Eina_List   *elm_menu_item_subitems_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 302
 303    /**
 304     * @brief Get the position of a menu item
 305     *
 306     * @param it The menu item
 307     * @return The item's index
 308     *
 309     * This function returns the index position of a menu item in a menu.
 310     * For a sub-menu, this number is relative to the first item in the sub-menu.
 311     *
 312     * @note Index values begin with 0
 313     */
 314    EAPI unsigned int       elm_menu_item_index_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
 315
 316    /**
 317     * @brief @brief Return a menu item's owner menu
 318     *
 319     * @param it The menu item
 320     * @return The menu object owning @p item, or NULL on failure
 321     *
 322     * Use this function to get the menu object owning an item.
 323     */
 324    EAPI Evas_Object       *elm_menu_item_menu_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
 325
 326    /**
 327     * @brief Get the selected item in the menu
 328     *
 329     * @param obj The menu object
 330     * @return The selected item, or NULL if none
 331     *
 332     * @see elm_menu_item_selected_get()
 333     * @see elm_menu_item_selected_set()
 334     */
 335    EAPI Elm_Object_Item *elm_menu_selected_item_get(const Evas_Object * obj) EINA_ARG_NONNULL(1);
 336
 337    /**
 338     * @brief Get the last item in the menu
 339     *
 340     * @param obj The menu object
 341     * @return The last item, or NULL if none
 342     */
 343    EAPI Elm_Object_Item *elm_menu_last_item_get(const Evas_Object * obj) EINA_ARG_NONNULL(1);
 344
 345    /**
 346     * @brief Get the first item in the menu
 347     *
 348     * @param obj The menu object
 349     * @return The first item, or NULL if none
 350     */
 351    EAPI Elm_Object_Item *elm_menu_first_item_get(const Evas_Object * obj) EINA_ARG_NONNULL(1);
 352
 353    /**
 354     * @brief Get the next item in the menu.
 355     *
 356     * @param it The menu item object.
 357     * @return The item after it, or NULL if none
 358     */
 359    EAPI Elm_Object_Item *elm_menu_item_next_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 360
 361    /**
 362     * @brief Get the previous item in the menu.
 363     *
 364     * @param it The menu item object.
 365     * @return The item before it, or NULL if none
 366     */
 367    EAPI Elm_Object_Item *elm_menu_item_prev_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 368
 369    /**
 370     * @}
 371     */
 372