Layout

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

Macros | Typedefs | Functions
Layout

## Macros
#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_layout_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_layout_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.

## Typedefs
typedef struct _Elm_Layout_Part_Alias_Description | Elm_Layout_Part_Alias_Description
| A layout part aliasing (proxying) description, used to get part names aliasing independently of a widgets theme.

## Functions
Evas_Object * | elm_layout_add (Evas_Object *parent)
| Add a new layout to the parent. More...
Eina_List * | elm_layout_content_swallow_list_get (const Evas_Object *obj)
| Get the list of swallow parts of a given container widget. More...
Eina_Bool | elm_layout_content_set (Evas_Object *obj, const char *swallow, Evas_Object *content)
| Set the layout content. More...
Evas_Object * | elm_layout_content_get (const Evas_Object *obj, const char *swallow)
| Get the child object in the given content part. More...
Evas_Object * | elm_layout_content_unset (Evas_Object *obj, const char *swallow)
| Unset the layout content. More...
Eina_Bool | elm_layout_file_set (Eo *obj, const char *file, const char *group)
| Set the file that will be used as layout. More...
void | elm_layout_file_get (Eo *obj, const char **file, const char **group)
| Get the loaded file. More...

## Detailed Description

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 forming a 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, moved if the Layout is moved, and so on.

The layout widget may contain as many parts/children as described in its theme file. Some of these children can have special types, such as content holder ones (swallow spots), boxes or tables. These are parts meant to contain others. For instance, objects can be added to different table parts by specifying the respective table part names. The same is valid for swallows and boxes.

The objects added as children of a 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 (@c SWALLOW part)

Only one object can be added to the `SWALLOW` part at a time (but you still can have many `SWALLOW` parts and one object on each of them). Use the `elm_layout_content_set()/get/unset` functions to set, retrieve and unset objects as content of the `SWALLOW`. After being set to this part, the object's 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's 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's size will be changed if the part size is changed, it will animate moving accordingly if the part is moving, and so on.

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

# Box (@c 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 content in a `SWALLOW` part.

The main difference to that, by using the layout box instead, is that its behavior, like layouting format, padding, align, etc., will all be controlled by the theme. This means, for example, that a signal could be sent to the layout's theme (with elm_layout_signal_emit()) and the signal be handled by changing the box's padding, or alignment, 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:

# Table (@c 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 by 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 a `SWALLOW` part, using elm_layout_content_set(). The same difference happens here when choosing to use the layout table (a `TABLE` part) instead of the table in a `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:

# 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 the available predefined theme layouts. All of them have class = `layout`, group = `application`, and style = one of the following options:

- `toolbar-content` - for applications with a toolbar and main content area
- `toolbar-content-back` - for applications with a toolbar and main content (with a back button) and title areas
- `toolbar-content-back-next` - for applications with a toolbar and main content (with back and next buttons) and title areas
- `content-back` - for application with main content (with a back button) and title areas
- `content-back-next` - for applications with main content (with back and next buttons) and title areas
- `toolbar-vbox` - for applications with a toolbar and main content area as a vertical box
- `toolbar-table` - for applications with a toolbar and main content area as a table

# Emitted signals

This widget emits the following signals:

- "theme,changed" - The theme was changed.
- "language,changed" - the program's language changed

# Examples

Some examples of the Layout widget can be found here:

- Layout - Content, Table and Box
- Layout - Predefined Layout
- Layout - Signals and Size Changed
- An example of layout theme file

## Function Documentation

Evas_Object* elm_layout_add | ( | Evas_Object * | parent | ) |

Add a new layout to the parent.

Parameters

  parent | The parent object

Returns
  The new object or NULL if it cannot be created

See also
  elm_layout_file_set()
  elm_layout_theme_set()

References _Elm_Layout_Smart_Data::obj.

Referenced by elm_color_class_editor_add(), elm_notify_parent_get(), and elm_panel_add().

Evas_Object* elm_layout_content_get | ( | const Evas_Object * | obj,
|  | const char * | swallow
| ) |  |

Get the child object in the given content part.

Parameters

  obj | The layout object
  swallow | The SWALLOW part to get its content

Returns
  The swallowed object or NULL if none or an error occurred

References _Elm_Layout_Smart_Data::subs.

Referenced by elm_entry_file_get(), and elm_panes_add().

Eina_Bool elm_layout_content_set | ( | Evas_Object * | obj,
|  | const char * | swallow,
|  | Evas_Object * | content
| ) |  |

Set the layout content.

Parameters

  obj | The layout object
  swallow | The swallow part name in the edje file
  content | The child that will be added in this layout object

Returns
  `EINA_TRUE` on success, `EINA_FALSE` otherwise

Once the content object is set, a previously set one will be deleted. If you want to keep that old content object, use the elm_layout_content_unset() function.

Note
  In an Edje theme, the part used as a content container is called `SWALLOW`. This is why the parameter name is called `swallow`, but it is expected to be a part name just like the second parameter of elm_layout_box_append().

See also
  elm_layout_box_append()
  elm_layout_content_get()
  elm_layout_content_unset()
  Box (`BOX` part)

References _Elm_Widget_Smart_Data::resize_obj, and _Elm_Layout_Smart_Data::subs.

Referenced by elm_bg_add(), elm_bg_color_set(), elm_colorselector_add(), elm_ctxpopup_add(), elm_datetime_add(), elm_fileselector_mode_set(), elm_menu_add(), elm_menu_parent_get(), elm_panel_add(), elm_panes_add(), and elm_slideshow_add().

Eina_List* elm_layout_content_swallow_list_get | ( | const Evas_Object * | obj | ) |

Get the list of swallow parts of a given container widget.

Parameters

  obj | The layout object

Returns
  list of swallow parts which should be freed by the user program with elm_list_free()

Since
  1.9

References _Elm_Layout_Smart_Data::can_access, elm_object_cursor_get(), elm_object_cursor_style_get(), elm_object_cursor_style_set(), elm_object_cursor_theme_search_enabled_get(), elm_object_cursor_theme_search_enabled_set(), elm_object_cursor_unset(), _Elm_Layout_Smart_Data::frozen, _Elm_Layout_Smart_Data::needs_size_calc, _Elm_Layout_Smart_Data::parts_cursors, _Elm_Widget_Smart_Data::resize_obj, _Elm_Layout_Smart_Data::restricted_calc_h, _Elm_Layout_Smart_Data::restricted_calc_w, and _Elm_Layout_Smart_Data::subs.

Evas_Object* elm_layout_content_unset | ( | Evas_Object * | obj,
|  | const char * | swallow
| ) |  |

Unset the layout content.

Parameters

  obj | The layout object
  swallow | The swallow part name in the edje file

Returns
  The content that was being used

Unparent and return the content object which was set for this part.

References _Elm_Widget_Smart_Data::resize_obj, and _Elm_Layout_Smart_Data::subs.

Referenced by elm_colorselector_add(), elm_datetime_add(), elm_fileselector_mode_set(), elm_panel_add(), elm_panes_add(), and elm_popup_add().

void elm_layout_file_get | ( | Eo * | obj,
|  | const char ** | file,
|  | const char ** | group
| ) |  |

Get the loaded file.

Parameters

  file | The path to file (edj) used as layout
  group | The group that the layout belongs in edje file

Since
  1.14

Eina_Bool elm_layout_file_set | ( | Eo * | obj,
|  | const char * | file,
|  | const char * | group
| ) |  |

Set the file that will be used as layout.

Returns
  (1 = success, 0 = error)

Parameters

  [in] | file | The path to file (edj) that will be used as layout
  [in] | group | The group that the layout belongs in edje file