Macros | Enumerations | Functions
Popup

Macros

#define ELM_POPUP_CLASS   elm_popup_class_get()
 Elementary popup class.
 
#define ELM_POPUP_EVENT_BLOCK_CLICKED   (&(_ELM_POPUP_EVENT_BLOCK_CLICKED))
 Called when popup was clicked.
 
#define ELM_POPUP_EVENT_TIMEOUT   (&(_ELM_POPUP_EVENT_TIMEOUT))
 Called when popup timed out.
 
#define ELM_POPUP_EVENT_ITEM_FOCUSED   (&(_ELM_POPUP_EVENT_ITEM_FOCUSED))
 Called when popup got focus. More...
 
#define ELM_POPUP_EVENT_ITEM_UNFOCUSED   (&(_ELM_POPUP_EVENT_ITEM_UNFOCUSED))
 Called when popup lost focus. More...
 
#define ELM_POPUP_EVENT_DISMISSED   (&(_ELM_POPUP_EVENT_DISMISSED))
 Called when popup was dismissed.
 

Enumerations

enum  Elm_Popup_Orient {
  ELM_POPUP_ORIENT_TOP = 0,
  ELM_POPUP_ORIENT_CENTER,
  ELM_POPUP_ORIENT_BOTTOM,
  ELM_POPUP_ORIENT_LEFT,
  ELM_POPUP_ORIENT_RIGHT,
  ELM_POPUP_ORIENT_TOP_LEFT,
  ELM_POPUP_ORIENT_TOP_RIGHT,
  ELM_POPUP_ORIENT_BOTTOM_LEFT,
  ELM_POPUP_ORIENT_BOTTOM_RIGHT,
  ELM_POPUP_ORIENT_LAST,
  ELM_POPUP_ORIENT_TOP = 0,
  ELM_POPUP_ORIENT_CENTER,
  ELM_POPUP_ORIENT_BOTTOM,
  ELM_POPUP_ORIENT_LEFT,
  ELM_POPUP_ORIENT_RIGHT,
  ELM_POPUP_ORIENT_TOP_LEFT,
  ELM_POPUP_ORIENT_TOP_RIGHT,
  ELM_POPUP_ORIENT_BOTTOM_LEFT,
  ELM_POPUP_ORIENT_BOTTOM_RIGHT,
  ELM_POPUP_ORIENT_LAST
}
 Possible orient values for popup. More...
 
enum  Elm_Popup_Orient {
  ELM_POPUP_ORIENT_TOP = 0,
  ELM_POPUP_ORIENT_CENTER,
  ELM_POPUP_ORIENT_BOTTOM,
  ELM_POPUP_ORIENT_LEFT,
  ELM_POPUP_ORIENT_RIGHT,
  ELM_POPUP_ORIENT_TOP_LEFT,
  ELM_POPUP_ORIENT_TOP_RIGHT,
  ELM_POPUP_ORIENT_BOTTOM_LEFT,
  ELM_POPUP_ORIENT_BOTTOM_RIGHT,
  ELM_POPUP_ORIENT_LAST,
  ELM_POPUP_ORIENT_TOP = 0,
  ELM_POPUP_ORIENT_CENTER,
  ELM_POPUP_ORIENT_BOTTOM,
  ELM_POPUP_ORIENT_LEFT,
  ELM_POPUP_ORIENT_RIGHT,
  ELM_POPUP_ORIENT_TOP_LEFT,
  ELM_POPUP_ORIENT_TOP_RIGHT,
  ELM_POPUP_ORIENT_BOTTOM_LEFT,
  ELM_POPUP_ORIENT_BOTTOM_RIGHT,
  ELM_POPUP_ORIENT_LAST
}
 Possible orient values for popup. More...
 

Functions

Evas_Objectelm_popup_add (Evas_Object *parent)
 Adds a new Popup to the parent. More...
 
EOAPI void elm_obj_popup_align_set (Eo *obj, double horizontal, double vertical)
 Set the alignment of the popup object. More...
 
