Layout

Defines

#define elm_layout_icon_set(_ly, _obj)
 Convenience macro to set the icon object in a layout that follows the Elementary naming convention for its parts.
#define elm_layout_icon_get(_ly)   elm_object_part_content_get((_ly), "elm.swallow.icon")
 Convenience macro to get the icon object from a layout that follows the Elementary naming convention for its parts.
#define elm_layout_end_set(_ly, _obj)
 Convenience macro to set the end object in a layout that follows the Elementary naming convention for its parts.
#define elm_layout_end_get(_ly)   elm_object_part_content_get((_ly), "elm.swallow.end")
 Convenience macro to get the end object in a layout that follows the Elementary naming convention for its parts.

Functions

Evas_Object * elm_layout_add (Evas_Object *parent)
 Add a new layout to the parent.
Eina_Bool elm_layout_file_set (Evas_Object *obj, const char *file, const char *group)
 Set the file that will be used as layout.
Eina_Bool elm_layout_theme_set (Evas_Object *obj, const char *clas, const char *group, const char *style)
 Set the edje group from the elementary theme that will be used as layout.
void elm_layout_signal_emit (Evas_Object *obj, const char *emission, const char *source)
 Send a (Edje) signal to a given layout widget's underlying Edje object.
void elm_layout_signal_callback_add (Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data)
 Add a callback for a (Edje) signal emitted by a layout widget's underlying Edje object.
void * elm_layout_signal_callback_del (Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func)
 Remove a signal-triggered callback from a given layout widget.
Eina_Bool elm_layout_box_append (Evas_Object *obj, const char *part, Evas_Object *child)
 Append child to layout box part.
Eina_Bool elm_layout_box_prepend (Evas_Object *obj, const char *part, Evas_Object *child)
 Prepend child to layout box part.
Eina_Bool elm_layout_box_insert_before (Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference)
 Insert child to layout box part before a reference object.
Eina_Bool elm_layout_box_insert_at (Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos)
 Insert child to layout box part at a given position.
Evas_Object * elm_layout_box_remove (Evas_Object *obj, const char *part, Evas_Object *child)
 Remove a child of the given part box.
Eina_Bool elm_layout_box_remove_all (Evas_Object *obj, const char *part, Eina_Bool clear)
 Remove all children of the given part box.
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)
 Insert child to layout table part.
Evas_Object * elm_layout_table_unpack (Evas_Object *obj, const char *part, Evas_Object *child_obj)
 Unpack (remove) a child of the given part table.
Eina_Bool elm_layout_table_clear (Evas_Object *obj, const char *part, Eina_Bool clear)
 Remove all the child objects of the given part table.
Evas_Object * elm_layout_edje_get (const Evas_Object *obj)
 Get the edje layout.
const char * elm_layout_data_get (const Evas_Object *obj, const char *key)
 Get the edje data from the given layout.
void elm_layout_sizing_eval (Evas_Object *obj)
 Eval sizing.
Eina_Bool elm_layout_part_cursor_set (Evas_Object *obj, const char *part_name, const char *cursor)
 Sets a specific cursor for an edje part.
const char * elm_layout_part_cursor_get (const Evas_Object *obj, const char *part_name)
 Get the cursor to be shown when mouse is over an edje part.
Eina_Bool elm_layout_part_cursor_unset (Evas_Object *obj, const char *part_name)
 Unsets a cursor previously set with elm_layout_part_cursor_set().
Eina_Bool elm_layout_part_cursor_style_set (Evas_Object *obj, const char *part_name, const char *style)
 Sets a specific cursor style for an edje part.
const char * elm_layout_part_cursor_style_get (const Evas_Object *obj, const char *part_name)
 Gets a specific cursor style for an edje part.
Eina_Bool elm_layout_part_cursor_engine_only_set (Evas_Object *obj, const char *part_name, Eina_Bool engine_only)
 Sets if the cursor set should be searched on the theme or should use the provided by the engine, only.
