src/lib/elm_notify.h

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