EOAPI void elm_obj_popup_align_get (const Eo *obj, double *horizontal, double *vertical)
 Get the alignment of the popup object. More...
 
EOAPI void elm_obj_popup_allow_events_set (Eo *obj, Eina_Bool allow)
 Sets whether events should be passed to by a click outside. More...
 
EOAPI Eina_Bool elm_obj_popup_allow_events_get (const Eo *obj)
 Returns value indicating whether allow event is enabled or not. More...
 
EOAPI void elm_obj_popup_content_text_wrap_type_set (Eo *obj, Elm_Wrap_Type wrap)
 Control the wrapping type of content text packed in content area of popup object. More...
 
EOAPI Elm_Wrap_Type elm_obj_popup_content_text_wrap_type_get (const Eo *obj)
 Control the wrapping type of content text packed in content area of popup object. More...
 
EOAPI void elm_obj_popup_orient_set (Eo *obj, Elm_Popup_Orient orient)
 Sets the orientation of the popup in the parent region. More...
 
EOAPI Elm_Popup_Orient elm_obj_popup_orient_get (const Eo *obj)
 Returns the orientation of the popup. More...
 
EOAPI void elm_obj_popup_timeout_set (Eo *obj, double timeout)
 Sets a timeout to hide popup automatically. More...
 
EOAPI double elm_obj_popup_timeout_get (const Eo *obj)
 Returns the timeout value set to the popup (in seconds). More...
 
EOAPI void elm_obj_popup_scrollable_set (Eo *obj, Eina_Bool scroll)
 Enable or disable scroller in popup content area. More...
 
EOAPI Eina_Bool elm_obj_popup_scrollable_get (const Eo *obj)
 Get the scrollable state of popup content area. More...
 
EOAPI Elm_Widget_Itemelm_obj_popup_item_append (Eo *obj, const char *label, Efl_Canvas_Object *icon, Evas_Smart_Cb func, const void *data)
 Add a new item to a Popup object. More...
 
EOAPI void elm_obj_popup_dismiss (Eo *obj)
 Dismiss a Popup object. More...
 

Detailed Description

popup_inheritance_tree.png

This widget is an enhancement of Notify. In addition to content area, there are two optional sections, namely title area and action area.

The popup widget displays its content with a particular orientation in the parent area. This orientation can be one among top, center, bottom, left, top-left, top-right, bottom-left and bottom-right. Content part of Popup can be an Evas Object set by application or it can be Text set by application or set of items containing an icon and/or text. The content/item-list can be removed using elm_object_content_set with second parameter passed as NULL.

The following figures show the textual layouts of popup in which Title Area and Action area are optional ones. Action area can have up to 3 buttons handled using elm_object common APIs mentioned below. If user wants to have more than 3 buttons then these buttons can be put inside the items of a list as content. User needs to handle the clicked signal of these action buttons if required. No event is processed by the widget automatically when clicked on these action buttons.

*|---------------------|    |---------------------|    |---------------------|
*|     Title Area      |    |     Title Area      |    |     Title Area      |
*|Icon|    Text        |    |Icon|    Text        |    |Icon|    Text        |
*|---------------------|    |---------------------|    |---------------------|
*|       Item 1        |    |                     |    |                     |
*|---------------------|    |                     |    |                     |
*|       Item 2        |    |                     |    |    Description      |
*|---------------------|    |       Content       |    |                     |
*|       Item 3        |    |                     |    |                     |
*|---------------------|    |                     |    |                     |
*|         .           |    |---------------------|    |---------------------|
*|         .           |    |     Action Area     |    |     Action Area     |
*|         .           |    | Btn1  |Btn2|. |Btn3 |    | Btn1  |Btn2|  |Btn3 |
*|---------------------|    |---------------------|    |---------------------|
*|       Item N        |     Content Based Layout     Description based Layout
*|---------------------|
*|     Action Area     |
*| Btn1  |Btn2|. |Btn3 |
*|---------------------|
    Item Based Layout
  

