Tizen Native API

Naviframe stands for navigation frame. It's a views manager for applications.

naviframe_inheritance_tree.png

A naviframe holds views (or pages) as its items. Those items are organized in a stack, so that new items get pushed on top of the old, and only the topmost view is displayed at one time. The transition between views is animated, depending on the theme applied to the widget.

Naviframe views hold spaces to various elements, which are:

  • back button, used to navigate to previous views,
  • next button, used to navigate to next views in the stack,
  • title label,
  • sub-title label,
  • title icon and
  • content area.

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

Because this widget is a layout, one places content on those areas by using elm_layout_content_set() on the right swallow part names expected for each, which are:

  • "default" - The main content of the current page
  • "icon" - An icon in the title area of the current page
  • "prev_btn" - A button of the current page to go to the previous page
  • "next_btn" - A button of the current page to go to the next page

For text, elm_layout_text_set() will work here on:

  • "default" - Title label in the title area of the current page
  • "subtitle" - Sub-title label in the title area of the current page

Most of those content objects can be passed at the time of an item creation (see elm_naviframe_item_push()).

Naviframe items can have different styles, which affect the transition between views, for example. On the default theme, two of them are supported:

  • "basic" - views are switched sliding horizontally, one after the other
  • "overlap" - like the previous one, but the previous view stays at its place and is overlapped by the new

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

  • "transition,finished" - When the transition is finished in changing the item
  • "title,transition,finished" - When the title transition is finished in changing enabled state of the title
  • "title,clicked" - User clicked title area

All the parts, for content and text, described here will also be reachable by naviframe items direct calls:

What happens is that the topmost item of a naviframe will be the widget's target layout, when accessed directly. Items lying below the top one can be interacted with this way.

Functions

Evas_Objectelm_naviframe_add (Evas_Object *parent)
 Add a new Naviframe object to the parent.
Elm_Object_Itemelm_naviframe_item_push (Evas_Object *obj, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style)
 Push a new item to the top of the naviframe stack (and show it).
Elm_Object_Itemelm_naviframe_item_insert_before (Evas_Object *obj, Elm_Object_Item *before, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style)
 Insert a new item into the naviframe before item before.
Elm_Object_Itemelm_naviframe_item_insert_after (Evas_Object *obj, Elm_Object_Item *after, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style)
 Insert a new item into the naviframe after item after.
Evas_Objectelm_naviframe_item_pop (Evas_Object *obj)
 Pop an item that is on top of the stack.
void elm_naviframe_item_pop_to (Elm_Object_Item *it)
 Pop the top item and delete the items between the top and the above one on the given item.
void elm_naviframe_item_promote (Elm_Object_Item *it)
 Promote an item already in the naviframe stack to the top of the stack.
void elm_naviframe_content_preserve_on_pop_set (Evas_Object *obj, Eina_Bool preserve)
 preserve the content objects when items are popped.
Eina_Bool elm_naviframe_content_preserve_on_pop_get (const Evas_Object *obj)
 Get a value whether preserve mode is enabled or not.
Elm_Object_Itemelm_naviframe_top_item_get (const Evas_Object *obj)
 Get a top item on the naviframe stack.
Elm_Object_Itemelm_naviframe_bottom_item_get (const Evas_Object *obj)
 Get a bottom item on the naviframe stack.
void elm_naviframe_item_style_set (Elm_Object_Item *it, const char *item_style)
 Set an item style.
const char * elm_naviframe_item_style_get (const Elm_Object_Item *it)
 Get an item style.
void elm_naviframe_item_title_enabled_set (Elm_Object_Item *it, Eina_Bool enabled, Eina_Bool transition)
 Enable/Disable the title area with transition effect.
Eina_Bool elm_naviframe_item_title_enabled_get (const Elm_Object_Item *it)
 Get a value whether title area is enabled or not.
void elm_naviframe_item_pop_cb_set (Elm_Object_Item *it, Elm_Naviframe_Item_Pop_Cb func, void *data)
 Set a function to be called when it of the naviframe is going to be popped.
void elm_naviframe_prev_btn_auto_pushed_set (Evas_Object *obj, Eina_Bool auto_pushed)
 Set creating prev button automatically or not.
Eina_Bool elm_naviframe_prev_btn_auto_pushed_get (const Evas_Object *obj)
 Get a value whether prev button(back button) will be auto pushed or not.
Eina_Listelm_naviframe_items_get (const Evas_Object *obj)
 Get a list of all the naviframe items.
void elm_naviframe_event_enabled_set (Evas_Object *obj, Eina_Bool enabled)
 Set the event enabled when pushing/popping items.
Eina_Bool elm_naviframe_event_enabled_get (const Evas_Object *obj)
 Get the value of event enabled status.
static Elm_Object_Itemelm_naviframe_item_simple_push (Evas_Object *obj, Evas_Object *content)
 Simple version of item_push.
