src/lib/elm_notify.h

   1 /**
   2  * @defgroup Notify Notify
   3  * @ingroup Elementary
   4  *
   5  * @image html notify_inheritance_tree.png
   6  * @image latex notify_inheritance_tree.eps
   7  *
   8  * @image html img/widget/notify/preview-00.png
   9  * @image latex img/widget/notify/preview-00.eps
  10  *
  11  * Display a container in a particular region of the parent(top, bottom,
  12  * etc).  A timeout can be set to automatically hide the notify. This is so
  13  * that, after an evas_object_show() on a notify object, if a timeout was set
  14  * on it, it will @b automatically get hidden after that time.
  15  *
  16  * Signals that you can add callbacks for are:
  17  * @li "timeout" - when timeout happens on notify and it's hidden
  18  * @li "block,clicked" - when a click outside of the notify happens
  19  *
  20  * This widget inherits from @ref elm-container-class, so that the
  21  * functions meant to act on it will wor work for mapbuf objects:
  22  *
  23  * @li @ref elm_object_part_content_set
  24  * @li @ref elm_object_part_content_get
  25  * @li @ref elm_object_part_content_unset
  26  *
  27  * Default content parts of the notify widget that you can use are:
  28  * @li @c "default" - The main content of the notify
  29  *
  30  * @ref tutorial_notify show usage of the API.
  31  *
  32  * @{
  33  */
  34
  35 #define ELM_NOTIFY_ALIGN_FILL                   -1.0  /**< Use with elm_notify_align_set() @since 1.8 */
  36
  37 /**
  38  * @brief Add a new notify to the parent
  39  *
  40  * @param parent The parent object
  41  * @return The new object or NULL if it cannot be created
  42  *
  43  * @ingroup Notify
  44  */
  45 EAPI Evas_Object                 *elm_notify_add(Evas_Object *parent);
  46
  47 /**
  48  * @brief Set the notify parent
  49  *
  50  * @param obj The notify object
  51  * @param parent The new parent
  52  *
  53  * Once the parent object is set, a previously set one will be disconnected
  54  * and replaced.
  55  *
  56  * @ingroup Notify
  57  */
  58 EAPI void                         elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent);
  59
  60 /**
  61  * @brief Get the notify parent
  62  *
  63  * @param obj The notify object
  64  * @return The parent
  65  *
  66  * @see elm_notify_parent_set()
  67  *
  68  * @ingroup Notify
  69  */
  70 EAPI Evas_Object                 *elm_notify_parent_get(const Evas_Object *obj);
  71
  72 /**
  73  * @brief Set the time interval after which the notify window is going to be
  74  * hidden.
  75  *
  76  * @param obj The notify object
  77  * @param timeout The timeout in seconds
  78  *
  79  * This function sets a timeout and starts the timer controlling when the
  80  * notify is hidden. Since calling evas_object_show() on a notify restarts
  81  * the timer controlling when the notify is hidden, setting this before the
  82  * notify is shown will in effect mean starting the timer when the notify is
  83  * shown.
  84  *
  85  * @note Set a value <= 0.0 to disable a running timer.
  86  *
  87  * @note If the value > 0.0 and the notify is previously visible, the
  88  * timer will be started with this value, canceling any running timer.
  89  *
  90  * @ingroup Notify
  91  */
  92 EAPI void                         elm_notify_timeout_set(Evas_Object *obj, double timeout);
  93
  94 /**
  95  * @brief Return the timeout value (in seconds)
  96  * @param obj the notify object
  97  *
  98  * @see elm_notify_timeout_set()
  99  *
 100  * @ingroup Notify
 101  */
 102 EAPI double                       elm_notify_timeout_get(const Evas_Object *obj);
 103
 104 /**
 105  * @brief Sets whether events should be passed to by a click outside
 106  * its area.
 107  *
 108  * @param obj The notify object
 109  * @param allow EINA_TRUE If events are allowed, otherwise not
 110  *
 111  * When true if the user clicks outside the window the events will be caught
 112  * by the others widgets, else the events are blocked.
 113  *
 114  * @note The default value is EINA_TRUE.
 115  *
 116  * @ingroup Notify
 117  */
 118 EAPI void                         elm_notify_allow_events_set(Evas_Object *obj, Eina_Bool allow);
 119
 120 /**
 121  * @brief Return true if events are allowed below the notify object
 122  * @param obj the notify object
 123  *
 124  * @see elm_notify_allow_events_set()
 125  *
 126  * @ingroup Notify
 127  */
 128 EAPI Eina_Bool                    elm_notify_allow_events_get(const Evas_Object *obj);
 129
 130 /**
 131  * @brief Set the alignment of the notify object
 132  *
 133  * @param obj The notify object
 134  * @param horizontal The horizontal alignment of the notification
 135  * @param vertical The vertical alignment of the notification
 136  *
 137  * Sets the alignment in which the notify will appear in its parent.
 138  *
 139  * @note To fill the notify box in the parent area, please pass the
 140  * @c ELM_NOTIFY_ALIGN_FILL to @p horizontal, @p vertical.
 141  *
 142  * @since 1.8
 143  * @ingroup Notify
 144  */
 145 EAPI void                         elm_notify_align_set(Evas_Object *obj, double horizontal, double vertical);
 146
 147 /**
 148  * @brief Get the alignment of the notify object
 149  * @param obj The notify object
 150  * @param horizontal The horizontal alignment of the notification
 151  * @param vertical The vertical alignment of the notification
 152  *
 153  * @see elm_notify_align_set()
 154  *
 155  * @since 1.8
 156  * @ingroup Notify
 157  */
 158 EAPI void                         elm_notify_align_get(const Evas_Object *obj, double *horizontal, double *vertical);
 159
 160 /**
 161  * @}
 162  */