[Elementary.h] Add docs for menu

diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in
index 86e3874..a4601d9 100644 (file)
--- a/src/lib/Elementary.h.in
+++ b/src/lib/Elementary.h.in
@@ -15392,31 +15392,211 @@ extern "C" {
     * @}
     */
 
-   /* menu */
+   /**
+    * @defgroup Menu Menu
+    *
+    * @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
+    * 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.
+    *             event_info is NULL.
+    *
+    * @see @ref tutorial_menu
+    * @{
+    */
    typedef struct _Elm_Menu_Item Elm_Menu_Item; /**< Item of Elm_Menu. Sub-type of Elm_Widget_Item */
+   /**
+    * @brief Add 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 obj The menu object.
+    * @param parent The new parent.
+    */
    EAPI void               elm_menu_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the parent for the given menu widget
+    *
+    * @param obj The menu object.
+    * @return The parent.
+    *
+    * @see elm_menu_parent_set()
+    */
    EAPI Evas_Object       *elm_menu_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Move the menu to a new position
+    *
+    * @param obj The menu object.
+    * @param x The new position.
+    * @param y The new position.
+    *
+    * 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
+    *
+    * Hides the menu and all it's sub-menus.
+    */
    EAPI void               elm_menu_close(Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Returns a list of @p item's items.
+    *
+    * @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_Menu_Item
+    *
+    * @param item The menu item object.
+    * @return The edje object containing the swallowed content
+    *
+    * @warning Don't manipulate this object!
+    */
    EAPI Evas_Object       *elm_menu_item_object_get(const Elm_Menu_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 A 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_Menu_Item     *elm_menu_item_add(Evas_Object *obj, Elm_Menu_Item *parent, const char *icon, const char *label, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the label of a menu item
+    *
+    * @param item The menu item object.
+    * @param label The label to set for @p item
+    *
+    * @warning Don't use this funcion on items created with
+    * elm_menu_item_add_object() or elm_menu_item_separator_add().
+    */
    EAPI void               elm_menu_item_label_set(Elm_Menu_Item *item, const char *label) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the label of a menu item
+    *
+    * @param item The menu item object.
+    * @return The label of @p item
+    */
    EAPI const char        *elm_menu_item_label_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
    EAPI void               elm_menu_item_icon_set(Elm_Menu_Item *item, const char *icon) EINA_ARG_NONNULL(1, 2);
    EAPI const char        *elm_menu_item_icon_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
    EAPI const Evas_Object *elm_menu_item_object_icon_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
+
+   /**
+    * @brief Set the selected state of @p item.
+    *
+    * @param item The menu item object.
+    * @param selected The selected/unselected state of the item
+    */
    EAPI void               elm_menu_item_selected_set(Elm_Menu_Item *item, Eina_Bool selected) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the selected state of @p item.
+    *
+    * @param item 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_Menu_Item *item) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the disabled state of @p item.
+    *
+    * @param item The menu item object.
+    * @param disabled The enabled/disabled state of the item
+    */
    EAPI void               elm_menu_item_disabled_set(Elm_Menu_Item *item, Eina_Bool disabled) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the disabled state of @p item.
+    *
+    * @param item The menu item object.
+    * @return The enabled/disabled state of the item
+    *
+    * @see elm_menu_item_disabled_set()
+    */
    EAPI Eina_Bool          elm_menu_item_disabled_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Add a separator item to menu @p obj under @p parent.
+    *
+    * @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.
+    */
    EAPI Elm_Menu_Item     *elm_menu_item_separator_add(Evas_Object *obj, Elm_Menu_Item *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Returns whether @p item is a separator.
+    *
+    * @param item The item to check
+    * @return If true, @p item is a separator
+    *
+    * @see elm_menu_item_separator_add()
+    */
    EAPI Eina_Bool          elm_menu_item_is_separator(Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Deletes an item from the menu.
+    *
+    * @param item The item to delete.
+    *
+    * @see elm_menu_item_add()
+    */
    EAPI void               elm_menu_item_del(Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the function called when a menu item is deleted.
+    *
+    * @param item The item to set the callback on
+    * @param func The function called
+    *
+    * @see elm_menu_item_add()
+    * @see elm_menu_item_del()
+    */
    EAPI void               elm_menu_item_del_cb_set(Elm_Menu_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Returns the data associated with menu item @p item.
+    *
+    * @param item 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().
+    */
    EAPI void              *elm_menu_item_data_get(const Elm_Menu_Item *it) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Sets the data to be associated with menu item @p item.
+    *
+    * @param item The item
+    * @param data The data to be associated with @p item
+    */
    EAPI void               elm_menu_item_data_set(Elm_Menu_Item *item, const void *data) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Returns a list of @p item's subitems.
+    *
+    * @param item The item
+    * @return An Eina_List* of @p item's subitems
+    *
+    * @see elm_menu_add()
+    */
    EAPI const Eina_List   *elm_menu_item_subitems_get(const Elm_Menu_Item *item) EINA_ARG_NONNULL(1);
    EAPI const Elm_Menu_Item *elm_menu_selected_item_get(const Evas_Object * obj) EINA_ARG_NONNULL(1);
    EAPI const Elm_Menu_Item *elm_menu_last_item_get(const Evas_Object * obj) EINA_ARG_NONNULL(1);
@@ -15424,8 +15604,8 @@ extern "C" {
    EAPI const Elm_Menu_Item *elm_menu_item_next_get(const Elm_Menu_Item *it) EINA_ARG_NONNULL(1);
    EAPI const Elm_Menu_Item *elm_menu_item_prev_get(const Elm_Menu_Item *it) EINA_ARG_NONNULL(1);
 
-   /* smart callbacks called:
-    * "clicked" - the user clicked the empty space in the menu to dismiss. event_info is NULL.
+   /**
+    * @}
     */
 
    /* list */