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 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.


Item Based Layout
 Item Based Layout consists of Title Area, Content of Items,
 and Action Area. Title Area which consists of Text locates
 in the upper side of this Layout, a list of Items in the middle,
 and an Action Area which consists of Buttons in the bottom.


Content Based Layout
 Content Based Layout consists of Title Area, Content, and Action Area.
 Title Area which consists of Text locates  in the upper side of
 this Layout, Content in the middle, and an Action Area which consists of
 Buttons in the bottom.


Description Based Layout
 Description Based Layout consists of Title Area, Content of Description,
 and Action Area. Title Area which consists of Text locates in the
 upper side of this layout, Description in the middle, and Action Area
 which consists of Buttons in the bottom.

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.

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

Since (EFL) :: 1.8).

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

"timeout" - whenever popup is closed as a result of timeout.
"block,clicked" - whenever user taps on Blocked Event area.
"language,changed" - The program's language changed. (
Since (EFL) :
1.8)
"show,finished" - When the popup transition is finished in showing.

Styles available for Popup

"default"

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

"default" - The content of the popup
"title,icon" - Title area's icon
"button1" - 1st button of the action area
"button2" - 2nd button of the action area
"button3" - 3rd button of the action area

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

"title,text" - This operates on Title area's label
"default" - content-text set in the content area of the widget

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

"default" -Item's icon

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

"default" - Item's label

Supported elm_object_item common APIs.

Functions
Evas_Object *	elm_popup_add (Evas_Object *parent)
	Adds a new Popup to the parent.
Elm_Object_Item *	elm_popup_item_append (Evas_Object obj, const char label, Evas_Object icon, Evas_Smart_Cb func, const void data)
	Add a new item to a Popup object.
void	elm_popup_content_text_wrap_type_set (Evas_Object *obj, Elm_Wrap_Type wrap)
	Sets the wrapping type of content text packed in content area of popup object.
Elm_Wrap_Type	elm_popup_content_text_wrap_type_get (const Evas_Object *obj)
	Returns the wrapping type of content text packed in content area of popup object.
void	elm_popup_orient_set (Evas_Object *obj, Elm_Popup_Orient orient)
	Sets the orientation of the popup in the parent region.
Elm_Popup_Orient	elm_popup_orient_get (const Evas_Object *obj)
	Returns the orientation of Popup.
void	elm_popup_timeout_set (Evas_Object *obj, double timeout)
	Sets a timeout to hide popup automatically.
double	elm_popup_timeout_get (const Evas_Object *obj)
	Returns the timeout value set to the popup (in seconds)
void	elm_popup_allow_events_set (Evas_Object *obj, Eina_Bool allow)
	Sets whether events should be passed to by a click outside.
Eina_Bool	elm_popup_allow_events_get (const Evas_Object *obj)
	Returns value indicating whether allow event is enabled or not.
void	elm_popup_align_set (Evas_Object *obj, double horizontal, double vertical)
	Set the alignment of the popup object.
void	elm_popup_align_get (const Evas_Object obj, double horizontal, double *vertical)
	Get the alignment of the popup object.
void	elm_popup_dismiss (Evas_Object *obj)
	Dismiss a popup object.

Enumeration Type Documentation

enum Elm_Popup_Orient

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, don't use

Function Documentation

Evas_Object* elm_popup_add ( Evas_Object * parent )

Adds a new Popup to the parent.

Since :: 2.3.1

Parameters:

[in] parent The parent object

Returns:: The new object or NULL if it cannot be created

void elm_popup_align_get	(	const Evas_Object *	obj,
		double *	horizontal,
		double *	vertical
	)

Get the alignment of the popup object.

Since (EFL) :: 1.9

Since :: 2.3.1

Parameters:

[in]	obj	The popup object
[out]	horizontal	The horizontal alignment of the popup
[out]	vertical	The vertical alignment of the popup

See also:: elm_popup_align_set()