void elm_naviframe_item_simple_promote (Evas_Object *obj, Evas_Object *content)
 Simple version of item_promote.

Typedefs

typedef Eina_Bool(* Elm_Naviframe_Item_Pop_Cb )(void *data, Elm_Object_Item *it)

Typedef Documentation

Since :
2.3.1

Pop callback called when it is going to be popped. data is user specific data. If it returns the EINA_FALSE in the callback, item popping will be cancelled.

See also:
elm_naviframe_item_pop_cb_set()
Since (EFL) :
1.8

Function Documentation

Add a new Naviframe object to the parent.

Since :
2.3.1
Parameters:
[in]parentParent object
Returns:
New object or NULL, if it cannot be created

Get a bottom item on the naviframe stack.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
Returns:
The bottom item on the naviframe stack or NULL, if the stack is empty

Get a value whether preserve mode is enabled or not.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
Returns:
If EINA_TRUE, preserve mode is enabled
See also:
also elm_naviframe_content_preserve_on_pop_set()

preserve the content objects when items are popped.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
[in]preserveEnable the preserve mode if EINA_TRUE, disable otherwise
See also:
also elm_naviframe_content_preserve_on_pop_get()

Get the value of event enabled status.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
Returns:
EINA_TRUE, when event is enabled
See also:
elm_naviframe_event_enabled_set()
void elm_naviframe_event_enabled_set ( Evas_Object obj,
Eina_Bool  enabled 
)

Set the event enabled when pushing/popping items.

Since :
2.3.1
Remarks:
If enabled is EINA_TRUE, the contents of the naviframe item will receives events from mouse and keyboard during view changing such as item push/pop.
Events will be blocked by calling evas_object_freeze_events_set() internally. So don't call the API whiling pushing/popping items.
Parameters:
[in]objThe naviframe object
[in]enabledEvents are received when enabled is EINA_TRUE, and ignored otherwise.
See also:
elm_naviframe_event_enabled_get()
evas_object_freeze_events_set()
Elm_Object_Item* elm_naviframe_item_insert_after ( Evas_Object obj,
Elm_Object_Item after,
const char *  title_label,
Evas_Object prev_btn,
Evas_Object next_btn,
Evas_Object content,
const char *  item_style 
)

Insert a new item into the naviframe after item after.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
[in]afterThe naviframe item to insert after.
[in]title_labelThe label in the title area. The name of the title label part is "elm.text.title"
[in]prev_btnThe button to go to the previous item. If it is NULL, then naviframe will create a back button automatically. The name of the prev_btn part is "elm.swallow.prev_btn"
[in]next_btnThe button to go to the next item. Or It could be just an extra function button. The name of the next_btn part is "elm.swallow.next_btn"
[in]contentThe main content object. The name of content part is "elm.swallow.content"
[in]item_styleThe current item style name. NULL would be default.
Returns:
The created item or NULL upon failure.

The item is inserted into the naviframe straight away without any transition operations. This item will be deleted when it is popped.

See also:
also elm_naviframe_item_style_set()
also elm_naviframe_item_push()
also elm_naviframe_item_insert_before()

The following styles are available for this item:

  • "default"
Elm_Object_Item* elm_naviframe_item_insert_before ( Evas_Object obj,
Elm_Object_Item before,
const char *  title_label,
Evas_Object prev_btn,
Evas_Object next_btn,
Evas_Object content,
const char *  item_style 
)

Insert a new item into the naviframe before item before.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
[in]beforeThe naviframe item to insert before.
[in]title_labelThe label in the title area. The name of the title label part is "elm.text.title"
[in]prev_btnThe button to go to the previous item. If it is NULL, then naviframe will create a back button automatically. The name of the prev_btn part is "elm.swallow.prev_btn"
[in]next_btnThe button to go to the next item. Or It could be just an extra function button. The name of the next_btn part is "elm.swallow.next_btn"
[in]contentThe main content object. The name of content part is "elm.swallow.content"
[in]item_styleThe current item style name. NULL would be default.
Returns:
The created item or NULL upon failure.

The item is inserted into the naviframe straight away without any transition operations. This item will be deleted when it is popped.

See also:
also elm_naviframe_item_style_set()
also elm_naviframe_item_push()
also elm_naviframe_item_insert_after()

The following styles are available for this item:

  • "default"

Pop an item that is on top of the stack.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
Returns:
NULL or the content object(if the elm_naviframe_content_preserve_on_pop_get is true).

This pops an item that is on the top(visible) of the naviframe, makes it disappear, then deletes the item. The item that was underneath it on the stack will become visible.

See also:
also elm_naviframe_content_preserve_on_pop_get()
also elm_naviframe_item_pop_cb_set()

Set a function to be called when it of the naviframe is going to be popped.