Timeout can be set on expiry of which popup instance hides and sends a smart signal "timeout" to the user. The visible region of popup is surrounded by a translucent region called Blocked Event area. By clicking on Blocked Event area, the signal "block,clicked" is sent to the application. This block event area can be avoided by using API elm_popup_allow_events_set. When gets hidden, popup does not get destroyed automatically, application should destroy the popup instance after use. To control the maximum height of the internal scroller for item, we use the height of the action area which is passed by theme based on the number of buttons currently set to popup.

Popup sets the focus to itself when evas_object_show is called on popup. To set the focus into popup's contents and buttons automatically, evas_object_show on popup should be called after setting all the contents and buttons of popup.

This widget inherits from the Layout one, so that all the functions acting on it also work for popup objects (since 1.8).

This widget emits the following signals, besides the ones sent from Layout:

Styles available for Popup

Default contents parts of the popup widget that you can use are:

Default text parts of the popup widget that you can use are:

Default contents parts of the popup items that you can use are:

Default text parts of the popup items that you can use are:

Supported elm_object_item common APIs.

supported elm_object common APIs.

Here are some sample code to illustrate Popup usage:

Macro Definition Documentation

◆ ELM_POPUP_EVENT_ITEM_FOCUSED

#define ELM_POPUP_EVENT_ITEM_FOCUSED   (&(_ELM_POPUP_EVENT_ITEM_FOCUSED))

Called when popup got focus.

Returns
Efl_Object *

◆ ELM_POPUP_EVENT_ITEM_UNFOCUSED

#define ELM_POPUP_EVENT_ITEM_UNFOCUSED   (&(_ELM_POPUP_EVENT_ITEM_UNFOCUSED))

Called when popup lost focus.

Returns
Efl_Object *

Enumeration Type Documentation

◆ Elm_Popup_Orient [1/2]

Possible orient values for popup.

These values should be used in conjunction to elm_popup_orient_set() to set the position in which the popup should appear(relative to its parent) and in conjunction with elm_popup_orient_get() to know where the popup is appearing.

Enumerator
ELM_POPUP_ORIENT_TOP 

Popup should appear in the top of parent, default.

ELM_POPUP_ORIENT_CENTER 

Popup should appear in the center of parent.

ELM_POPUP_ORIENT_BOTTOM 

Popup should appear in the bottom of parent.

ELM_POPUP_ORIENT_LEFT 

Popup should appear in the left of parent.

ELM_POPUP_ORIENT_RIGHT 

Popup should appear in the right of parent.

ELM_POPUP_ORIENT_TOP_LEFT 

Popup should appear in the top left of parent.

ELM_POPUP_ORIENT_TOP_RIGHT 

Popup should appear in the top right of parent.

ELM_POPUP_ORIENT_BOTTOM_LEFT 

Popup should appear in the bottom left of parent.

ELM_POPUP_ORIENT_BOTTOM_RIGHT 

Notify should appear in the bottom right of parent.

ELM_POPUP_ORIENT_LAST 

Sentinel value to indicate last enum field during iteration.

ELM_POPUP_ORIENT_TOP 

Popup should appear in the top of parent, default.

ELM_POPUP_ORIENT_CENTER 

Popup should appear in the center of parent.

ELM_POPUP_ORIENT_BOTTOM 

Popup should appear in the bottom of parent.

ELM_POPUP_ORIENT_LEFT 

Popup should appear in the left of parent.

ELM_POPUP_ORIENT_RIGHT 

Popup should appear in the right of parent.

ELM_POPUP_ORIENT_TOP_LEFT 

Popup should appear in the top left of parent.

ELM_POPUP_ORIENT_TOP_RIGHT 

Popup should appear in the top right of parent.

ELM_POPUP_ORIENT_BOTTOM_LEFT 

Popup should appear in the bottom left of parent.