void elm_popup_align_set	(	Evas_Object *	obj,
		double	horizontal,
		double	vertical
	)

Set the alignment of the popup object.

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

Since (EFL) :: 1.9

Since :: 2.3.1

Parameters:

[in]	obj	popup object
[in]	horizontal	The horizontal alignment of the popup
[in]	vertical	The vertical alignment of the popup

See also:: elm_popup_align_get()

Eina_Bool elm_popup_allow_events_get ( const Evas_Object * obj )

Returns value indicating whether allow event is enabled or not.

Since :: 2.3.1

Parameters:

[in] obj The popup object

Returns:: EINA_FALSE if Blocked event area is present else EINA_TRUE

See also:: elm_popup_allow_events_set()

Note:: By default the Blocked event area is present

void elm_popup_allow_events_set	(	Evas_Object *	obj,
		Eina_Bool	allow
	)

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

Since :: 2.3.1

Parameters:

[in]	obj	The popup object
[in]	allow	EINA_TRUE Events are passed to lower objects, else not

Remarks:: Enabling allow event will remove the Blocked event area and events will pass to the lower layer objects otherwise they are blocked.; The default value is EINA_FALSE.

See also:: elm_popup_allow_events_get()

Elm_Wrap_Type elm_popup_content_text_wrap_type_get ( const Evas_Object * obj )

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

Since :: 2.3.1

Parameters:

[in] obj The Popup object

Returns:: wrap type of the content text

See also:: elm_popup_content_text_wrap_type_set

void elm_popup_content_text_wrap_type_set	(	Evas_Object *	obj,
		Elm_Wrap_Type	wrap
	)

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

Since :: 2.3.1

Parameters:

[in]	obj	The Popup object
[in]	wrap	wrapping type of type Elm_Wrap_Type

See also:: elm_popup_content_text_wrap_type_get()

void elm_popup_dismiss ( Evas_Object * obj )

Dismiss a popup object.

Since :: 2.3.1

Parameters:

[in] obj The popup object

Use this function to dismiss the popup with hide effect. when the popup is dismissed, the "dismissed" signal will be emitted.

Elm_Object_Item* elm_popup_item_append	(	Evas_Object *	obj,
		const char *	label,
		Evas_Object *	icon,
		Evas_Smart_Cb	func,
		const void *	data
	)

Add a new item to a Popup object.

Since :: 2.3.1

Remarks:: 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.; 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]	obj	popup object
[in]	icon	Icon to be set on new item
[in]	label	The Label of the new item
[in]	func	Convenience function called when item selected
[in]	data	Data passed to `func` above

Returns:: A handle to the item added or NULL, on errors

Elm_Popup_Orient elm_popup_orient_get ( const Evas_Object * obj )

Returns the orientation of Popup.

Since :: 2.3.1

Parameters:

[in] obj The popup object

Returns:: the orientation of the popup

See also:: elm_popup_orient_set(); Elm_Popup_Orient

void elm_popup_orient_set	(	Evas_Object *	obj,
		Elm_Popup_Orient	orient
	)

Sets the orientation of the popup in the parent region.

Since :: 2.3.1

Parameters:

[in]	obj	The popup object
[in]	orient	the orientation of the popup

Sets the position in which popup will appear in its parent

See also:: Elm_Popup_Orient for possible values.

double elm_popup_timeout_get ( const Evas_Object * obj )

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

Since :: 2.3.1

Parameters:

[in] obj The popup object

Returns:: the timeout value

See also:: elm_popup_timeout_set()

void elm_popup_timeout_set	(	Evas_Object *	obj,
		double	timeout
	)

Sets a timeout to hide popup automatically.

Since :: 2.3.1

Parameters:

[in]	obj	The popup object
[in]	timeout	The timeout in seconds

This function sets a timeout and starts the timer controlling when the popup is hidden.

Remarks:: 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.; 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.

Functions

Enumeration Type Documentation

Function Documentation