[Elementary.h] Add documentation for notify

diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in
index 98156a3..31fb473 100644 (file)
--- a/src/lib/Elementary.h.in
+++ b/src/lib/Elementary.h.in
@@ -10097,35 +10097,174 @@ extern "C" {
     * "theme,changed" - when elm theme is changed.
     */
 
-   /* notify */
+   /**
+    * @defgroup Notify Notify
+    *
+    * @image html img/widget/notify/preview-00.png
+    * @image latex img/widget/notify/preview-00.eps
+    *
+    * Display a container in a particular region of the parent(top, bottom,
+    * etc).  A timeout can be set to automatically hide the notify. This is so
+    * that, after an evas_object_show() on a notify object, if a timeout was set
+    * on it, it will @b automatically get hidden after that time.
+    *
+    * Signals that you can add callbacks for are:
+    * @li "timeout" - when timeout happens on notify and it's hidden
+    * @li "block,clicked" - when a click outside of the notify happens
+    *
+    * Default contents parts of the notify widget that you can use for are:
+    * @li "elm.swallow.content" - A content of the notify
+    *
+    * @ref tutorial_notify show usage of the API.
+    *
+    * @{
+    */
+   /**
+    * @brief Possible orient values for notify.
+    *
+    * This values should be used in conjunction to elm_notify_orient_set() to
+    * set the position in which the notify should appear(relative to its parent)
+    * and in conjunction with elm_notify_orient_get() to know where the notify
+    * is appearing.
+    */
    typedef enum _Elm_Notify_Orient
      {
-        ELM_NOTIFY_ORIENT_TOP,
-        ELM_NOTIFY_ORIENT_CENTER,
-        ELM_NOTIFY_ORIENT_BOTTOM,
-        ELM_NOTIFY_ORIENT_LEFT,
-        ELM_NOTIFY_ORIENT_RIGHT,
-        ELM_NOTIFY_ORIENT_TOP_LEFT,
-        ELM_NOTIFY_ORIENT_TOP_RIGHT,
-        ELM_NOTIFY_ORIENT_BOTTOM_LEFT,
-        ELM_NOTIFY_ORIENT_BOTTOM_RIGHT,
-        ELM_NOTIFY_ORIENT_LAST
+        ELM_NOTIFY_ORIENT_TOP, /**< Notify should appear in the top of parent, default */
+        ELM_NOTIFY_ORIENT_CENTER, /**< Notify should appear in the center of parent */
+        ELM_NOTIFY_ORIENT_BOTTOM, /**< Notify should appear in the bottom of parent */
+        ELM_NOTIFY_ORIENT_LEFT, /**< Notify should appear in the left of parent */
+        ELM_NOTIFY_ORIENT_RIGHT, /**< Notify should appear in the right of parent */
+        ELM_NOTIFY_ORIENT_TOP_LEFT, /**< Notify should appear in the top left of parent */
+        ELM_NOTIFY_ORIENT_TOP_RIGHT, /**< Notify should appear in the top right of parent */
+        ELM_NOTIFY_ORIENT_BOTTOM_LEFT, /**< Notify should appear in the bottom left of parent */
+        ELM_NOTIFY_ORIENT_BOTTOM_RIGHT, /**< Notify should appear in the bottom right of parent */
+        ELM_NOTIFY_ORIENT_LAST /**< Sentinel value, @b don't use */
      } Elm_Notify_Orient;
+   /**
+    * @brief Add a new notify to the parent
+    *
+    * @param parent The parent object
+    * @return The new object or NULL if it cannot be created
+    */
    EAPI Evas_Object      *elm_notify_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the content of the notify widget
+    *
+    * @param obj The notify object
+    * @param content The content will be filled in this notify object
+    *
+    * Once the content object is set, a previously set one will be deleted. If
+    * you want to keep that old content object, use the
+    * elm_notify_content_unset() function.
+    */
    EAPI void              elm_notify_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Unset the content of the notify widget
+    *
+    * @param obj The notify object
+    * @return The content that was being used
+    *
+    * Unparent and return the content object which was set for this widget
+    *
+    * @see elm_notify_content_set()
+    */
    EAPI Evas_Object      *elm_notify_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Return the content of the notify widget
+    *
+    * @param obj The notify object
+    * @return The content that is being used
+    *
+    * @see elm_notify_content_set()
+    */
    EAPI Evas_Object      *elm_notify_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the notify parent
+    *
+    * @param obj The notify object
+    * @param content The new parent
+    *
+    * Once the parent object is set, a previously set one will be disconnected
+    * and replaced.
+    */
    EAPI void              elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the notify parent
+    *
+    * @param obj The notify object
+    * @return The parent
+    *
+    * @see elm_notify_parent_set()
+    */
    EAPI Evas_Object      *elm_notify_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the orientation
+    *
+    * @param obj The notify object
+    * @param orient The new orientation
+    *
+    * Sets the position in which the notify will appear in its parent.
+    *
+    * @see @ref Elm_Notify_Orient for possible values.
+    */
    EAPI void              elm_notify_orient_set(Evas_Object *obj, Elm_Notify_Orient orient) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Return the orientation
+    * @param obj The notify object
+    * @return The orientation of the notification
+    *
+    * @see elm_notify_orient_set()
+    * @see Elm_Notify_Orient
+    */
    EAPI Elm_Notify_Orient elm_notify_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the time interval after which the notify window is going to be
+    * hidden.
+    *
+    * @param obj The notify object
+    * @param time The timeout in seconds
+    *
+    * This function sets a timeout and starts the timer controlling when the
+    * notify is hidden. Since calling evas_object_show() on a notify restarts
+    * the timer controlling when the notify is hidden, setting this before the
+    * notify is shown will in effect mean starting the timer when the notify is
+    * shown.
+    *
+    * @note Set a value <= 0.0 to disable a running timer.
+    *
+    * @note If the value > 0.0 and the notify is previously visible, the
+    * timer will be started with this value, canceling any running timer.
+    */
    EAPI void              elm_notify_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Return the timeout value (in seconds)
+    * @param obj the notify object
+    *
+    * @see elm_notify_timeout_set()
+    */
    EAPI double            elm_notify_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Sets whether events should be passed to by a click outside
+    * its area.
+    *
+    * @param obj The notify object
+    * @param repeats EINA_TRUE Events are repeats, else no
+    *
+    * When true if the user clicks outside the window the events will be caught
+    * by the others widgets, else the events are blocked.
+    *
+    * @note The default value is EINA_TRUE.
+    */
    EAPI void              elm_notify_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Return true if events are repeat below the notify object
+    * @param obj the notify object
+    *
+    * @see elm_notify_repeat_events_set()
+    */
    EAPI Eina_Bool         elm_notify_repeat_events_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   /* smart callbacks called:
-    * "timeout" - when timeout happens on notify and it's hidden
-    * "block,clicked" - when it's hidden by a click outside of the notify's view
+   /**
+    * @}
     */
 
    /* hover */