ELM_POPUP_ORIENT_BOTTOM_RIGHT 

Notify should appear in the bottom right of parent.

ELM_POPUP_ORIENT_LAST 

Sentinel value to indicate last enum field during iteration.

◆ Elm_Popup_Orient [2/2]

Possible orient values for popup.

These values should be used in conjunction to elm_popup_orient_set() to set the position in which the popup should appear(relative to its parent) and in conjunction with elm_popup_orient_get() to know where the popup is appearing.

Enumerator
ELM_POPUP_ORIENT_TOP 

Popup should appear in the top of parent, default.

ELM_POPUP_ORIENT_CENTER 

Popup should appear in the center of parent.

ELM_POPUP_ORIENT_BOTTOM 

Popup should appear in the bottom of parent.

ELM_POPUP_ORIENT_LEFT 

Popup should appear in the left of parent.

ELM_POPUP_ORIENT_RIGHT 

Popup should appear in the right of parent.

ELM_POPUP_ORIENT_TOP_LEFT 

Popup should appear in the top left of parent.

ELM_POPUP_ORIENT_TOP_RIGHT 

Popup should appear in the top right of parent.

ELM_POPUP_ORIENT_BOTTOM_LEFT 

Popup should appear in the bottom left of parent.

ELM_POPUP_ORIENT_BOTTOM_RIGHT 

Notify should appear in the bottom right of parent.

ELM_POPUP_ORIENT_LAST 

Sentinel value to indicate last enum field during iteration.

ELM_POPUP_ORIENT_TOP 

Popup should appear in the top of parent, default.

ELM_POPUP_ORIENT_CENTER 

Popup should appear in the center of parent.

ELM_POPUP_ORIENT_BOTTOM 

Popup should appear in the bottom of parent.

ELM_POPUP_ORIENT_LEFT 

Popup should appear in the left of parent.

ELM_POPUP_ORIENT_RIGHT 

Popup should appear in the right of parent.

ELM_POPUP_ORIENT_TOP_LEFT 

Popup should appear in the top left of parent.

ELM_POPUP_ORIENT_TOP_RIGHT 

Popup should appear in the top right of parent.

ELM_POPUP_ORIENT_BOTTOM_LEFT 

Popup should appear in the bottom left of parent.

ELM_POPUP_ORIENT_BOTTOM_RIGHT 

Notify should appear in the bottom right of parent.

ELM_POPUP_ORIENT_LAST 

Sentinel value to indicate last enum field during iteration.

Function Documentation

◆ elm_popup_add()

Evas_Object* elm_popup_add ( Evas_Object parent)

◆ elm_obj_popup_align_set()

EOAPI void elm_obj_popup_align_set ( Eo obj,
double  horizontal,
double  vertical 
)

Set the alignment of the popup object.

Sets the alignment in which the popup will appear in its parent.

Parameters
[in]objThe object.
[in]horizontalThe horizontal alignment of the popup.
[in]verticalThe vertical alignment of the popup.
Since
1.9

◆ elm_obj_popup_align_get()

EOAPI void elm_obj_popup_align_get ( const Eo obj,
double *  horizontal,
double *  vertical 
)

Get the alignment of the popup object.

Parameters
[in]objThe object.
[out]horizontalThe horizontal alignment of the popup.
[out]verticalThe vertical alignment of the popup.
Since
1.9

◆ elm_obj_popup_allow_events_set()

EOAPI void elm_obj_popup_allow_events_set ( Eo obj,
Eina_Bool  allow 
)

Sets whether events should be passed to by a click outside.

Enabling allow event will remove the Blocked event area and events will pass to the lower layer objects otherwise they are blocked.

Note
The default value is false.
Parameters
[in]objThe object.
[in]allowIf true, events are passed to lower objects.

◆ elm_obj_popup_allow_events_get()

EOAPI Eina_Bool elm_obj_popup_allow_events_get ( const Eo obj)

Returns value indicating whether allow event is enabled or not.