Eina_Bool elm_layout_part_cursor_engine_only_get (const Evas_Object *obj, const char *part_name)
 Gets a specific cursor engine_only for an edje part.

Detailed Description

layout_inheritance_tree.png
preview-00.png
layout-predefined.png

A Layout is a direct realization of The Elementary Layout Class.

This is a container widget that takes a standard Edje design file and wraps it very thinly in a widget.

An Edje design (theme) file has a very wide range of possibilities to describe the behavior of elements added to the Layout. Check out the Edje documentation and the EDC reference to get more information about what can be done with Edje.

Just like List, Box, and other container widgets, any object added to the Layout will become its child, meaning that it will be deleted if the Layout is deleted, move if the Layout is moved, and so on.

The Layout widget can contain as many Contents, Boxes or Tables as described in its theme file. For instance, objects can be added to different Tables by specifying the respective Table part names. The same is valid for Content and Box.

The objects added as child of the Layout will behave as described in the part description where they were added. There are 3 possible types of parts where a child can be added:

Content (SWALLOW part)

Only one object can be added to the SWALLOW part (but you still can have many SWALLOW parts and one object on each of them). Use the elm_object_content_set/get/unset functions to set, retrieve and unset objects as content of the SWALLOW. After being set to this part, the object size, position, visibility, clipping and other description properties will be totally controlled by the description of the given part (inside the Edje theme file).

One can use evas_object_size_hint_* functions on the child to have some kind of control over its behavior, but the resulting behavior will still depend heavily on the SWALLOW part description.

The Edje theme also can change the part description, based on signals or scripts running inside the theme. This change can also be animated. All of this will affect the child object set as content accordingly. The object size will be changed if the part size is changed, it will animate move if the part is moving, and so on.

The following picture demonstrates a Layout widget with a child object added to its SWALLOW:

layout_swallow.png

Box (BOX part)

An Edje BOX part is very similar to the Elementary Box widget. It allows one to add objects to the box and have them distributed along its area, accordingly to the specified layout property (now by layout we mean the chosen layouting design of the Box, not the Layout widget itself).

A similar effect for having a box with its position, size and other things controlled by the Layout theme would be to create an Elementary Box widget and add it as a Content in the SWALLOW part.

The main difference of using the Layout Box is that its behavior, the box properties like layouting format, padding, align, etc. will be all controlled by the theme. This means, for example, that a signal could be sent to the Layout theme (with elm_object_signal_emit()) and the theme handled the signal by changing the box padding, or align, or both. Using the Elementary Box widget is not necessarily harder or easier, it just depends on the circumstances and requirements.

The Layout Box can be used through the elm_layout_box_* set of functions.

The following picture demonstrates a Layout widget with many child objects added to its BOX part:

layout_box.png

Table (TABLE part)

Just like the Box (BOX part), the Layout Table is very similar to the Elementary Table widget. It allows one to add objects to the Table specifying the row and column where the object should be added, and any column or row span if necessary.

Again, we could have this design by adding a Table widget to the SWALLOW part using elm_object_part_content_set(). The same difference happens here when choosing to use the Layout Table (a TABLE part) instead of the Table plus SWALLOW part. It's just a matter of convenience.

The Layout Table can be used through the elm_layout_table_* set of functions.

The following picture demonstrates a Layout widget with many child objects added to its TABLE part:

layout_table.png

Predefined Layouts

Another interesting thing about the Layout widget is that it offers some predefined themes that come with the default Elementary theme. These themes can be set by the call elm_layout_theme_set(), and provide some basic functionality depending on the theme used.

Most of them already send some signals, some already provide a toolbar or back and next buttons.

These are available predefined theme layouts. All of them have class = layout, group = application, and style = one of the following options:

  • toolbar-content - application with toolbar and main content area
  • toolbar-content-back - application with toolbar and main content area with a back button and title area
  • toolbar-content-back-next - application with toolbar and main content area with a back and next buttons and title area
  • content-back - application with a main content area with a back button and title area
  • content-back-next - application with a main content area with a back and next buttons and title area
  • toolbar-vbox - application with toolbar and main content area as a vertical box
  • toolbar-table - application with toolbar and main content area as a table

