2 * @defgroup Naviframe Naviframe
5 * @brief Naviframe is a kind of view manager for the applications.
7 * Naviframe provides functions to switch different pages with stack
8 * mechanism. It means if one page(item) needs to be changed to the new one,
10 * then naviframe would push the new page to it's internal stack. Of course,
12 * then naviframe would push the new page to its internal stack. Of course,
13 >>>>>>> remotes/origin/upstream
14 * it can be back to the previous page by popping the top page. Naviframe
15 * provides some transition effect while the pages are switching (same as
18 * Since each item could keep the different styles, users could keep the
19 * same look & feel for the pages or different styles for the items in it's
23 * Signals that you can add callback for are:
24 * @li "transition,finished" - When the transition is finished in changing
26 * @li "title,clicked" - User clicked title area
28 * Default contents parts of the naviframe items that you can use for are:
29 * @li "default" - A main content of the page
32 * Default content parts of the naviframe that you can use content hooks for
34 * @li "default" - The main content of the current page
35 * @li "icon" - An icon in the title area of the current page
36 * @li "prev_btn" - A button of the current page to go to the previous page
37 * @li "next_btn" - A button of the current page to go to the next page
39 * Default text parts of the naviframe that you can use for are:
40 * @li "default" - Title label in the title area of the current page
41 * @li "subtitle" - Sub-title label in the title area of the current page
43 * Signals that you can add callbacks for are:
44 * @li "transition,finished" - When the transition is finished in changing the
46 * @li "title,clicked" - User clicked title area
48 * Item Signals that you can add callbacks for are:
49 * @li "show,begin" - When the item is started to be top item.
50 * @li "hide,finished" - When a new top item is finished to push onto the
53 * Default content parts of the naviframe items that you can use content hooks
55 * @li "default" - The main content of the page
56 >>>>>>> remotes/origin/upstream
57 * @li "icon" - An icon in the title area
58 * @li "prev_btn" - A button to go to the previous page
59 * @li "next_btn" - A button to go to the next page
61 * Default text parts of the naviframe items that you can use for are:
62 * @li "default" - Title label in the title area
63 * @li "subtitle" - Sub-title label in the title area
65 * Supported elm_object common APIs.
66 * @li elm_object_signal_emit
69 * @li elm_object_part_text_set
70 * @li elm_object_part_text_get
71 * @li elm_object_part_content_set
72 * @li elm_object_part_content_get
73 * @li elm_object_part_content_unset
74 >>>>>>> remotes/origin/upstream
76 * Supported elm_object_item common APIs.
77 * @li elm_object_item_part_text_set
78 * @li elm_object_item_part_text_get
79 * @li elm_object_item_part_content_set
80 * @li elm_object_item_part_content_get
81 * @li elm_object_item_part_content_unset
82 * @li elm_object_item_signal_emit
87 #define ELM_NAVIFRAME_ITEM_CONTENT "elm.swallow.content"
88 #define ELM_NAVIFRAME_ITEM_ICON "elm.swallow.icon"
89 #define ELM_NAVIFRAME_ITEM_OPTIONHEADER "elm.swallow.optionheader"
90 #define ELM_NAVIFRAME_ITEM_TITLE_LABEL "elm.text.title"
91 #define ELM_NAVIFRAME_ITEM_PREV_BTN "elm.swallow.prev_btn"
92 #define ELM_NAVIFRAME_ITEM_TITLE_LEFT_BTN "elm.swallow.left_btn"
93 #define ELM_NAVIFRAME_ITEM_TITLE_RIGHT_BTN "elm.swallow.right_btn"
94 #define ELM_NAVIFRAME_ITEM_TITLE_MORE_BTN "elm.swallow.more_btn"
95 #define ELM_NAVIFRAME_ITEM_CONTROLBAR "elm.swallow.controlbar"
96 #define ELM_NAVIFRAME_ITEM_SIGNAL_OPTIONHEADER_CLOSE "elm,state,optionheader,close", ""
97 #define ELM_NAVIFRAME_ITEM_SIGNAL_OPTIONHEADER_OPEN "elm,state,optionheader,open", ""
98 #define ELM_NAVIFRAME_ITEM_SIGNAL_OPTIONHEADER_INSTANT_CLOSE "elm,state,optionheader,instant_close", ""
99 #define ELM_NAVIFRAME_ITEM_SIGNAL_OPTIONHEADER_INSTANT_OPEN "elm,state,optionheader,instant_open", ""
100 #define ELM_NAVIFRAME_ITEM_SIGNAL_CONTROLBAR_CLOSE "elm,state,controlbar,close", ""
101 #define ELM_NAVIFRAME_ITEM_SIGNAL_CONTROLBAR_OPEN "elm,state,controlbar,open", ""
102 #define ELM_NAVIFRAME_ITEM_SIGNAL_CONTROLBAR_INSTANT_CLOSE "elm,state,controlbar,instant_close", ""
103 #define ELM_NAVIFRAME_ITEM_SIGNAL_CONTROLBAR_INSTANT_OPEN "elm,state,controlbar,instant_open", ""
105 //Available only in a style - "2line"
106 #define ELM_NAVIFRAME_ITEM_OPTIONHEADER2 "elm.swallow.optionheader2"
108 //Available only in a style - "segment"
109 #define ELM_NAVIFRAME_ITEM_SEGMENT2 "elm.swallow.segment2"
110 #define ELM_NAVIFRAME_ITEM_SEGMENT3 "elm.swallow.segment3"
113 >>>>>>> remotes/origin/upstream
115 * @addtogroup Naviframe
120 * @brief Add a new Naviframe object to the parent.
122 * @param parent Parent object
123 * @return New object or @c NULL, if it cannot be created
127 EAPI Evas_Object *elm_naviframe_add(Evas_Object *parent);
130 * @brief Push a new item to the top of the naviframe stack (and show it).
132 * @param obj The naviframe object
133 * @param title_label The label in the title area. The name of the title
134 * label part is "elm.text.title"
135 * @param prev_btn The button to go to the previous item. If it is NULL,
136 * then naviframe will create a back button automatically. The name of
137 * the prev_btn part is "elm.swallow.prev_btn"
138 * @param next_btn The button to go to the next item. Or It could be just an
139 * extra function button. The name of the next_btn part is
140 * "elm.swallow.next_btn"
141 * @param content The main content object. The name of content part is
142 * "elm.swallow.content"
143 * @param item_style The current item style name. @c NULL would be default.
144 * @return The created item or @c NULL upon failure.
146 * The item pushed becomes one page of the naviframe, this item will be
147 * deleted when it is popped.
149 * @see also elm_naviframe_item_style_set()
150 * @see also elm_naviframe_item_insert_before()
151 * @see also elm_naviframe_item_insert_after()
153 * The following styles are available for this item:
158 EAPI 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);
161 * @brief Insert a new item into the naviframe before item @p before.
165 * @param obj The naviframe object
166 >>>>>>> remotes/origin/upstream
167 * @param before The naviframe item to insert before.
168 * @param title_label The label in the title area. The name of the title
169 * label part is "elm.text.title"
170 * @param prev_btn The button to go to the previous item. If it is NULL,
171 * then naviframe will create a back button automatically. The name of
172 * the prev_btn part is "elm.swallow.prev_btn"
173 * @param next_btn The button to go to the next item. Or It could be just an
174 * extra function button. The name of the next_btn part is
175 * "elm.swallow.next_btn"
176 * @param content The main content object. The name of content part is
177 * "elm.swallow.content"
178 * @param item_style The current item style name. @c NULL would be default.
179 * @return The created item or @c NULL upon failure.
181 * The item is inserted into the naviframe straight away without any
182 * transition operations. This item will be deleted when it is popped.
184 * @see also elm_naviframe_item_style_set()
185 * @see also elm_naviframe_item_push()
186 * @see also elm_naviframe_item_insert_after()
188 * The following styles are available for this item:
194 EAPI Elm_Object_Item *elm_naviframe_item_insert_before(Elm_Object_Item *before, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style);
196 EAPI 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);
197 >>>>>>> remotes/origin/upstream
200 * @brief Insert a new item into the naviframe after item @p after.
204 * @param obj The naviframe object
205 >>>>>>> remotes/origin/upstream
206 * @param after The naviframe item to insert after.
207 * @param title_label The label in the title area. The name of the title
208 * label part is "elm.text.title"
209 * @param prev_btn The button to go to the previous item. If it is NULL,
210 * then naviframe will create a back button automatically. The name of
211 * the prev_btn part is "elm.swallow.prev_btn"
212 * @param next_btn The button to go to the next item. Or It could be just an
213 * extra function button. The name of the next_btn part is
214 * "elm.swallow.next_btn"
215 * @param content The main content object. The name of content part is
216 * "elm.swallow.content"
217 * @param item_style The current item style name. @c NULL would be default.
218 * @return The created item or @c NULL upon failure.
220 * The item is inserted into the naviframe straight away without any
221 * transition operations. This item will be deleted when it is popped.
223 * @see also elm_naviframe_item_style_set()
224 * @see also elm_naviframe_item_push()
225 * @see also elm_naviframe_item_insert_before()
227 * The following styles are available for this item:
233 EAPI Elm_Object_Item *elm_naviframe_item_insert_after(Elm_Object_Item *after, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style);
235 EAPI 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);
236 >>>>>>> remotes/origin/upstream
239 * @brief Pop an item that is on top of the stack
241 * @param obj The naviframe object
242 * @return @c NULL or the content object(if the
243 * elm_naviframe_content_preserve_on_pop_get is true).
245 * This pops an item that is on the top(visible) of the naviframe, makes it
246 * disappear, then deletes the item. The item that was underneath it on the
247 * stack will become visible.
249 * @see also elm_naviframe_content_preserve_on_pop_get()
253 EAPI Evas_Object *elm_naviframe_item_pop(Evas_Object *obj);
256 * @brief Pop the items between the top and the above one on the given item.
258 * @param it The naviframe item
262 EAPI void elm_naviframe_item_pop_to(Elm_Object_Item *it);
265 * Promote an item already in the naviframe stack to the top of the stack
267 * @param it The naviframe item
269 * This will take the indicated item and promote it to the top of the stack
270 * as if it had been pushed there. The item must already be inside the
271 * naviframe stack to work.
274 EAPI void elm_naviframe_item_promote(Elm_Object_Item *it);
277 * @brief preserve the content objects when items are popped.
279 * @param obj The naviframe object
280 * @param preserve Enable the preserve mode if EINA_TRUE, disable otherwise
282 * @see also elm_naviframe_content_preserve_on_pop_get()
286 EAPI void elm_naviframe_content_preserve_on_pop_set(Evas_Object *obj, Eina_Bool preserve);
289 * @brief Get a value whether preserve mode is enabled or not.
291 * @param obj The naviframe object
292 * @return If @c EINA_TRUE, preserve mode is enabled
294 * @see also elm_naviframe_content_preserve_on_pop_set()
298 EAPI Eina_Bool elm_naviframe_content_preserve_on_pop_get(const Evas_Object *obj);
301 * @brief Get a top item on the naviframe stack
303 * @param obj The naviframe object
304 * @return The top item on the naviframe stack or @c NULL, if the stack is
309 EAPI Elm_Object_Item *elm_naviframe_top_item_get(const Evas_Object *obj);
312 * @brief Get a bottom item on the naviframe stack
314 * @param obj The naviframe object
315 * @return The bottom item on the naviframe stack or @c NULL, if the stack is
320 EAPI Elm_Object_Item *elm_naviframe_bottom_item_get(const Evas_Object *obj);
323 * @brief Set an item style
325 * @param it The naviframe item
326 * @param item_style The current item style name. @c NULL would be default
328 * The following styles are available for this item:
331 * @see also elm_naviframe_item_style_get()
335 EAPI void elm_naviframe_item_style_set(Elm_Object_Item *it, const char *item_style);
338 * @brief Get an item style
340 * @param it The naviframe item
341 * @return The current item style name
343 * @see also elm_naviframe_item_style_set()
347 EAPI const char *elm_naviframe_item_style_get(const Elm_Object_Item *it);
350 * @brief Show/Hide the title area
352 * @param it The naviframe item
353 * @param visible If @c EINA_TRUE, title area will be visible, hidden
356 * When the title area is invisible, then the controls would be hidden so as * to expand the content area to full-size.
358 * @see also elm_naviframe_item_title_visible_get()
362 EAPI void elm_naviframe_item_title_visible_set(Elm_Object_Item *it, Eina_Bool visible);
365 * @brief Get a value whether title area is visible or not.
367 * @param it The naviframe item
368 * @return If @c EINA_TRUE, title area is visible
370 * @see also elm_naviframe_item_title_visible_set()
374 EAPI Eina_Bool elm_naviframe_item_title_visible_get(const Elm_Object_Item *it);
377 * @brief Set creating prev button automatically or not
379 * @param obj The naviframe object
380 * @param auto_pushed If @c EINA_TRUE, the previous button(back button) will
381 * be created internally when you pass the @c NULL to the prev_btn
382 * parameter in elm_naviframe_item_push
384 * @see also elm_naviframe_item_push()
388 EAPI void elm_naviframe_prev_btn_auto_pushed_set(Evas_Object *obj, Eina_Bool auto_pushed);
391 * @brief Get a value whether prev button(back button) will be auto pushed or
394 * @param obj The naviframe object
395 * @return If @c EINA_TRUE, prev button will be auto pushed.
397 * @see also elm_naviframe_item_push()
398 * elm_naviframe_prev_btn_auto_pushed_set()
402 EAPI Eina_Bool elm_naviframe_prev_btn_auto_pushed_get(const Evas_Object *obj);
405 * @brief Get a list of all the naviframe items.
407 * @param obj The naviframe object
409 * @return An Eina_Inlist* of naviframe items, #Elm_Object_Item,
410 * or @c NULL on failure.
414 EAPI Eina_Inlist *elm_naviframe_items_get(const Evas_Object *obj);
416 * @return An Eina_List of naviframe items, #Elm_Object_Item,
417 * or @c NULL on failure.
418 * @note The returned list MUST be freed.
422 EAPI Eina_List *elm_naviframe_items_get(const Evas_Object *obj) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
423 >>>>>>> remotes/origin/upstream
426 * @brief Set the event enabled when pushing/popping items
428 * If @c enabled is EINA_TRUE, the contents of the naviframe item will
429 * receives events from mouse and keyboard during view changing such as
432 * @param obj The naviframe object
433 * @param enabled Events are received when enabled is @c EINA_TRUE, and
436 * @warning Events will be blocked by calling evas_object_freeze_events_set()
437 * internally. So don't call the API whiling pushing/popping items.
439 * @see elm_naviframe_event_enabled_get()
440 * @see evas_object_freeze_events_set()
444 EAPI void elm_naviframe_event_enabled_set(Evas_Object *obj, Eina_Bool enabled);
447 * @brief Get the value of event enabled status.
449 * @param obj The naviframe object
450 * @return EINA_TRUE, when event is enabled
452 * @see elm_naviframe_event_enabled_set()
456 EAPI Eina_Bool elm_naviframe_event_enabled_get(const Evas_Object *obj);
461 * @brief Simple version of item_push.
463 * @see elm_naviframe_item_push
465 static inline Elm_Object_Item *
466 elm_naviframe_item_simple_push(Evas_Object *obj, Evas_Object *content)
469 it = elm_naviframe_item_push(obj, NULL, NULL, NULL, content, NULL);
470 elm_naviframe_item_title_visible_set(it, EINA_FALSE);
475 * @brief Simple version of item_promote.
477 * @see elm_naviframe_item_promote
479 EAPI void elm_naviframe_item_simple_promote(Evas_Object *obj, Evas_Object *content);
482 >>>>>>> remotes/origin/upstream