2 * @defgroup Naviframe Naviframe
5 * @image html naviframe_inheritance_tree.png
6 * @image latex naviframe_inheritance_tree.eps
8 * @brief Naviframe stands for navigation frame. It's a views manager
11 * A naviframe holds views (or pages) as its items. Those items are
12 * organized in a stack, so that new items get pushed on top of the
13 * old, and only the topmost view is displayed at one time. The
14 * transition between views is animated, depending on the theme
15 * applied to the widget.
17 * Naviframe views hold spaces to various elements, which are:
18 * - back button, used to navigate to previous views,
19 * - next button, used to navigate to next views in the stack,
25 * This widget inherits from the @ref Layout one, so that all the
26 * functions acting on it also work for naviframe objects.
28 * Because this widget is a layout, one places content on those areas
29 * by using elm_layout_content_set() on the right swallow part names
30 * expected for each, which are:
31 * @li @c "default" - The main content of the current page
32 * @li @c "icon" - An icon in the title area of the current page
33 * @li @c "prev_btn" - A button of the current page to go to the
35 * @li @c "next_btn" - A button of the current page to go to the next
38 * For text, elm_layout_text_set() will work here on:
39 * @li @c "default" - Title label in the title area of the current
41 * @li @c "subtitle" - Sub-title label in the title area of the
44 * Most of those content objects can be passed at the time of an item
45 * creation (see elm_naviframe_item_push()).
47 * Naviframe items can have different styles, which affect the
48 * transition between views, for example. On the default theme, two of
50 * - @c "basic" - views are switched sliding horizontally, one after
52 * - @c "overlap" - like the previous one, but the previous view stays
53 * at its place and is overlapped by the new
56 * This widget emits the following signals, besides the ones sent from
58 * @li @c "transition,finished" - When the transition is finished in
60 * @li @c "title,clicked" - User clicked title area
62 * All the parts, for content and text, described here will also be
63 * reachable by naviframe @b items direct calls:
64 * @li @ref elm_object_item_part_text_set
65 * @li @ref elm_object_item_part_text_get
66 * @li @ref elm_object_item_part_content_set
67 * @li @ref elm_object_item_part_content_get
68 * @li @ref elm_object_item_part_content_unset
69 * @li @ref elm_object_item_signal_emit
71 * What happens is that the topmost item of a naviframe will be the
72 * widget's target layout, when accessed directly. Items lying below
73 * the top one can be interacted with this way.
77 * @typedef Elm_Naviframe_Item_Pop_Cb
79 * Pop callback called when @c it is going to be popped. @c data is user
82 * @see elm_naviframe_item_pop_cb_set()
86 typedef void (*Elm_Naviframe_Item_Pop_Cb)(void *data, Elm_Object_Item *it);
89 * @addtogroup Naviframe
94 * @brief Add a new Naviframe object to the parent.
96 * @param parent Parent object
97 * @return New object or @c NULL, if it cannot be created
101 EAPI Evas_Object *elm_naviframe_add(Evas_Object *parent);
104 * @brief Push a new item to the top of the naviframe stack (and show it).
106 * @param obj The naviframe object
107 * @param title_label The label in the title area. The name of the title
108 * label part is "elm.text.title"
109 * @param prev_btn The button to go to the previous item. If it is NULL,
110 * then naviframe will create a back button automatically. The name of
111 * the prev_btn part is "elm.swallow.prev_btn"
112 * @param next_btn The button to go to the next item. Or It could be just an
113 * extra function button. The name of the next_btn part is
114 * "elm.swallow.next_btn"
115 * @param content The main content object. The name of content part is
116 * "elm.swallow.content"
117 * @param item_style The current item style name. @c NULL would be default.
118 * @return The created item or @c NULL upon failure.
120 * The item pushed becomes one page of the naviframe, this item will be
121 * deleted when it is popped.
123 * @see also elm_naviframe_item_style_set()
124 * @see also elm_naviframe_item_insert_before()
125 * @see also elm_naviframe_item_insert_after()
127 * The following styles are available for this item:
132 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);
135 * @brief Insert a new item into the naviframe before item @p before.
137 * @param obj The naviframe object
138 * @param before The naviframe item to insert before.
139 * @param title_label The label in the title area. The name of the title
140 * label part is "elm.text.title"
141 * @param prev_btn The button to go to the previous item. If it is NULL,
142 * then naviframe will create a back button automatically. The name of
143 * the prev_btn part is "elm.swallow.prev_btn"
144 * @param next_btn The button to go to the next item. Or It could be just an
145 * extra function button. The name of the next_btn part is
146 * "elm.swallow.next_btn"
147 * @param content The main content object. The name of content part is
148 * "elm.swallow.content"
149 * @param item_style The current item style name. @c NULL would be default.
150 * @return The created item or @c NULL upon failure.
152 * The item is inserted into the naviframe straight away without any
153 * transition operations. This item will be deleted when it is popped.
155 * @see also elm_naviframe_item_style_set()
156 * @see also elm_naviframe_item_push()
157 * @see also elm_naviframe_item_insert_after()
159 * The following styles are available for this item:
164 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);
167 * @brief Insert a new item into the naviframe after item @p after.
169 * @param obj The naviframe object
170 * @param after The naviframe item to insert after.
171 * @param title_label The label in the title area. The name of the title
172 * label part is "elm.text.title"
173 * @param prev_btn The button to go to the previous item. If it is NULL,
174 * then naviframe will create a back button automatically. The name of
175 * the prev_btn part is "elm.swallow.prev_btn"
176 * @param next_btn The button to go to the next item. Or It could be just an
177 * extra function button. The name of the next_btn part is
178 * "elm.swallow.next_btn"
179 * @param content The main content object. The name of content part is
180 * "elm.swallow.content"
181 * @param item_style The current item style name. @c NULL would be default.
182 * @return The created item or @c NULL upon failure.
184 * The item is inserted into the naviframe straight away without any
185 * transition operations. This item will be deleted when it is popped.
187 * @see also elm_naviframe_item_style_set()
188 * @see also elm_naviframe_item_push()
189 * @see also elm_naviframe_item_insert_before()
191 * The following styles are available for this item:
196 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);
199 * @brief Pop an item that is on top of the stack
201 * @param obj The naviframe object
202 * @return @c NULL or the content object(if the
203 * elm_naviframe_content_preserve_on_pop_get is true).
205 * This pops an item that is on the top(visible) of the naviframe, makes it
206 * disappear, then deletes the item. The item that was underneath it on the
207 * stack will become visible.
209 * @see also elm_naviframe_content_preserve_on_pop_get()
210 * @see also elm_naviframe_item_pop_cb_set()
214 EAPI Evas_Object *elm_naviframe_item_pop(Evas_Object *obj);
217 * @brief Pop the items between the top and the above one on the given item.
219 * @param it The naviframe item
223 EAPI void elm_naviframe_item_pop_to(Elm_Object_Item *it);
226 * Promote an item already in the naviframe stack to the top of the stack
228 * @param it The naviframe item
230 * This will take the indicated item and promote it to the top of the stack
231 * as if it had been pushed there. The item must already be inside the
232 * naviframe stack to work.
235 EAPI void elm_naviframe_item_promote(Elm_Object_Item *it);
238 * @brief preserve the content objects when items are popped.
240 * @param obj The naviframe object
241 * @param preserve Enable the preserve mode if EINA_TRUE, disable otherwise
243 * @see also elm_naviframe_content_preserve_on_pop_get()
247 EAPI void elm_naviframe_content_preserve_on_pop_set(Evas_Object *obj, Eina_Bool preserve);
250 * @brief Get a value whether preserve mode is enabled or not.
252 * @param obj The naviframe object
253 * @return If @c EINA_TRUE, preserve mode is enabled
255 * @see also elm_naviframe_content_preserve_on_pop_set()
259 EAPI Eina_Bool elm_naviframe_content_preserve_on_pop_get(const Evas_Object *obj);
262 * @brief Get a top item on the naviframe stack
264 * @param obj The naviframe object
265 * @return The top item on the naviframe stack or @c NULL, if the stack is
270 EAPI Elm_Object_Item *elm_naviframe_top_item_get(const Evas_Object *obj);
273 * @brief Get a bottom item on the naviframe stack
275 * @param obj The naviframe object
276 * @return The bottom item on the naviframe stack or @c NULL, if the stack is
281 EAPI Elm_Object_Item *elm_naviframe_bottom_item_get(const Evas_Object *obj);
284 * @brief Set an item style
286 * @param it The naviframe item
287 * @param item_style The current item style name. @c NULL would be default
289 * The following styles are available for this item:
292 * @see also elm_naviframe_item_style_get()
296 EAPI void elm_naviframe_item_style_set(Elm_Object_Item *it, const char *item_style);
299 * @brief Get an item style
301 * @param it The naviframe item
302 * @return The current item style name
304 * @see also elm_naviframe_item_style_set()
308 EAPI const char *elm_naviframe_item_style_get(const Elm_Object_Item *it);
311 * @brief Show/Hide the title area
313 * @param it The naviframe item
314 * @param visible If @c EINA_TRUE, title area will be visible, hidden
317 * When the title area is invisible, then the controls would be hidden so as * to expand the content area to full-size.
319 * @see also elm_naviframe_item_title_visible_get()
323 EAPI void elm_naviframe_item_title_visible_set(Elm_Object_Item *it, Eina_Bool visible);
326 * @brief Get a value whether title area is visible or not.
328 * @param it The naviframe item
329 * @return If @c EINA_TRUE, title area is visible
331 * @see also elm_naviframe_item_title_visible_set()
335 EAPI Eina_Bool elm_naviframe_item_title_visible_get(const Elm_Object_Item *it);
338 * @brief Set a function to be called when @c it of the naviframe is going to be
341 * @param it The item to set the callback on
342 * @param func the callback function.
344 * @warning Don't set "clicked" callback to the prev button additionally if the
345 * function does a exact same logic with this @c func. When hardware back key is
346 * pressed then both callbacks will be called.
351 EAPI void elm_naviframe_item_pop_cb_set(Elm_Object_Item *it, Elm_Naviframe_Item_Pop_Cb func, void *data);
354 * @brief Set creating prev button automatically or not
356 * @param obj The naviframe object
357 * @param auto_pushed If @c EINA_TRUE, the previous button(back button) will
358 * be created internally when you pass the @c NULL to the prev_btn
359 * parameter in elm_naviframe_item_push
361 * @see also elm_naviframe_item_push()
365 EAPI void elm_naviframe_prev_btn_auto_pushed_set(Evas_Object *obj, Eina_Bool auto_pushed);
368 * @brief Get a value whether prev button(back button) will be auto pushed or
371 * @param obj The naviframe object
372 * @return If @c EINA_TRUE, prev button will be auto pushed.
374 * @see also elm_naviframe_item_push()
375 * elm_naviframe_prev_btn_auto_pushed_set()
379 EAPI Eina_Bool elm_naviframe_prev_btn_auto_pushed_get(const Evas_Object *obj);
382 * @brief Get a list of all the naviframe items.
384 * @param obj The naviframe object
385 * @return An Eina_List of naviframe items, #Elm_Object_Item,
386 * or @c NULL on failure.
387 * @note The returned list MUST be freed.
391 EAPI Eina_List *elm_naviframe_items_get(const Evas_Object *obj) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
394 * @brief Set the event enabled when pushing/popping items
396 * If @c enabled is EINA_TRUE, the contents of the naviframe item will
397 * receives events from mouse and keyboard during view changing such as
400 * @param obj The naviframe object
401 * @param enabled Events are received when enabled is @c EINA_TRUE, and
404 * @warning Events will be blocked by calling evas_object_freeze_events_set()
405 * internally. So don't call the API whiling pushing/popping items.
407 * @see elm_naviframe_event_enabled_get()
408 * @see evas_object_freeze_events_set()
412 EAPI void elm_naviframe_event_enabled_set(Evas_Object *obj, Eina_Bool enabled);
415 * @brief Get the value of event enabled status.
417 * @param obj The naviframe object
418 * @return EINA_TRUE, when event is enabled
420 * @see elm_naviframe_event_enabled_set()
424 EAPI Eina_Bool elm_naviframe_event_enabled_get(const Evas_Object *obj);
427 * @brief Simple version of item_push.
429 * @see elm_naviframe_item_push
431 static inline Elm_Object_Item *
432 elm_naviframe_item_simple_push(Evas_Object *obj, Evas_Object *content)
435 it = elm_naviframe_item_push(obj, NULL, NULL, NULL, content, NULL);
436 elm_naviframe_item_title_visible_set(it, EINA_FALSE);
441 * @brief Simple version of item_promote.
443 * @see elm_naviframe_item_promote
445 EAPI void elm_naviframe_item_simple_promote(Evas_Object *obj, Evas_Object *content);