Supported elm_object common APIs.

Emitted signals

This widget emits the following signals:

  • "theme,changed": The theme was changed.

Examples

Some examples of the Layout widget can be found here:


Function Documentation

Evas_Object* elm_layout_add ( Evas_Object *  parent)

Add a new layout to the parent.

Parameters:
parentThe parent object
Returns:
The new object or NULL if it cannot be created
See also:
elm_layout_file_set()
elm_layout_theme_set()

Referenced by elm_notify_allow_events_set(), elm_popup_add(), and elm_toolbar_add().

Eina_Bool elm_layout_box_append ( Evas_Object *  obj,
const char *  part,
Evas_Object *  child 
)

Append child to layout box part.

Parameters:
objthe layout object
partthe box part to which the object will be appended.
childthe child object to append to box.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

Once the object is appended, it will become child of the layout. Its lifetime will be bound to the layout, whenever the layout dies the child will be deleted automatically. One should use elm_layout_box_remove() to make this layout forget about the object.

See also:
elm_layout_box_prepend()
elm_layout_box_insert_before()
elm_layout_box_insert_at()
elm_layout_box_remove()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Eina_Bool elm_layout_box_insert_at ( Evas_Object *  obj,
const char *  part,
Evas_Object *  child,
unsigned int  pos 
)

Insert child to layout box part at a given position.

Parameters:
objthe layout object
partthe box part to insert.
childthe child object to insert into box.
posthe numeric position >=0 to insert the child.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

Once the object is inserted, it will become child of the layout. Its lifetime will be bound to the layout, whenever the layout dies the child will be deleted automatically. One should use elm_layout_box_remove() to make this layout forget about the object.

See also:
elm_layout_box_append()
elm_layout_box_prepend()
elm_layout_box_insert_before()
elm_layout_box_remove()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Eina_Bool elm_layout_box_insert_before ( Evas_Object *  obj,
const char *  part,
Evas_Object *  child,
const Evas_Object *  reference 
)

Insert child to layout box part before a reference object.

Parameters:
objthe layout object
partthe box part to insert.
childthe child object to insert into box.
referenceanother reference object to insert before in box.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

Once the object is inserted, it will become child of the layout. Its lifetime will be bound to the layout, whenever the layout dies the child will be deleted automatically. One should use elm_layout_box_remove() to make this layout forget about the object.

See also:
elm_layout_box_append()
elm_layout_box_prepend()
elm_layout_box_insert_before()
elm_layout_box_remove()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Eina_Bool elm_layout_box_prepend ( Evas_Object *  obj,
const char *  part,
Evas_Object *  child 
)

Prepend child to layout box part.

Parameters:
objthe layout object
partthe box part to prepend.
childthe child object to prepend to box.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

Once the object is prepended, it will become child of the layout. Its lifetime will be bound to the layout, whenever the layout dies the child will be deleted automatically. One should use elm_layout_box_remove() to make this layout forget about the object.

See also:
elm_layout_box_append()
elm_layout_box_insert_before()
elm_layout_box_insert_at()
elm_layout_box_remove()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Evas_Object* elm_layout_box_remove ( Evas_Object *  obj,
const char *  part,
Evas_Object *  child 
)

Remove a child of the given part box.

Parameters:
objThe layout object
partThe box part name to remove child.
childThe object to remove from box.
Returns:
The object that was being used, or NULL if not found.

The object will be removed from the box part and its lifetime will not be handled by the layout anymore. This is equivalent to elm_object_part_content_unset() for box.

See also:
elm_layout_box_append()
elm_layout_box_remove_all()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Eina_Bool elm_layout_box_remove_all ( Evas_Object *  obj,
const char *  part,
Eina_Bool  clear 
)

