/**
+ * @internal
* @defgroup Menu Menu
+ * @ingroup Elementary
+ *
+ * @image html menu_inheritance_tree.png
+ * @image latex menu_inheritance_tree.eps
*
* @image html img/widget/menu/preview-00.png
* @image latex img/widget/menu/preview-00.eps
*
* A menu is a list of items displayed above its parent. When the menu is
- * showing its parent is darkened. Each item can have a sub-menu. The menu
+ * showing, its parent is darkened. Each item can have a sub-menu. The menu
* object can be used to display a menu on a right click event, in a toolbar,
* anywhere.
*
* Signals that you can add callbacks for are:
- * @li "clicked" - the user clicked the empty space in the menu to dismiss.
+ * @li "clicked" - The user clicked the empty space in the menu to dismiss.
+ *
+ * The default content parts of the menu items that you can use are:
+ * @li "default" - The main content of the menu item.
*
- * Default contents parts of the menu items that you can use for are:
- * @li "default" - A main content of the menu item
+ * The default text parts of the menu items that you can use are:
+ * @li "default" - The label in the menu item.
*
- * Default text parts of the menu items that you can use for are:
- * @li "default" - label in the menu item
+ * Supported common elm_object_item APIs.
+ * @li @ref elm_object_item_part_text_set
+ * @li @ref elm_object_item_part_text_get
+ * @li @ref elm_object_item_part_content_set
+ * @li @ref elm_object_item_part_content_get
+ * @li @ref elm_object_item_disabled_set
+ * @li @ref elm_object_item_disabled_get
+ * @li @ref elm_object_item_signal_emit
*
- * @see @ref tutorial_menu
* @{
*/
/**
- * @brief Add a new menu to the parent
+ * @brief Adds a new menu to the parent.
*
- * @param parent The parent object.
- * @return The new object or NULL if it cannot be created.
- */
-EAPI Evas_Object *
- elm_menu_add(Evas_Object *parent)
-EINA_ARG_NONNULL(1);
-
-/**
- * @brief Set the parent for the given menu widget
+ * @param[in] parent The parent object
+ * @return The new object, otherwise @c NULL if it cannot be created
*
- * @param obj The menu object.
- * @param parent The new parent.
+ * @ingroup Menu
*/
-EAPI void elm_menu_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+EAPI Evas_Object *elm_menu_add(Evas_Object *parent);
/**
- * @brief Get the parent for the given menu widget
+ * @brief Sets the parent for the given menu widget.
*
- * @param obj The menu object.
- * @return The parent.
+ * @param[in] obj The menu object
+ * @param[in] parent The new parent
*
- * @see elm_menu_parent_set()
+ * @ingroup Menu
*/
-EAPI Evas_Object *elm_menu_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+EAPI void elm_menu_parent_set(Evas_Object *obj, Evas_Object *parent);
/**
- * @brief Move the menu to a new position
+ * @brief Gets the parent for the given menu widget.
*
- * @param obj The menu object.
- * @param x The new position.
- * @param y The new position.
+ * @param[in] obj The menu object
+ * @return The parent
*
- * Sets the top-left position of the menu to (@p x,@p y).
- *
- * @note @p x and @p y coordinates are relative to parent.
- */
-EAPI void elm_menu_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Close a opened menu
- *
- * @param obj the menu object
- * @return void
+ * @see elm_menu_parent_set()
*
- * Hides the menu and all it's sub-menus.
+ * @ingroup Menu
*/
-EAPI void elm_menu_close(Evas_Object *obj) EINA_ARG_NONNULL(1);
+EAPI Evas_Object *elm_menu_parent_get(const Evas_Object *obj);
/**
- * @brief Returns a list of @p item's items.
+ * @brief Moves the menu to a new position.
*
- * @param obj The menu object
- * @return An Eina_List* of @p item's items
- */
-EAPI const Eina_List *elm_menu_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the Evas_Object of an Elm_Object_Item
+ * @details This sets the top-left position of the menu to (@a x,@a y).
*
- * @param it The menu item object.
- * @return The edje object containing the swallowed content
+ * @remarks The @a x and @a y coordinates are relative to the parent.
*
- * @warning Don't manipulate this object!
+ * @param[in] obj The menu object
+ * @param[in] x The new position
+ * @param[in] y The new position
*
+ * @ingroup Menu
*/
-EAPI Evas_Object *elm_menu_item_object_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Add an item at the end of the given menu widget
- *
- * @param obj The menu object.
- * @param parent The parent menu item (optional)
- * @param icon An icon display on the item. The icon will be destryed by the menu.
- * @param label The label of the item.
- * @param func Function called when the user select the item.
- * @param data Data sent by the callback.
- * @return Returns the new item.
- */
-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);
+EAPI void elm_menu_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y);
/**
- * @brief Add an object swallowed in an item at the end of the given menu
- * widget
+ * @brief Closes an opened menu.
*
- * @param obj The menu object.
- * @param parent The parent menu item (optional)
- * @param subobj The object to swallow
- * @param func Function called when the user select the item.
- * @param data Data sent by the callback.
- * @return Returns the new item.
+ * @details This hides the menu and all it's sub-menus.
*
- * Add an evas object as an item to the menu.
+ * @param[in] obj The menu object
+ * @return A void value
+ *
+ * @ingroup Menu
*/
-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);
+EAPI void elm_menu_close(Evas_Object *obj);
/**
- * @brief Set the label of a menu item
- *
- * @param it The menu item object.
- * @param label The label to set for @p item
+ * @brief Gets a list of the @a it items.
*
- * @warning Don't use this funcion on items created with
- * elm_menu_item_add_object() or elm_menu_item_separator_add().
+ * @param[in] obj The menu object
+ * @return An Eina_List* of the @a it items
*
- * @deprecated Use elm_object_item_text_set() instead
+ * @ingroup Menu
*/
-EINA_DEPRECATED EAPI void elm_menu_item_label_set(Elm_Object_Item *it, const char *label) EINA_ARG_NONNULL(1);
+EAPI const Eina_List *elm_menu_items_get(const Evas_Object *obj);
/**
- * @brief Get the label of a menu item
+ * @brief Gets the Evas_Object of an Elm_Object_Item.
*
- * @param it The menu item object.
- * @return The label of @p item
- * @deprecated Use elm_object_item_text_get() instead
- */
-EINA_DEPRECATED EAPI const char *elm_menu_item_label_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Set the icon of a menu item to the standard icon with name @p icon
+ * @remarks Don't manipulate this object.
*
- * @param it The menu item object.
- * @param icon The icon object to set for the content of @p item
+ * @param[in] it The menu item object
+ * @return The edje object containing the swallowed content
*
- * Once this icon is set, any previously set icon will be deleted.
+ * @ingroup Menu
*/
-EAPI void elm_menu_item_object_icon_name_set(Elm_Object_Item *it, const char *icon) EINA_ARG_NONNULL(1, 2);
+EAPI Evas_Object *elm_menu_item_object_get(const Elm_Object_Item *it);
/**
- * @brief Get the string representation from the icon of a menu item
+ * @brief Adds an item at the end of the given menu widget.
*
- * @param it The menu item object.
- * @return The string representation of @p item's icon or NULL
+ * @param[in] obj The menu object
+ * @param[in] parent The parent menu item (optional)
+ * @param[in] icon An icon display on the item \n
+ * The icon is destroyed by the menu.
+ * @param[in] label The label of the item
+ * @param[in] func The function called when the user selects the item
+ * @param[in] data The data sent by the callback
+ * @return The new item
*
- * @see elm_menu_item_object_icon_name_set()
+ * @ingroup Menu
*/
-EAPI const char *elm_menu_item_object_icon_name_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+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);
/**
- * @brief Set the content object of a menu item
+ * @brief Sets the icon of a menu item to the standard icon with name @a icon.
*
- * @param it The menu item object
- * @param The content object or NULL
- * @return EINA_TRUE on success, else EINA_FALSE
+ * @remarks Once this icon is set, any previously set icon is deleted.
*
- * Use this function to change the object swallowed by a menu item, deleting
- * any previously swallowed object.
+ * @param[in] it The menu item object
+ * @param[in] icon The name of the icon object to set for the content of @a it
*
- * @deprecated Use elm_object_item_content_set() instead
+ * @ingroup Menu
*/
-EINA_DEPRECATED EAPI Eina_Bool elm_menu_item_object_content_set(Elm_Object_Item *it, Evas_Object *obj) EINA_ARG_NONNULL(1);
+EAPI void elm_menu_item_icon_name_set(Elm_Object_Item *it, const char *icon);
/**
- * @brief Get the content object of a menu item
+ * @brief Gets the string representation from the icon of a menu item.
*
- * @param it The menu item object
- * @return The content object or NULL
- * @note If @p item was added with elm_menu_item_add_object, this
- * function will return the object passed, else it will return the
- * icon object.
+ * @param[in] it The menu item object
+ * @return The string representation of the @a it icon, otherwise @c NULL
*
- * @see elm_menu_item_object_content_set()
+ * @see elm_menu_item_icon_name_set()
*
- * @deprecated Use elm_object_item_content_get() instead
+ * @ingroup Menu
*/
-EINA_DEPRECATED EAPI Evas_Object *elm_menu_item_object_content_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+EAPI const char *elm_menu_item_icon_name_get(const Elm_Object_Item *it);
/**
- * @brief Set the selected state of @p item.
+ * @brief Sets the selected state of @a it.
*
- * @param it The menu item object.
- * @param selected The selected/unselected state of the item
+ * @param[in] it The menu item object
+ * @param[in] selected The selected/unselected state of the item
+ *
+ * @ingroup Menu
*/
-EAPI void elm_menu_item_selected_set(Elm_Object_Item *it, Eina_Bool selected) EINA_ARG_NONNULL(1);
+EAPI void elm_menu_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
/**
- * @brief Get the selected state of @p item.
+ * @brief Gets the selected state of @a it.
*
- * @param it The menu item object.
+ * @param[in] it The menu item object
* @return The selected/unselected state of the item
*
* @see elm_menu_item_selected_set()
- */
-EAPI Eina_Bool elm_menu_item_selected_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Set the disabled state of @p item.
*
- * @param it The menu item object.
- * @param disabled The enabled/disabled state of the item
- * @deprecated Use elm_object_item_disabled_set() instead
+ * @ingroup Menu
*/
-EINA_DEPRECATED EAPI void elm_menu_item_disabled_set(Elm_Object_Item *it, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+EAPI Eina_Bool elm_menu_item_selected_get(const Elm_Object_Item *it);
/**
- * @brief Get the disabled state of @p item.
+ * @brief Adds a separator item to the menu @a obj under the @a parent.
*
- * @param it The menu item object.
- * @return The enabled/disabled state of the item
+ * @remarks This item is a @ref Separator.
*
- * @see elm_menu_item_disabled_set()
- * @deprecated Use elm_object_item_disabled_get() instead
- */
-EINA_DEPRECATED EAPI Eina_Bool elm_menu_item_disabled_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Add a separator item to menu @p obj under @p parent.
+ * @param[in] obj The menu object
+ * @param[in] parent The item to add the separator under
+ * @return The created item, otherwise @c NULL on failure
*
- * @param obj The menu object
- * @param parent The item to add the separator under
- * @return The created item or NULL on failure
- *
- * This is item is a @ref Separator.
+ * @ingroup Menu
*/
-EAPI Elm_Object_Item *elm_menu_item_separator_add(Evas_Object *obj, Elm_Object_Item *parent) EINA_ARG_NONNULL(1);
+EAPI Elm_Object_Item *elm_menu_item_separator_add(Evas_Object *obj, Elm_Object_Item *parent);
/**
- * @brief Returns whether @p item is a separator.
+ * @brief Returns whether @a it is a separator.
*
- * @param it The item to check
- * @return If true, @p item is a separator
+ * @param[in] it The item to check
+ * @return If @c true @a it is a separator,
+ * otherwise @c false
*
* @see elm_menu_item_separator_add()
- */
-EAPI Eina_Bool elm_menu_item_is_separator(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Deletes an item from the menu.
*
- * @param it The item to delete.
- *
- * @see elm_menu_item_add()
+ * @ingroup Menu
*/
-EAPI void elm_menu_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+EAPI Eina_Bool elm_menu_item_is_separator(Elm_Object_Item *it);
/**
- * @brief Set the function called when a menu item is deleted.
+ * @brief Returns a list of the @a it subitems.
*
- * @param it The item to set the callback on
- * @param func The function called
+ * @param[in] it The item
+ * @return An Eina_List* of the @a it subitems
*
- * @see elm_menu_item_add()
- * @see elm_menu_item_del()
- */
-EAPI void elm_menu_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Returns the data associated with menu item @p item.
- *
- * @param it The item
- * @return The data associated with @p item or NULL if none was set.
- *
- * This is the data set with elm_menu_add() or elm_menu_item_data_set().
+ * @see elm_menu_add()
*
- * @deprecated Use elm_object_item_data_get() instead
+ * @ingroup Menu
*/
-EINA_DEPRECATED EAPI void *elm_menu_item_data_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+EAPI const Eina_List *elm_menu_item_subitems_get(const Elm_Object_Item *it);
/**
- * @brief Sets the data to be associated with menu item @p item.
+ * @brief Gets the position of a menu item.
*
- * @param it The item
- * @param data The data to be associated with @p item
+ * @details This function returns the index position of a menu item in a menu.
+ * For a sub-menu, this number is relative to the first item in the sub-menu.
*
- * @deprecated Use elm_object_item_data_set() instead
- */
-EINA_DEPRECATED EAPI void elm_menu_item_data_set(Elm_Object_Item *it, const void *data) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Returns a list of @p item's subitems.
+ * @remarks Index values begin with @c 0.
*
- * @param it The item
- * @return An Eina_List* of @p item's subitems
+ * @param[in] it The menu item
+ * @return The item's index
*
- * @see elm_menu_add()
+ * @ingroup Menu
*/
-EAPI const Eina_List *elm_menu_item_subitems_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+EAPI unsigned int elm_menu_item_index_get(const Elm_Object_Item *it);
/**
- * @brief Get the position of a menu item
+ * @brief Gets the selected item in the menu.
*
- * @param it The menu item
- * @return The item's index
+ * @param[in] obj The menu object
+ * @return The selected item, otherwise @c NULL if none are selected
*
- * This function returns the index position of a menu item in a menu.
- * For a sub-menu, this number is relative to the first item in the sub-menu.
+ * @see elm_menu_item_selected_get()
+ * @see elm_menu_item_selected_set()
*
- * @note Index values begin with 0
+ * @ingroup Menu
*/
-EAPI unsigned int elm_menu_item_index_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI Elm_Object_Item *elm_menu_selected_item_get(const Evas_Object *obj);
/**
- * @brief @brief Return a menu item's owner menu
+ * @brief Gets the last item in the menu.
*
- * @param it The menu item
- * @return The menu object owning @p item, or NULL on failure
+ * @param[in] obj The menu object
+ * @return The last item, otherwise @c NULL if none are present
*
- * Use this function to get the menu object owning an item.
+ * @ingroup Menu
*/
-EAPI Evas_Object *elm_menu_item_menu_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI Elm_Object_Item *elm_menu_last_item_get(const Evas_Object *obj);
/**
- * @brief Get the selected item in the menu
+ * @brief Gets the first item in the menu.
*
- * @param obj The menu object
- * @return The selected item, or NULL if none
+ * @param[in] obj The menu object
+ * @return The first item, otherwise @c NULL if none are present
*
- * @see elm_menu_item_selected_get()
- * @see elm_menu_item_selected_set()
+ * @ingroup Menu
*/
-EAPI Elm_Object_Item *elm_menu_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+EAPI Elm_Object_Item *elm_menu_first_item_get(const Evas_Object *obj);
/**
- * @brief Get the last item in the menu
+ * @brief Gets the next item in the menu.
*
- * @param obj The menu object
- * @return The last item, or NULL if none
- */
-EAPI Elm_Object_Item *elm_menu_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the first item in the menu
+ * @param[in] it The menu item object
+ * @return The item after @a it, otherwise @c NULL if none are present
*
- * @param obj The menu object
- * @return The first item, or NULL if none
+ * @ingroup Menu
*/
-EAPI Elm_Object_Item *elm_menu_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+EAPI Elm_Object_Item *elm_menu_item_next_get(const Elm_Object_Item *it);
/**
- * @brief Get the next item in the menu.
+ * @brief Gets the previous item in the menu.
*
- * @param it The menu item object.
- * @return The item after it, or NULL if none
- */
-EAPI Elm_Object_Item *elm_menu_item_next_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the previous item in the menu.
+ * @param[in] it The menu item object
+ * @return The item before @a it, otherwise @c NULL if none are present
*
- * @param it The menu item object.
- * @return The item before it, or NULL if none
+ * @ingroup Menu
*/
-EAPI Elm_Object_Item *elm_menu_item_prev_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
+EAPI Elm_Object_Item *elm_menu_item_prev_get(const Elm_Object_Item *it);
/**
* @}
projects / framework / uifw / elementary.git / blobdiff