Since (EFL) :
1.8
Since :
2.3.1
Warning:
Don't set "clicked" callback to the prev button additionally if the function does a exact same logic with this func. When hardware back key is pressed then both callbacks will be called.
The pop callback function is called only if the item is popped. Therefore, the pop callback function is not called if the item is deleted without being popped.
Parameters:
[in]itThe item to set the callback on
[in]functhe callback function.
[in]datauser data

Pop the top item and delete the items between the top and the above one on the given item.

Since :
2.3.1
Remarks:
The items between the top and the given item will be deleted first, and then the top item will be popped at last.
Warning:
The pop callback function set by elm_naviframe_item_pop_cb_set is not called for items between the top item and the destination item since those items are deleted without being popped.
Parameters:
[in]itThe naviframe item

Promote an item already in the naviframe stack to the top of the stack.

Since :
2.3.1
Remarks:
This will take the indicated item and promote it to the top of the stack as if it had been pushed there. The item must already be inside the naviframe stack to work.
Parameters:
[in]itThe naviframe item
Elm_Object_Item* elm_naviframe_item_push ( Evas_Object obj,
const char *  title_label,
Evas_Object prev_btn,
Evas_Object next_btn,
Evas_Object content,
const char *  item_style 
)

Push a new item to the top of the naviframe stack (and show it).

Since :
2.3.1
Parameters:
[in]objThe naviframe object
[in]title_labelThe label in the title area. The name of the title label part is "elm.text.title"
[in]prev_btnThe button to go to the previous item. If it is NULL, then naviframe will create a back button automatically. The name of the prev_btn part is "elm.swallow.prev_btn"
[in]next_btnThe button to go to the next item. Or It could be just an extra function button. The name of the next_btn part is "elm.swallow.next_btn"
[in]contentThe main content object. The name of content part is "elm.swallow.content"
[in]item_styleThe current item style name. NULL would be default.
Returns:
The created item or NULL upon failure.

The item pushed becomes one page of the naviframe, this item will be deleted when it is popped.

See also:
also elm_naviframe_item_style_set()
also elm_naviframe_item_insert_before()
also elm_naviframe_item_insert_after()

The following styles are available for this item:

  • "default"

Simple version of item_promote.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
[in]contentThe main content object. The name of content part is "elm.swallow.content"
See also:
elm_naviframe_item_promote
static Elm_Object_Item* elm_naviframe_item_simple_push ( Evas_Object obj,
Evas_Object content 
) [static]

Simple version of item_push.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
[in]contentThe main content object. The name of content part is "elm.swallow.content"
Returns:
The created item or NULL upon failure.
See also:
elm_naviframe_item_push
const char* elm_naviframe_item_style_get ( const Elm_Object_Item it)

Get an item style.

Since :
2.3.1
Parameters:
[in]itThe naviframe item
Returns:
The current item style name
See also:
also elm_naviframe_item_style_set()
void elm_naviframe_item_style_set ( Elm_Object_Item it,
const char *  item_style 
)

Set an item style.

Since :
2.3.1
Remarks:
The following styles are available for this item:
  • "default"
Parameters:
[in]itThe naviframe item
[in]item_styleThe current item style name. NULL would be default
See also:
also elm_naviframe_item_style_get()

Get a value whether title area is enabled or not.

Since :
2.3.1
Parameters:
[in]itThe naviframe item
Returns:
If EINA_TRUE, title area is enabled
See also:
also elm_naviframe_item_title_enabled_set()
void elm_naviframe_item_title_enabled_set ( Elm_Object_Item it,
Eina_Bool  enabled,
Eina_Bool  transition 
)

Enable/Disable the title area with transition effect.

Since :
2.3.1
Remarks:
When the title area is disabled, then the controls would be hidden so as to expand the content area to full-size.
Parameters:
[in]itThe naviframe item
[in]enabledIf EINA_TRUE, title area will be enabled, disabled otherwise
[in]transitionIf EINA_TRUE, transition effect of the title will be visible, invisible otherwise
See also:
also elm_naviframe_item_title_enabled_get()

Get a list of all the naviframe items.

Since :
2.3.1
Remarks:
The returned list MUST be freed.
Parameters:
[in]objThe naviframe object
Returns:
An Eina_List of naviframe items, Elm_Object_Item, or NULL on failure.

Get a value whether prev button(back button) will be auto pushed or not.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
Returns:
If EINA_TRUE, prev button will be auto pushed.
See also:
also elm_naviframe_item_push() elm_naviframe_prev_btn_auto_pushed_set()

Set creating prev button automatically or not.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
[in]auto_pushedIf EINA_TRUE, the previous button(back button) will be created internally when you pass the NULL to the prev_btn parameter in elm_naviframe_item_push
See also:
also elm_naviframe_item_push()

Get a top item on the naviframe stack.

Since :
2.3.1
Parameters:
[in]objThe naviframe object
Returns:
The top item on the naviframe stack or NULL, if the stack is empty