Remove all children of the given part box.

Parameters:
objThe layout object
partThe box part name to remove child.
clearIf EINA_TRUE, then all objects will be deleted as well, otherwise they will just be removed and will be dangling on the canvas.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

The objects will be removed from the box part and their lifetime will not be handled by the layout anymore. This is equivalent to elm_layout_box_remove() for all box children.

See also:
elm_layout_box_append()
elm_layout_box_remove()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

const char* elm_layout_data_get ( const Evas_Object *  obj,
const char *  key 
)

Get the edje data from the given layout.

Parameters:
objThe layout object
keyThe data key
Returns:
The edje data string

This function fetches data specified inside the edje theme of this layout. This function return NULL if data is not found.

In EDC this comes from a data block within the group block that obj was loaded from. E.g.

 collections {
   group {
     name: "a_group";
     data {
       item: "key1" "value1";
       item: "key2" "value2";
     }
   }
 }

References ELM_WIDGET_DATA.

Evas_Object* elm_layout_edje_get ( const Evas_Object *  obj)

Get the edje layout.

Parameters:
objThe layout object
Returns:
A Evas_Object with the edje layout settings loaded with function elm_layout_file_set

This returns the edje object. It is not expected to be used to then swallow objects via edje_object_part_swallow() for example. Use elm_object_part_content_set() instead so child object handling and sizing is done properly.

Note:
This function should only be used if you really need to call some low level Edje function on this edje object. All the common stuff (setting text, emitting signals, hooking callbacks to signals, etc.) can be done with proper elementary functions.
See also:
elm_object_signal_callback_add()
elm_object_signal_emit()
elm_object_part_text_set()
elm_object_part_content_set()
elm_layout_box_append()
elm_layout_table_pack()
elm_layout_data_get()

References ELM_WIDGET_DATA.

Eina_Bool elm_layout_file_set ( Evas_Object *  obj,
const char *  file,
const char *  group 
)

Set the file that will be used as layout.

Parameters:
objThe layout object
fileThe path to file (edj) that will be used as layout
groupThe group that the layout belongs in edje file
Returns:
(1 = success, 0 = error)

References ELM_WIDGET_DATA.

Eina_Bool elm_layout_part_cursor_engine_only_get ( const Evas_Object *  obj,
const char *  part_name 
)

Gets a specific cursor engine_only for an edje part.

Parameters:
objThe layout object.
part_namea part from loaded edje group.
Returns:
whenever the cursor is just provided by engine or also from theme.

References elm_object_cursor_theme_search_enabled_get().

Eina_Bool elm_layout_part_cursor_engine_only_set ( Evas_Object *  obj,
const char *  part_name,
Eina_Bool  engine_only 
)

Sets if the cursor set should be searched on the theme or should use the provided by the engine, only.

Note:
before you set if should look on theme you should define a cursor with elm_layout_part_cursor_set(). By default it will only look for cursors provided by the engine.
Parameters:
objThe layout object.
part_namea part from loaded edje group.
engine_onlyif cursors should be just provided by the engine (EINA_TRUE) or should also search on widget's theme as well (EINA_FALSE)
Returns:
EINA_TRUE on success or EINA_FALSE on failure, that may be part not exists or it did not had a cursor set.

References elm_object_cursor_theme_search_enabled_set().

const char* elm_layout_part_cursor_get ( const Evas_Object *  obj,
const char *  part_name 
)

Get the cursor to be shown when mouse is over an edje part.

Parameters:
objThe layout object.
part_namea part from loaded edje group.
Returns:
the cursor name.

References elm_object_cursor_get().

Eina_Bool elm_layout_part_cursor_set ( Evas_Object *  obj,
const char *  part_name,
const char *  cursor 
)

Sets a specific cursor for an edje part.