Parameters
[in]objThe object.
Returns
If true, events are passed to lower objects.

◆ elm_obj_popup_content_text_wrap_type_set()

EOAPI void elm_obj_popup_content_text_wrap_type_set ( Eo obj,
Elm_Wrap_Type  wrap 
)

Control the wrapping type of content text packed in content area of popup object.

Parameters
[in]objThe object.
[in]wrapWrapping type of type Elm_Wrap_Type.

◆ elm_obj_popup_content_text_wrap_type_get()

EOAPI Elm_Wrap_Type elm_obj_popup_content_text_wrap_type_get ( const Eo obj)

Control the wrapping type of content text packed in content area of popup object.

Parameters
[in]objThe object.
Returns
Wrapping type of type Elm_Wrap_Type.

◆ elm_obj_popup_orient_set()

EOAPI void elm_obj_popup_orient_set ( Eo obj,
Elm_Popup_Orient  orient 
)

Sets the orientation of the popup in the parent region.

Sets the position in which popup will appear in its parent. By default, ELM_POPUP_ORIENT_CENTER is set.

Parameters
[in]objThe object.
[in]orientThe orientation of the popup.

◆ elm_obj_popup_orient_get()

EOAPI Elm_Popup_Orient elm_obj_popup_orient_get ( const Eo obj)

Returns the orientation of the popup.

Parameters
[in]objThe object.
Returns
The orientation of the popup.

◆ elm_obj_popup_timeout_set()

EOAPI void elm_obj_popup_timeout_set ( Eo obj,
double  timeout 
)

Sets a timeout to hide popup automatically.

This function sets a timeout and starts the timer controlling when the popup is hidden. Since calling evas_object_show on a popup restarts the timer controlling when it is hidden, setting this before the popup is shown will in effect mean starting the timer when the popup is shown. Smart signal "timeout" is called afterwards which can be handled if needed.

Note
Set a value <= 0.0 to disable a running timer.
If the value > 0.0 and the popup is previously visible, the timer will be started with this value, canceling any running timer.
Parameters
[in]objThe object.
[in]timeoutThe timeout in seconds.

◆ elm_obj_popup_timeout_get()

EOAPI double elm_obj_popup_timeout_get ( const Eo obj)

Returns the timeout value set to the popup (in seconds).

Parameters
[in]objThe object.
Returns
The timeout in seconds.

◆ elm_obj_popup_scrollable_set()

EOAPI void elm_obj_popup_scrollable_set ( Eo obj,
Eina_Bool  scroll 
)

Enable or disable scroller in popup content area.

Normally content area does not contain scroller.

Parameters
[in]objThe object.
[in]scrolltrue if it is to be scrollable, false otherwise.
Since
1.15.1

◆ elm_obj_popup_scrollable_get()

EOAPI Eina_Bool elm_obj_popup_scrollable_get ( const Eo obj)

Get the scrollable state of popup content area.

Normally content area does not contain scroller.

Parameters
[in]objThe object.
Returns
true if it is to be scrollable, false otherwise.
Since
1.15.1

◆ elm_obj_popup_item_append()

EOAPI Elm_Widget_Item* elm_obj_popup_item_append ( Eo obj,
const char *  label,
Efl_Canvas_Object icon,
Evas_Smart_Cb  func,
const void *  data 
)

Add a new item to a Popup object.

Both an item list and a content could not be set at the same time! once you add an item, the previous content will be removed.

Warning
When the first item is appended to popup object, any previous content of the content area is deleted. At a time, only one of content, content-text and item(s) can be there in a popup content area.
Parameters
[in]objThe object.
[in]labelThe Label of the new item.
[in]iconIcon to be set on new item.
[in]funcConvenience function called when item selected.
[in]dataData passed to func above.
Returns
A handle to the item added or null on errors.

◆ elm_obj_popup_dismiss()

EOAPI void elm_obj_popup_dismiss ( Eo obj)

Dismiss a Popup object.

Since
1.17