src/lib/elc_popup.h

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