Parameters:
objThe layout object.
part_namea part from loaded edje group.
cursorcursor name to use, see Elementary_Cursor.h
Returns:
EINA_TRUE on success or EINA_FALSE on failure, that may be part not exists or it has "mouse_events: 0".

References ELM_WIDGET_DATA.

const char* elm_layout_part_cursor_style_get ( const Evas_Object *  obj,
const char *  part_name 
)

Gets a specific cursor style for an edje part.

Parameters:
objThe layout object.
part_namea part from loaded edje group.
Returns:
the theme style in use, defaults to "default". If the object does not have a cursor set, then NULL is returned.

References elm_object_cursor_style_get().

Eina_Bool elm_layout_part_cursor_style_set ( Evas_Object *  obj,
const char *  part_name,
const char *  style 
)

Sets a specific cursor style for an edje part.

Parameters:
objThe layout object.
part_namea part from loaded edje group.
stylethe theme style to use (default, transparent, ...)
Returns:
EINA_TRUE on success or EINA_FALSE on failure, that may be part not exists or it did not had a cursor set.

References elm_object_cursor_style_set().

Eina_Bool elm_layout_part_cursor_unset ( Evas_Object *  obj,
const char *  part_name 
)

Unsets a cursor previously set with elm_layout_part_cursor_set().

Parameters:
objThe layout object.
part_namea part from loaded edje group, that had a cursor set with elm_layout_part_cursor_set().
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

References elm_object_cursor_unset().

void elm_layout_signal_callback_add ( Evas_Object *  obj,
const char *  emission,
const char *  source,
Edje_Signal_Cb  func,
void *  data 
)

Add a callback for a (Edje) signal emitted by a layout widget's underlying Edje object.

Parameters:
objThe layout object handle
emissionThe signal's name string
sourceThe signal's source string
funcThe callback function to be executed when the signal is emitted.
dataA pointer to data to pass in to the callback function.

This function connects a callback function to a signal emitted by the underlying Edje object of obj. Globs are accepted in either the emission or source strings (see edje_object_signal_callback_add()).

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_notify_allow_events_set().

void* elm_layout_signal_callback_del ( Evas_Object *  obj,
const char *  emission,
const char *  source,
Edje_Signal_Cb  func 
)

Remove a signal-triggered callback from a given layout widget.

Parameters:
objThe layout object handle
emissionThe signal's name string
sourceThe signal's source string
funcThe callback function being executed when the signal was emitted.
Returns:
The data pointer of the signal callback (passed on elm_layout_signal_callback_add()) or NULL, on errors.

This function removes the last callback attached to a signal emitted by the undelying Edje object of obj, with parameters emission, source and func matching exactly those passed to a previous call to elm_object_signal_callback_add(). The data pointer that was passed to this call will be returned.

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

void elm_layout_signal_emit ( Evas_Object *  obj,
const char *  emission,
const char *  source 
)

Send a (Edje) signal to a given layout widget's underlying Edje object.

Parameters:
objThe layout object handle
emissionThe signal's name string
sourceThe signal's source string

This function sends a signal to the underlying Edje object of obj. An Edje program on that Edje object's definition can respond to a signal by specifying matching 'signal' and 'source' fields.

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_check_state_pointer_set(), elm_check_state_set(), elm_colorselector_mode_set(), elm_fileselector_is_save_set(), elm_frame_collapse_go(), elm_frame_collapse_set(), elm_hover_dismiss(), elm_index_autohide_disabled_set(), elm_index_indicator_disabled_set(), elm_panes_fixed_set(), elm_progressbar_inverted_set(), elm_progressbar_pulse(), elm_progressbar_unit_format_set(), elm_slider_indicator_show_set(), elm_slider_inverted_set(), elm_slider_span_size_set(), elm_slider_unit_format_set(), elm_slideshow_item_show(), elm_slideshow_layout_set(), elm_slideshow_next(), elm_slideshow_previous(), elm_video_file_set(), elm_video_pause(), and elm_video_stop().

void elm_layout_sizing_eval ( Evas_Object *  obj)

