src/lib/elm_notify.h

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