2 * @defgroup Layout Layout
4 * @image html img/widget/layout/preview-00.png
5 * @image latex img/widget/layout/preview-00.eps width=\textwidth
7 * @image html img/layout-predefined.png
8 * @image latex img/layout-predefined.eps width=\textwidth
10 * This is a container widget that takes a standard Edje design file and
11 * wraps it very thinly in a widget.
13 * An Edje design (theme) file has a very wide range of possibilities to
14 * describe the behavior of elements added to the Layout. Check out the Edje
15 * documentation and the EDC reference to get more information about what can
18 * Just like @ref List, @ref Box, and other container widgets, any
19 * object added to the Layout will become its child, meaning that it will be
20 * deleted if the Layout is deleted, move if the Layout is moved, and so on.
22 * The Layout widget can contain as many Contents, Boxes or Tables as
23 * described in its theme file. For instance, objects can be added to
24 * different Tables by specifying the respective Table part names. The same
25 * is valid for Content and Box.
27 * The objects added as child of the Layout will behave as described in the
28 * part description where they were added. There are 3 possible types of
29 * parts where a child can be added:
31 * @section secContent Content (SWALLOW part)
33 * Only one object can be added to the @c SWALLOW part (but you still can
34 * have many @c SWALLOW parts and one object on each of them). Use the @c
35 * elm_object_content_set/get/unset functions to set, retrieve and unset
36 * objects as content of the @c SWALLOW. After being set to this part, the
37 * object size, position, visibility, clipping and other description
38 * properties will be totally controlled by the description of the given part
39 * (inside the Edje theme file).
41 * One can use @c evas_object_size_hint_* functions on the child to have some
42 * kind of control over its behavior, but the resulting behavior will still
43 * depend heavily on the @c SWALLOW part description.
45 * The Edje theme also can change the part description, based on signals or
46 * scripts running inside the theme. This change can also be animated. All of
47 * this will affect the child object set as content accordingly. The object
48 * size will be changed if the part size is changed, it will animate move if
49 * the part is moving, and so on.
51 * The following picture demonstrates a Layout widget with a child object
52 * added to its @c SWALLOW:
54 * @image html layout_swallow.png
55 * @image latex layout_swallow.eps width=\textwidth
57 * @section secBox Box (BOX part)
59 * An Edje @c BOX part is very similar to the Elementary @ref Box widget. It
60 * allows one to add objects to the box and have them distributed along its
61 * area, accordingly to the specified @a layout property (now by @a layout we
62 * mean the chosen layouting design of the Box, not the Layout widget
65 * A similar effect for having a box with its position, size and other things
66 * controlled by the Layout theme would be to create an Elementary @ref Box
67 * widget and add it as a Content in the @c SWALLOW part.
69 * The main difference of using the Layout Box is that its behavior, the box
70 * properties like layouting format, padding, align, etc. will be all
71 * controlled by the theme. This means, for example, that a signal could be
72 * sent to the Layout theme (with elm_object_signal_emit()) and the theme
73 * handled the signal by changing the box padding, or align, or both. Using
74 * the Elementary @ref Box widget is not necessarily harder or easier, it
76 * just depends on the circunstances and requirements.
78 * just depends on the circumstances and requirements.
79 >>>>>>> remotes/origin/upstream
81 * The Layout Box can be used through the @c elm_layout_box_* set of
84 * The following picture demonstrates a Layout widget with many child objects
85 * added to its @c BOX part:
87 * @image html layout_box.png
88 * @image latex layout_box.eps width=\textwidth
90 * @section secTable Table (TABLE part)
92 * Just like the @ref secBox, the Layout Table is very similar to the
93 * Elementary @ref Table widget. It allows one to add objects to the Table
94 * specifying the row and column where the object should be added, and any
95 * column or row span if necessary.
97 * Again, we could have this design by adding a @ref Table widget to the @c
98 * SWALLOW part using elm_object_part_content_set(). The same difference happens
99 * here when choosing to use the Layout Table (a @c TABLE part) instead of
100 * the @ref Table plus @c SWALLOW part. It's just a matter of convenience.
102 * The Layout Table can be used through the @c elm_layout_table_* set of
105 * The following picture demonstrates a Layout widget with many child objects
106 * added to its @c TABLE part:
108 * @image html layout_table.png
109 * @image latex layout_table.eps width=\textwidth
111 * @section secPredef Predefined Layouts
113 * Another interesting thing about the Layout widget is that it offers some
114 * predefined themes that come with the default Elementary theme. These
115 * themes can be set by the call elm_layout_theme_set(), and provide some
116 * basic functionality depending on the theme used.
118 * Most of them already send some signals, some already provide a toolbar or
119 * back and next buttons.
121 * These are available predefined theme layouts. All of them have class = @c
122 * layout, group = @c application, and style = one of the following options:
124 * @li @c toolbar-content - application with toolbar and main content area
125 * @li @c toolbar-content-back - application with toolbar and main content
126 * area with a back button and title area
127 * @li @c toolbar-content-back-next - application with toolbar and main
128 * content area with a back and next buttons and title area
129 * @li @c content-back - application with a main content area with a back
130 * button and title area
131 * @li @c content-back-next - application with a main content area with a
132 * back and next buttons and title area
133 * @li @c toolbar-vbox - application with toolbar and main content area as a
135 * @li @c toolbar-table - application with toolbar and main content area as a
138 * Supported elm_object common APIs.
139 * @li elm_object_signal_emit
140 * @li elm_object_signal_callback_add
141 * @li elm_object_signal_callback_del
142 * @li elm_object_part_text_set
143 * @li elm_object_part_text_get
144 * @li elm_object_part_content_set
145 * @li elm_object_part_content_get
146 * @li elm_object_part_content_unset
148 * @section secExamples Examples
150 * Some examples of the Layout widget can be found here:
151 * @li @ref layout_example_01
152 * @li @ref layout_example_02
153 * @li @ref layout_example_03
154 * @li @ref layout_example_edc
159 * Add a new layout to the parent
161 * @param parent The parent object
162 * @return The new object or NULL if it cannot be created
164 * @see elm_layout_file_set()
165 * @see elm_layout_theme_set()
169 EAPI Evas_Object *elm_layout_add(Evas_Object *parent);
172 * Set the file that will be used as layout
174 * @param obj The layout object
175 * @param file The path to file (edj) that will be used as layout
176 * @param group The group that the layout belongs in edje file
178 * @return (1 = success, 0 = error)
182 EAPI Eina_Bool elm_layout_file_set(Evas_Object *obj, const char *file, const char *group);
185 * Set the edje group from the elementary theme that will be used as layout
187 * @param obj The layout object
189 * @param clas the clas of the group
191 * @param clas the class of the group
192 >>>>>>> remotes/origin/upstream
193 * @param group the group
194 * @param style the style to used
196 * @return (1 = success, 0 = error)
200 EAPI Eina_Bool elm_layout_theme_set(Evas_Object *obj, const char *clas, const char *group, const char *style);
203 * Append child to layout box part.
205 * @param obj the layout object
206 * @param part the box part to which the object will be appended.
207 * @param child the child object to append to box.
210 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
211 >>>>>>> remotes/origin/upstream
213 * Once the object is appended, it will become child of the layout. Its
214 * lifetime will be bound to the layout, whenever the layout dies the child
215 * will be deleted automatically. One should use elm_layout_box_remove() to
216 * make this layout forget about the object.
218 * @see elm_layout_box_prepend()
219 * @see elm_layout_box_insert_before()
220 * @see elm_layout_box_insert_at()
221 * @see elm_layout_box_remove()
226 EAPI void elm_layout_box_append(Evas_Object *obj, const char *part, Evas_Object *child);
228 EAPI Eina_Bool elm_layout_box_append(Evas_Object *obj, const char *part, Evas_Object *child);
229 >>>>>>> remotes/origin/upstream
232 * Prepend child to layout box part.
234 * @param obj the layout object
235 * @param part the box part to prepend.
236 * @param child the child object to prepend to box.
239 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
240 >>>>>>> remotes/origin/upstream
242 * Once the object is prepended, it will become child of the layout. Its
243 * lifetime will be bound to the layout, whenever the layout dies the child
244 * will be deleted automatically. One should use elm_layout_box_remove() to
245 * make this layout forget about the object.
247 * @see elm_layout_box_append()
248 * @see elm_layout_box_insert_before()
249 * @see elm_layout_box_insert_at()
250 * @see elm_layout_box_remove()
255 EAPI void elm_layout_box_prepend(Evas_Object *obj, const char *part, Evas_Object *child);
257 EAPI Eina_Bool elm_layout_box_prepend(Evas_Object *obj, const char *part, Evas_Object *child);
258 >>>>>>> remotes/origin/upstream
261 * Insert child to layout box part before a reference object.
263 * @param obj the layout object
264 * @param part the box part to insert.
265 * @param child the child object to insert into box.
266 * @param reference another reference object to insert before in box.
269 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
270 >>>>>>> remotes/origin/upstream
272 * Once the object is inserted, it will become child of the layout. Its
273 * lifetime will be bound to the layout, whenever the layout dies the child
274 * will be deleted automatically. One should use elm_layout_box_remove() to
275 * make this layout forget about the object.
277 * @see elm_layout_box_append()
278 * @see elm_layout_box_prepend()
279 * @see elm_layout_box_insert_before()
280 * @see elm_layout_box_remove()
285 EAPI void elm_layout_box_insert_before(Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference);
287 EAPI Eina_Bool elm_layout_box_insert_before(Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference);
288 >>>>>>> remotes/origin/upstream
291 * Insert child to layout box part at a given position.
293 * @param obj the layout object
294 * @param part the box part to insert.
295 * @param child the child object to insert into box.
296 * @param pos the numeric position >=0 to insert the child.
299 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
300 >>>>>>> remotes/origin/upstream
302 * Once the object is inserted, it will become child of the layout. Its
303 * lifetime will be bound to the layout, whenever the layout dies the child
304 * will be deleted automatically. One should use elm_layout_box_remove() to
305 * make this layout forget about the object.
307 * @see elm_layout_box_append()
308 * @see elm_layout_box_prepend()
309 * @see elm_layout_box_insert_before()
310 * @see elm_layout_box_remove()
315 EAPI void elm_layout_box_insert_at(Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos);
317 EAPI Eina_Bool elm_layout_box_insert_at(Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos);
318 >>>>>>> remotes/origin/upstream
321 * Remove a child of the given part box.
323 * @param obj The layout object
324 * @param part The box part name to remove child.
325 * @param child The object to remove from box.
326 * @return The object that was being used, or NULL if not found.
328 * The object will be removed from the box part and its lifetime will
329 * not be handled by the layout anymore. This is equivalent to
330 * elm_object_part_content_unset() for box.
332 * @see elm_layout_box_append()
333 * @see elm_layout_box_remove_all()
337 EAPI Evas_Object *elm_layout_box_remove(Evas_Object *obj, const char *part, Evas_Object *child);
340 * Remove all children of the given part box.
342 * @param obj The layout object
343 * @param part The box part name to remove child.
344 * @param clear If EINA_TRUE, then all objects will be deleted as
345 * well, otherwise they will just be removed and will be
346 * dangling on the canvas.
349 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
350 >>>>>>> remotes/origin/upstream
352 * The objects will be removed from the box part and their lifetime will
353 * not be handled by the layout anymore. This is equivalent to
354 * elm_layout_box_remove() for all box children.
356 * @see elm_layout_box_append()
357 * @see elm_layout_box_remove()
362 EAPI void elm_layout_box_remove_all(Evas_Object *obj, const char *part, Eina_Bool clear);
364 EAPI Eina_Bool elm_layout_box_remove_all(Evas_Object *obj, const char *part, Eina_Bool clear);
365 >>>>>>> remotes/origin/upstream
368 * Insert child to layout table part.
370 * @param obj the layout object
371 * @param part the box part to pack child.
372 * @param child_obj the child object to pack into table.
373 * @param col the column to which the child should be added. (>= 0)
374 * @param row the row to which the child should be added. (>= 0)
375 * @param colspan how many columns should be used to store this object. (>=
377 * @param rowspan how many rows should be used to store this object. (>= 1)
380 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
381 >>>>>>> remotes/origin/upstream
383 * Once the object is inserted, it will become child of the table. Its
384 * lifetime will be bound to the layout, and whenever the layout dies the
385 * child will be deleted automatically. One should use
386 * elm_layout_table_remove() to make this layout forget about the object.
388 * If @p colspan or @p rowspan are bigger than 1, that object will occupy
389 * more space than a single cell. For instance, the following code:
391 * elm_layout_table_pack(layout, "table_part", child, 0, 1, 3, 1);
394 * Would result in an object being added like the following picture:
396 * @image html layout_colspan.png
397 * @image latex layout_colspan.eps width=\textwidth
399 * @see elm_layout_table_unpack()
400 * @see elm_layout_table_clear()
405 EAPI void elm_layout_table_pack(Evas_Object *obj, const char *part, Evas_Object *child_obj, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan);
407 EAPI Eina_Bool elm_layout_table_pack(Evas_Object *obj, const char *part, Evas_Object *child_obj, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan);
408 >>>>>>> remotes/origin/upstream
411 * Unpack (remove) a child of the given part table.
413 * @param obj The layout object
414 * @param part The table part name to remove child.
415 * @param child_obj The object to remove from table.
416 * @return The object that was being used, or NULL if not found.
418 * The object will be unpacked from the table part and its lifetime
419 * will not be handled by the layout anymore. This is equivalent to
420 * elm_object_part_content_unset() for table.
422 * @see elm_layout_table_pack()
423 * @see elm_layout_table_clear()
427 EAPI Evas_Object *elm_layout_table_unpack(Evas_Object *obj, const char *part, Evas_Object *child_obj);
430 * Remove all the child objects of the given part table.
432 * @param obj The layout object
433 * @param part The table part name to remove child.
434 * @param clear If EINA_TRUE, then all objects will be deleted as
435 * well, otherwise they will just be removed and will be
436 * dangling on the canvas.
439 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
440 >>>>>>> remotes/origin/upstream
442 * The objects will be removed from the table part and their lifetime will
443 * not be handled by the layout anymore. This is equivalent to
444 * elm_layout_table_unpack() for all table children.
446 * @see elm_layout_table_pack()
447 * @see elm_layout_table_unpack()
452 EAPI void elm_layout_table_clear(Evas_Object *obj, const char *part, Eina_Bool clear);
454 EAPI Eina_Bool elm_layout_table_clear(Evas_Object *obj, const char *part, Eina_Bool clear);
455 >>>>>>> remotes/origin/upstream
458 * Get the edje layout
460 * @param obj The layout object
462 * @return A Evas_Object with the edje layout settings loaded
463 * with function elm_layout_file_set
465 * This returns the edje object. It is not expected to be used to then
466 * swallow objects via edje_object_part_swallow() for example. Use
467 * elm_object_part_content_set() instead so child object handling and sizing is
470 * @note This function should only be used if you really need to call some
471 * low level Edje function on this edje object. All the common stuff (setting
472 * text, emitting signals, hooking callbacks to signals, etc.) can be done
473 * with proper elementary functions.
475 * @see elm_object_signal_callback_add()
476 * @see elm_object_signal_emit()
477 * @see elm_object_part_text_set()
478 * @see elm_object_part_content_set()
479 * @see elm_layout_box_append()
480 * @see elm_layout_table_pack()
481 * @see elm_layout_data_get()
485 EAPI Evas_Object *elm_layout_edje_get(const Evas_Object *obj);
488 * Get the edje data from the given layout
490 * @param obj The layout object
491 * @param key The data key
493 * @return The edje data string
495 * This function fetches data specified inside the edje theme of this layout.
496 * This function return NULL if data is not found.
498 * In EDC this comes from a data block within the group block that @p
499 * obj was loaded from. E.g.
506 * item: "key1" "value1";
507 * item: "key2" "value2";
515 EAPI const char *elm_layout_data_get(const Evas_Object *obj, const char *key);
520 * @param obj The layout object
522 * Manually forces a sizing re-evaluation. This is useful when the minimum
523 * size required by the edje theme of this layout has changed. The change on
524 * the minimum size required by the edje theme is not immediately reported to
525 * the elementary layout, so one needs to call this function in order to tell
526 * the widget (layout) that it needs to reevaluate its own size.
528 * The minimum size of the theme is calculated based on minimum size of
529 * parts, the size of elements inside containers like box and table, etc. All
530 * of this can change due to state changes, and that's when this function
533 * Also note that a standard signal of "size,eval" "elm" emitted from the
534 * edje object will cause this to happen too.
538 EAPI void elm_layout_sizing_eval(Evas_Object *obj);
541 * Sets a specific cursor for an edje part.
543 * @param obj The layout object.
544 * @param part_name a part from loaded edje group.
545 * @param cursor cursor name to use, see Elementary_Cursor.h
547 * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
548 * part not exists or it has "mouse_events: 0".
552 EAPI Eina_Bool elm_layout_part_cursor_set(Evas_Object *obj, const char *part_name, const char *cursor);
555 * Get the cursor to be shown when mouse is over an edje part
557 * @param obj The layout object.
558 * @param part_name a part from loaded edje group.
559 * @return the cursor name.
563 EAPI const char *elm_layout_part_cursor_get(const Evas_Object *obj, const char *part_name);
566 * Unsets a cursor previously set with elm_layout_part_cursor_set().
568 * @param obj The layout object.
569 * @param part_name a part from loaded edje group, that had a cursor set
570 * with elm_layout_part_cursor_set().
575 EAPI void elm_layout_part_cursor_unset(Evas_Object *obj, const char *part_name);
577 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
581 EAPI Eina_Bool elm_layout_part_cursor_unset(Evas_Object *obj, const char *part_name);
582 >>>>>>> remotes/origin/upstream
585 * Sets a specific cursor style for an edje part.
587 * @param obj The layout object.
588 * @param part_name a part from loaded edje group.
589 * @param style the theme style to use (default, transparent, ...)
591 * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
592 * part not exists or it did not had a cursor set.
596 EAPI Eina_Bool elm_layout_part_cursor_style_set(Evas_Object *obj, const char *part_name, const char *style);
599 * Gets a specific cursor style for an edje part.
601 * @param obj The layout object.
602 * @param part_name a part from loaded edje group.
604 * @return the theme style in use, defaults to "default". If the
605 * object does not have a cursor set, then NULL is returned.
609 EAPI const char *elm_layout_part_cursor_style_get(const Evas_Object *obj, const char *part_name);
612 * Sets if the cursor set should be searched on the theme or should use
613 * the provided by the engine, only.
615 * @note before you set if should look on theme you should define a
616 * cursor with elm_layout_part_cursor_set(). By default it will only
617 * look for cursors provided by the engine.
619 * @param obj The layout object.
620 * @param part_name a part from loaded edje group.
621 * @param engine_only if cursors should be just provided by the engine (EINA_TRUE)
622 * or should also search on widget's theme as well (EINA_FALSE)
624 * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
625 * part not exists or it did not had a cursor set.
629 EAPI Eina_Bool elm_layout_part_cursor_engine_only_set(Evas_Object *obj, const char *part_name, Eina_Bool engine_only);
632 * Gets a specific cursor engine_only for an edje part.
634 * @param obj The layout object.
635 * @param part_name a part from loaded edje group.
637 * @return whenever the cursor is just provided by engine or also from theme.
641 EAPI Eina_Bool elm_layout_part_cursor_engine_only_get(const Evas_Object *obj, const char *part_name);
644 * @def elm_layout_icon_set
645 * Convenience macro to set the icon object in a layout that follows the
646 * Elementary naming convention for its parts.
650 #define elm_layout_icon_set(_ly, _obj) \
653 elm_object_part_content_set((_ly), "elm.swallow.icon", (_obj)); \
654 if ((_obj)) sig = "elm,state,icon,visible"; \
655 else sig = "elm,state,icon,hidden"; \
656 elm_object_signal_emit((_ly), sig, "elm"); \
660 * @def elm_layout_icon_get
662 * Convienience macro to get the icon object from a layout that follows the
664 * Convenience macro to get the icon object from a layout that follows the
665 >>>>>>> remotes/origin/upstream
666 * Elementary naming convention for its parts.
670 #define elm_layout_icon_get(_ly) \
671 elm_object_part_content_get((_ly), "elm.swallow.icon")
674 * @def elm_layout_end_set
676 * Convienience macro to set the end object in a layout that follows the
678 * Convenience macro to set the end object in a layout that follows the
679 >>>>>>> remotes/origin/upstream
680 * Elementary naming convention for its parts.
684 #define elm_layout_end_set(_ly, _obj) \
687 elm_object_part_content_set((_ly), "elm.swallow.end", (_obj)); \
688 if ((_obj)) sig = "elm,state,end,visible"; \
689 else sig = "elm,state,end,hidden"; \
690 elm_object_signal_emit((_ly), sig, "elm"); \
694 * @def elm_layout_end_get
696 * Convienience macro to get the end object in a layout that follows the
698 * Convenience macro to get the end object in a layout that follows the
699 >>>>>>> remotes/origin/upstream
700 * Elementary naming convention for its parts.
704 #define elm_layout_end_get(_ly) \
705 elm_object_part_content_get((_ly), "elm.swallow.end")
707 /* smart callbacks called:
708 * "theme,changed" - when elm theme is changed.