Eval sizing.

Parameters:
objThe layout object

Manually forces a sizing re-evaluation. This is useful when the minimum size required by the edje theme of this layout has changed. The change on the minimum size required by the edje theme is not immediately reported to the elementary layout, so one needs to call this function in order to tell the widget (layout) that it needs to reevaluate its own size.

The minimum size of the theme is calculated based on minimum size of parts, the size of elements inside containers like box and table, etc. All of this can change due to state changes, and that's when this function should be called.

Also note that a standard signal of "size,eval" "elm" emitted from the edje object will cause this to happen too.

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_bg_color_set(), elm_bg_file_set(), elm_bg_option_set(), elm_colorselector_mode_set(), elm_colorselector_palette_color_add(), elm_genlist_mode_set(), elm_hover_parent_set(), elm_hover_target_set(), elm_label_ellipsis_set(), elm_label_line_wrap_set(), elm_label_slide_set(), elm_label_wrap_width_set(), elm_list_clear(), elm_naviframe_item_insert_after(), elm_naviframe_item_insert_before(), elm_naviframe_item_push(), elm_progressbar_span_size_set(), elm_progressbar_unit_format_function_set(), elm_progressbar_unit_format_set(), and elm_spinner_label_format_set().

Eina_Bool elm_layout_table_clear ( Evas_Object *  obj,
const char *  part,
Eina_Bool  clear 
)

Remove all the child objects of the given part table.

Parameters:
objThe layout object
partThe table part name to remove child.
clearIf EINA_TRUE, then all objects will be deleted as well, otherwise they will just be removed and will be dangling on the canvas.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

The objects will be removed from the table part and their lifetime will not be handled by the layout anymore. This is equivalent to elm_layout_table_unpack() for all table children.

See also:
elm_layout_table_pack()
elm_layout_table_unpack()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

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 
)

Insert child to layout table part.

Parameters:
objthe layout object
partthe box part to pack child.
child_objthe child object to pack into table.
colthe column to which the child should be added. (>= 0)
rowthe row to which the child should be added. (>= 0)
colspanhow many columns should be used to store this object. (>= 1)
rowspanhow many rows should be used to store this object. (>= 1)
Returns:
EINA_TRUE on success, EINA_FALSE otherwise

Once the object is inserted, it will become child of the table. Its lifetime will be bound to the layout, and whenever the layout dies the child will be deleted automatically. One should use elm_layout_table_remove() to make this layout forget about the object.

If colspan or rowspan are bigger than 1, that object will occupy more space than a single cell. For instance, the following code:

 elm_layout_table_pack(layout, "table_part", child, 0, 1, 3, 1);

Would result in an object being added like the following picture:

layout_colspan.png
See also:
elm_layout_table_unpack()
elm_layout_table_clear()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Evas_Object* elm_layout_table_unpack ( Evas_Object *  obj,
const char *  part,
Evas_Object *  child_obj 
)

Unpack (remove) a child of the given part table.

Parameters:
objThe layout object
partThe table part name to remove child.
child_objThe object to remove from table.
Returns:
The object that was being used, or NULL if not found.

The object will be unpacked from the table part and its lifetime will not be handled by the layout anymore. This is equivalent to elm_object_part_content_unset() for table.

See also:
elm_layout_table_pack()
elm_layout_table_clear()

References ELM_LAYOUT_CLASS, and ELM_WIDGET_DATA.

Eina_Bool elm_layout_theme_set ( Evas_Object *  obj,
const char *  clas,
const char *  group,
const char *  style 
)

Set the edje group from the elementary theme that will be used as layout.

Parameters:
objThe layout object
clasthe class of the group
groupthe group
stylethe style to used
Returns:
(1 = success, 0 = error)

Note that style will be the new style of obj too, as in an elm_object_style_set() call.

References ELM_WIDGET_DATA.

Referenced by elm_popup_add(), and elm_toolbar_add().