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