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      *elm_notify_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  53
  54    /**
  55     * @brief Set the content of the notify widget
  56     *
  57     * @param obj The notify object
  58     * @param content The content will be filled in this notify object
  59     *
  60     * Once the content object is set, a previously set one will be deleted. If
  61     * you want to keep that old content object, use the
  62     * elm_notify_content_unset() function.
  63     *
  64     * @deprecated use elm_object_content_set() instead
  65     *
  66     */
  67    EINA_DEPRECATED EAPI void              elm_notify_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
  68
  69    /**
  70     * @brief Unset the content of the notify widget
  71     *
  72     * @param obj The notify object
  73     * @return The content that was being used
  74     *
  75     * Unparent and return the content object which was set for this widget
  76     *
  77     * @see elm_notify_content_set()
  78     * @deprecated use elm_object_content_unset() instead
  79     *
  80     */
  81    EINA_DEPRECATED EAPI Evas_Object      *elm_notify_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
  82
  83    /**
  84     * @brief Return the content of the notify widget
  85     *
  86     * @param obj The notify object
  87     * @return The content that is being used
  88     *
  89     * @see elm_notify_content_set()
  90     * @deprecated use elm_object_content_get() instead
  91     *
  92     */
  93    EINA_DEPRECATED EAPI Evas_Object      *elm_notify_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  94
  95    /**
  96     * @brief Set the notify parent
  97     *
  98     * @param obj The notify object
  99     * @param content The new parent
 100     *
 101     * Once the parent object is set, a previously set one will be disconnected
 102     * and replaced.
 103     */
 104    EAPI void              elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
 105
 106    /**
 107     * @brief Get the notify parent
 108     *
 109     * @param obj The notify object
 110     * @return The parent
 111     *
 112     * @see elm_notify_parent_set()
 113     */
 114    EAPI Evas_Object      *elm_notify_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 115
 116    /**
 117     * @brief Set the orientation
 118     *
 119     * @param obj The notify object
 120     * @param orient The new orientation
 121     *
 122     * Sets the position in which the notify will appear in its parent.
 123     *
 124     * @see @ref Elm_Notify_Orient for possible values.
 125     */
 126    EAPI void              elm_notify_orient_set(Evas_Object *obj, Elm_Notify_Orient orient) EINA_ARG_NONNULL(1);
 127
 128    /**
 129     * @brief Return the orientation
 130     * @param obj The notify object
 131     * @return The orientation of the notification
 132     *
 133     * @see elm_notify_orient_set()
 134     * @see Elm_Notify_Orient
 135     */
 136    EAPI Elm_Notify_Orient elm_notify_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 137
 138    /**
 139     * @brief Set the time interval after which the notify window is going to be
 140     * hidden.
 141     *
 142     * @param obj The notify object
 143     * @param time The timeout in seconds
 144     *
 145     * This function sets a timeout and starts the timer controlling when the
 146     * notify is hidden. Since calling evas_object_show() on a notify restarts
 147     * the timer controlling when the notify is hidden, setting this before the
 148     * notify is shown will in effect mean starting the timer when the notify is
 149     * shown.
 150     *
 151     * @note Set a value <= 0.0 to disable a running timer.
 152     *
 153     * @note If the value > 0.0 and the notify is previously visible, the
 154     * timer will be started with this value, canceling any running timer.
 155     */
 156    EAPI void              elm_notify_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
 157
 158    /**
 159     * @brief Return the timeout value (in seconds)
 160     * @param obj the notify object
 161     *
 162     * @see elm_notify_timeout_set()
 163     */
 164    EAPI double            elm_notify_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 165
 166    /**
 167     * @brief Sets whether events should be passed to by a click outside
 168     * its area.
 169     *
 170     * @param obj The notify object
 171     * @param repeats EINA_TRUE Events are repeats, else no
 172     *
 173     * When true if the user clicks outside the window the events will be caught
 174     * by the others widgets, else the events are blocked.
 175     *
 176     * @note The default value is EINA_TRUE.
 177     */
 178    EAPI void              elm_notify_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
 179
 180    /**
 181     * @brief Return true if events are repeat below the notify object
 182     * @param obj the notify object
 183     *
 184     * @see elm_notify_repeat_events_set()
 185     */
 186    EAPI Eina_Bool         elm_notify_repeat_events_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 187
 188    /**
 189     * @}
 190     */
 191