wearable/src/lib/elc_popup.h

   1 /**
   2  * @defgroup Popup Popup
   3  * @ingroup Elementary
   4  *
   5  * @image html popup_inheritance_tree.png
   6  * @image latex popup_inheritance_tree.eps
   7  *
   8  * This widget is an enhancement of @ref Notify. In addition to
   9  * content area, there are two optional sections, namely title area and
  10  * action area.
  11  *
  12  * The popup widget displays its content with a particular orientation in
  13  * the parent area. This orientation can be one among top, center,
  14  * bottom, left, top-left, top-right, bottom-left and bottom-right.
  15  * Content part of Popup can be an Evas Object set by application or
  16  * it can be Text set by application or set of items containing an
  17  * icon and/or text.  The content/item-list can be removed using
  18  * elm_object_content_set with second parameter passed as NULL.
  19  *
  20  * The following figures show the textual layouts of popup in which Title
  21  * Area and Action area area are optional ones.  Action area can have
  22  * up to 3 buttons handled using elm_object common APIs mentioned
  23  * below. If user wants to have more than 3 buttons then these buttons
  24  * can be put inside the items of a list as content.  User needs to
  25  * handle the clicked signal of these action buttons if required.  No
  26  * event is processed by the widget automatically when clicked on
  27  * these action buttons.
  28  *
  29  * <pre>
  30  *
  31  *|---------------------|    |---------------------|    |---------------------|
  32  *|     Title Area      |    |     Title Area      |    |     Title Area      |
  33  *|Icon|    Text        |    |Icon|    Text        |    |Icon|    Text        |
  34  *|---------------------|    |---------------------|    |---------------------|
  35  *|       Item 1        |    |                     |    |                     |
  36  *|---------------------|    |                     |    |                     |
  37  *|       Item 2        |    |                     |    |    Description      |
  38  *|---------------------|    |       Content       |    |                     |
  39  *|       Item 3        |    |                     |    |                     |
  40  *|---------------------|    |                     |    |                     |
  41  *|         .           |    |---------------------|    |---------------------|
  42  *|         .           |    |     Action Area     |    |     Action Area     |
  43  *|         .           |    | Btn1  |Btn2|. |Btn3 |    | Btn1  |Btn2|  |Btn3 |
  44  *|---------------------|    |---------------------|    |---------------------|
  45  *|       Item N        |     Content Based Layout     Description based Layout
  46  *|---------------------|
  47  *|     Action Area     |
  48  *| Btn1  |Btn2|. |Btn3 |
  49  *|---------------------|
  50  *   Item Based Layout
  51  *
  52  * </pre>
  53  *
  54  * Timeout can be set on expiry of which popup instance hides and
  55  * sends a smart signal "timeout" to the user.  The visible region of
  56  * popup is surrounded by a translucent region called Blocked Event
  57  * area.  By clicking on Blocked Event area, the signal
  58  * "block,clicked" is sent to the application. This block event area
  59  * can be avoided by using API elm_popup_allow_events_set.  When gets
  60  * hidden, popup does not get destroyed automatically, application
  61  * should destroy the popup instance after use.  To control the
  62  * maximum height of the internal scroller for item, we use the height
  63  * of the action area which is passed by theme based on the number of
  64  * buttons currently set to popup.
  65  *
  66  * This widget inherits from the @ref Layout one, so that all the
  67  * functions acting on it also work for popup objects (@since 1.8).
  68  *
  69  * This widget emits the following signals, besides the ones sent from
  70  * @ref Layout:
  71  * @li @c "timeout" - whenever popup is closed as a result of timeout.
  72  * @li @c "block,clicked" - whenever user taps on Blocked Event area.
  73  * @li @c "language,changed" - The program's language changed. (@since 1.8)
  74  * @li @c "show,finished" - When the popup transition is finished in showing.
  75  *
  76  * Styles available for Popup
  77  * @li "default"
  78  *
  79  * Default contents parts of the popup widget that you can use are:
  80  * @li "default" - The content of the popup
  81  * @li "title,icon" - Title area's icon
  82  * @li "button1" - 1st button of the action area
  83  * @li "button2" - 2nd button of the action area
  84  * @li "button3" - 3rd button of the action area
  85  *
  86  * Default text parts of the popup widget that you can use are:
  87  * @li "title,text" - This operates on Title area's label
  88  * @li "default" - content-text set in the content area of the widget
  89  *
  90  * Default contents parts of the popup items that you can use are:
  91  * @li "default" -Item's icon
  92  *
  93  * Default text parts of the popup items that you can use are:
  94  * @li "default" - Item's label
  95  *
  96  * Supported elm_object_item common APIs.
  97  * @li @ref elm_object_item_disabled_set
  98  * @li @ref elm_object_item_disabled_get
  99  * @li @ref elm_object_item_part_text_set
 100  * @li @ref elm_object_item_part_text_get
 101  * @li @ref elm_object_item_part_content_set
 102  * @li @ref elm_object_item_part_content_get
 103  * @li @ref elm_object_item_signal_emit
 104  * @li @ref elm_object_item_del
 105  *
 106  * Here are some sample code to illustrate Popup usage:
 107  * @li @ref popup_example_01_c
 108  * @li @ref popup_example_02_c
 109  * @li @ref popup_example_03_c
 110  */
 111
 112 /**
 113  * @brief Possible orient values for popup.
 114  *
 115  * These values should be used in conjunction to elm_popup_orient_set() to
 116  * set the position in which the popup should appear(relative to its parent)
 117  * and in conjunction with elm_popup_orient_get() to know where the popup
 118  * is appearing.
 119  *
 120  * @ingroup Popup
 121  */
 122 typedef enum
 123 {
 124    ELM_POPUP_ORIENT_TOP = 0, /**< Popup should appear in the top of parent, default */
 125    ELM_POPUP_ORIENT_CENTER, /**< Popup should appear in the center of parent */
 126    ELM_POPUP_ORIENT_BOTTOM, /**< Popup should appear in the bottom of parent */
 127    ELM_POPUP_ORIENT_LEFT, /**< Popup should appear in the left of parent */
 128    ELM_POPUP_ORIENT_RIGHT, /**< Popup should appear in the right of parent */
 129    ELM_POPUP_ORIENT_TOP_LEFT, /**< Popup should appear in the top left of parent */
 130    ELM_POPUP_ORIENT_TOP_RIGHT, /**< Popup should appear in the top right of parent */
 131    ELM_POPUP_ORIENT_BOTTOM_LEFT, /**< Popup should appear in the bottom left of parent */
 132    ELM_POPUP_ORIENT_BOTTOM_RIGHT, /**< Notify should appear in the bottom right of parent */
 133    ELM_POPUP_ORIENT_LAST /**< Sentinel value, @b don't use */
 134  } Elm_Popup_Orient;
 135
 136 /**
 137  * @brief Adds a new Popup to the parent
 138  *
 139  * @param parent The parent object
 140  * @return The new object or NULL if it cannot be created
 141  *
 142  * @ingroup Popup
 143  */
 144 EAPI Evas_Object *elm_popup_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
 145
 146 /**
 147  * @brief Add a new item to a Popup object
 148  *
 149  * Both an item list and a content could not be set at the same time!
 150  * once you add an item, the previous content will be removed.
 151  *
 152  * @param obj popup object
 153  * @param icon Icon to be set on new item
 154  * @param label The Label of the new item
 155  * @param func Convenience function called when item selected
 156  * @param data Data passed to @p func above
 157  * @return A handle to the item added or @c NULL, on errors
 158  *
 159  * @ingroup Popup
 160  * @warning When the first item is appended to popup object, any previous content
 161  * of the content area is deleted. At a time, only one of content, content-text
 162  * and item(s) can be there in a popup content area.
 163  */
 164 EAPI Elm_Object_Item *elm_popup_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 165
 166 /**
 167  * @brief Sets the wrapping type of content text packed in content
 168  * area of popup object.
 169  *
 170  * @param obj The Popup object
 171  * @param wrap wrapping type of type Elm_Wrap_Type
 172  *
 173  * @ingroup Popup
 174  * @see elm_popup_content_text_wrap_type_get()
 175  */
 176 EAPI void elm_popup_content_text_wrap_type_set(Evas_Object *obj, Elm_Wrap_Type wrap) EINA_ARG_NONNULL(1);
 177
 178 /**
 179  * @brief Returns the wrapping type of content text packed in content area of
 180  * popup object.
 181  *
 182  * @param obj The Popup object
 183  * @return wrap type of the content text
 184  *
 185  * @ingroup Popup
 186  * @see elm_popup_content_text_wrap_type_set
 187  */
 188 EAPI Elm_Wrap_Type elm_popup_content_text_wrap_type_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 189
 190 /**
 191  * @brief Sets the orientation of the popup in the parent region
 192  *
 193  * @param obj The popup object
 194  * @param orient  the orientation of the popup
 195  *
 196  * Sets the position in which popup will appear in its parent
 197  *
 198  * @ingroup Popup
 199  * @see @ref Elm_Popup_Orient for possible values.
 200  */
 201 EAPI void elm_popup_orient_set(Evas_Object *obj, Elm_Popup_Orient orient) EINA_ARG_NONNULL(1);
 202
 203 /**
 204  * @brief Returns the orientation of Popup
 205  *
 206  * @param obj The popup object
 207  * @return the orientation of the popup
 208  *
 209  * @ingroup Popup
 210  * @see elm_popup_orient_set()
 211  * @see Elm_Popup_Orient
 212  */
 213 EAPI Elm_Popup_Orient elm_popup_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 214
 215 /**
 216  * @brief Sets a timeout to hide popup automatically
 217  *
 218  * @param obj The popup object
 219  * @param timeout The timeout in seconds
 220  *
 221  * This function sets a timeout and starts the timer controlling when the
 222  * popup is hidden. Since calling evas_object_show() on a popup restarts
 223  * the timer controlling when it is hidden, setting this before the
 224  * popup is shown will in effect mean starting the timer when the popup is
 225  * shown. Smart signal "timeout" is called afterwards which can be handled
 226  * if needed.
 227  *
 228  * @note Set a value <= 0.0 to disable a running timer.
 229  *
 230  * @note If the value > 0.0 and the popup is previously visible, the
 231  * timer will be started with this value, canceling any running timer.
 232  * @ingroup Popup
 233  */
 234 EAPI void elm_popup_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
 235
 236 /**
 237  * @brief Returns the timeout value set to the popup (in seconds)
 238  *
 239  * @param obj The popup object
 240  * @return the timeout value
 241  *
 242  * @ingroup Popup
 243  * @see elm_popup_timeout_set()
 244  */
 245 EAPI double elm_popup_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 246
 247 /**
 248  * @brief Sets whether events should be passed to by a click outside.
 249  *
 250  * @param obj The popup object
 251  * @param allow EINA_TRUE Events are passed to lower objects, else not
 252  *
 253  * Enabling allow event will remove the Blocked event area and events will
 254  * pass to the lower layer objects otherwise they are blocked.
 255  *
 256  * @ingroup Popup
 257  * @see elm_popup_allow_events_get()
 258  * @note The default value is EINA_FALSE.
 259  */
 260 EAPI void elm_popup_allow_events_set(Evas_Object *obj, Eina_Bool allow);
 261
 262 /**
 263  * @brief Returns value indicating whether allow event is enabled or not
 264  *
 265  * @param obj The popup object
 266  * @return EINA_FALSE if Blocked event area is present else EINA_TRUE
 267  *
 268  * @ingroup Popup
 269  * @see elm_popup_allow_events_set()
 270  * @note By default the Blocked event area is present
 271  */
 272 EAPI Eina_Bool elm_popup_allow_events_get(const Evas_Object *obj);
 273
 274 /**
 275  * @brief Set the popup's parent
 276  *
 277  * @param obj The popup object
 278  * @param parent The new parent
 279  *
 280  * Once the parent object is set, a previously set one will be disconnected
 281  * and replaced.
 282  *
 283  * @ingroup Popup
 284  */
 285 EAPI void elm_popup_parent_set(Evas_Object *obj, Evas_Object *parent);
 286
 287 /**
 288  * @brief Get the popup's parent
 289  *
 290  * @param obj The popup object
 291  * @return The parent
 292  *
 293  * @see elm_popup_parent_set()
 294  *
 295  * @ingroup Popup
 296  */
 297 EAPI Evas_Object *elm_popup_parent_get(Evas_Object *obj);