Layout¶

Widget description¶

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 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 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.

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 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 box_ set of functions.

Table (TABLE part)

Just like the Box, 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 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 table_ set of functions.

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 theme, 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.

Layout Class¶

Elementary, besides having the Layout widget, exposes its foundation – the Elementary Layout Class – in order to create other widgets which are, basically, a certain layout with some more logic on top.

The idea is to make the creation of that widgets as easy as possible, factorizing code on this common base. For example, a button is a layout (that looks like push button) that happens to react on clicks and keyboard events in a special manner, calling its user back on those events. That’s no surprise, then, that the Button implementation relies on LayoutClass, if you go to check it.

Container parts, here, map directly to Edje parts from the layout’s Edje group. Besides that, there’s a whole infrastructure around Edje files:

interfacing by signals,
setting/retrieving text part values,
dealing with table and box parts directly,
etc.

Finally, layout objects will do part aliasing for you, if you set it up properly. For that, take a look at Elm_Layout_Part_Alias_Description, where it’s explained in detail.

Available styles¶

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

Emitted signals¶

theme,changed - The theme was changed.

Inheritance diagram¶

class efl.elementary.Layout(Object parent, *args, **kwargs)¶

Bases: efl.elementary.__init__.LayoutClass

This is the class that actually implements the widget.

Layout(…)

Parameters

parent (efl.evas.Object) – The parent object
**kwargs – All the remaining keyword arguments are interpreted as properties of the instance

class efl.elementary.LayoutClass¶

Bases: efl.elementary.__init__.Object

This is the base class for the Layout widget and all the other widgets that inherit from it.

box_append(part, child)¶

Append child to layout box part.

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 box_remove() to make this layout forget about the object.

Parameters

part (string) – the box part to which the object will be appended.
child (Object) – the child object to append to box.

Raises

RuntimeError – when adding the child fails

Changed in version 1.8: Raises RuntimeError if adding the child fails

box_insert_at(part, child, pos)¶

Insert child to layout box part at a given position.

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 box_remove() to make this layout forget about the object.

Parameters

part (string) – the box part to insert.
child (Object) – the child object to insert into box.
pos (int) – the numeric position >=0 to insert the child.

Raises

RuntimeError – when inserting to box fails

Changed in version 1.8: Raises RuntimeError if adding the child fails

box_insert_before(part, child, reference)¶

Insert child to layout box part before a reference object.

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 box_remove() to make this layout forget about the object.

Parameters

part (string) – the box part to insert.
child (Object) – the child object to insert into box.
reference (Object) – another reference object to insert before in box.

Raises

RuntimeError – when inserting to box fails

Changed in version 1.8: Raises RuntimeError if adding the child fails

box_prepend(part, child)¶

Prepend child to layout box part.

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 box_remove() to make this layout forget about the object.

Parameters

part (string) – the box part to prepend.
child (Object) – the child object to prepend to box.

Raises

RuntimeError – when adding to box fails

Changed in version 1.8: Raises RuntimeError if adding the child fails

box_remove(part, child)¶

Remove a child of the given part box.

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

See also

box_append() box_remove_all()

Parameters

part (string) – The box part name to remove child.
child (Object) – The object to remove from box.

Returns

The object that was being used, or None if not found.

Return type

Object

box_remove_all(part, clear)¶

Remove all children of the given part box.

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

See also

box_append() box_remove()

Parameters

part (string) – The box part name to remove child.
clear (bool) – If True, then all objects will be deleted as well, otherwise they will just be removed and will be dangling on the canvas.

Raises

RuntimeError – when removing all items fails

Changed in version 1.8: Raises RuntimeError if removing the children fails

callback_theme_changed_add(func, *args, **kwargs)¶: The theme was changed.

callback_theme_changed_del(func)¶

content_get(swallow=None)¶

Get the child object in the given content part.

Parameters: swallow (string) – The SWALLOW part to get its content
Returns: The swallowed object or None if none or an error occurred

content_set(swallow=None, content=None)¶

Set the layout content.

Once the content object is set, a previously set one will be deleted. If you want to keep that old content object, use the 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 box_append().

Parameters

swallow (string) – The swallow part name in the edje file
content (Object) – The child that will be added in this layout object

Changed in version 1.8: Raises RuntimeError if setting the content fails.

content_swallow_list_get()¶

Get the list of objects swallowed into the layout.

Returns: a list of swallowed objects.
Return type: list of objects.

New in version 1.9.

content_unset(swallow=None)¶

Unset the layout content.

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

Parameters: swallow (string) – The swallow part name in the edje file
Returns: The content that was being used
Return type: Object

data_get(key)¶

Get the edje data from the given layout

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

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

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

Parameters: key (string) – The data key
Returns: The edje data string
Return type: string

edje¶

Get the edje layout

This returns the edje object. It is not expected to be used to then swallow objects via Edje.part_swallow for example. Use 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.

Type: Edje

edje_get()¶

edje_object_can_access¶

Set accessibility to all textblock(text) parts in the layout object

Makes it possible for all textblock(text) parts in the layout to have accessibility.

Raises: RuntimeError – if accessibility cannot be set.

New in version 1.8.

edje_object_can_access_get()¶

edje_object_can_access_set(can_access)¶

end¶

The end object in a layout that follows the Elementary naming convention for its parts.

Type: Object

end_get()¶

end_set(end)¶

file¶

Set the file path and group of the edje file that will be used as layout.

Type: tuple of string
Raises: RuntimeError – when setting the file fails

Changed in version 1.8: Raises RuntimeError if setting the file fails

Changed in version 1.14: Property is now also readable

file_get()¶

file_set(filename, group=None)¶

freeze()¶

Freezes the Elementary layout object.

This function puts all changes on hold. Successive freezes will nest, requiring an equal number of thaws.

Returns: The frozen state or 0 on Error
See: thaw()

New in version 1.8.

icon¶

The icon object in a layout that follows the Elementary naming convention for its parts.

Type: Object

icon_get()¶

icon_set(icon)¶

part_cursor_engine_only_get(part_name)¶

Gets a specific cursor engine_only for an edje part.

Parameters: part_name (string) – a part from loaded edje group.
Returns: whenever the cursor is just provided by engine or also from theme.
Return type: bool

part_cursor_engine_only_set(part_name, 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 part_cursor_set(). By default it will only look for cursors provided by the engine.

Parameters

part_name (string) – a part from loaded edje group.
engine_only (bool) – if cursors should be just provided by the engine (True) or should also search on widget’s theme as well (False)

Returns

True on success or False on failure, that may be part not exists or it did not had a cursor set.

Return type

bool

Raises

RuntimeError – when setting the engine_only setting fails, when part does not exist or has no cursor set.

Changed in version 1.8: Raises RuntimeError if setting the value fails

part_cursor_get(part_name)¶

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

Parameters: part_name (string) – a part from loaded edje group.
Returns: the cursor name.
Return type: string

part_cursor_set(part_name, cursor)¶

Sets a specific cursor for an edje part.

Parameters

part_name (string) – a part from loaded edje group.
cursor (string) – cursor name to use, see Elementary_Cursor.h

Raises

RuntimeError – when setting the parts cursor fails

Changed in version 1.8: Raises RuntimeError if setting the cursor fails

part_cursor_style_get(part_name)¶

Gets a specific cursor style for an edje part.

Parameters: part_name (string) – a part from loaded edje group.
Returns: the theme style in use, defaults to “default”. If the object does not have a cursor set, then None is returned.
Return type: string

part_cursor_style_set(part_name, style)¶

Sets a specific cursor style for an edje part.

Parameters

part_name (string) – a part from loaded edje group.
style (string) – the theme style to use (default, transparent, …)

Raises

RuntimeError – when setting the part cursor style fails

Changed in version 1.8: Raises RuntimeError if setting the cursor style fails

part_cursor_unset(part_name)¶

Unsets a cursor previously set with part_cursor_set().

Parameters: part_name (string) – a part from loaded edje group, that had a cursor set with part_cursor_set().
Raises: RuntimeError – when unsetting the part cursor fails

Changed in version 1.8: Raises RuntimeError if unsetting the cursor fails

signal_callback_add(emission, source, func, *args, **kwargs)¶

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

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

Parameters

emission (string) – The signal’s name string
source (string) – The signal’s source string
func (function) – The callback function to be executed when the signal is emitted.

signal_callback_del(emission, source, func)¶

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

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

Parameters

emission (string) – The signal’s name string
source (string) – The signal’s source string
func (function) – The callback function being executed when the signal was emitted.

signal_emit(emission, source)¶

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

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

Parameters

emission (string) – The signal’s name string
source (string) – The signal’s source string

sizing_eval()¶

Eval sizing

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.

table_clear(part, clear)¶

Remove all the child objects of the given part table.

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

See also

table_pack() table_unpack()

Parameters

part (string) – The table part name to remove child.
clear (bool) – If True, then all objects will be deleted as well, otherwise they will just be removed and will be dangling on the canvas.

Raises

RuntimeError – when clearing the table fails

Changed in version 1.8: Raises RuntimeError if clearing the table fails

table_pack(part, child_obj, col, row, colspan, rowspan)¶

Insert child to layout table part.

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 table_unpack() 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.

See also

table_unpack() table_clear()

Parameters

part (string) – the box part to pack child.
child_obj (Object) – the child object to pack into table.
col (int) – the column to which the child should be added. (>= 0)
row (int) – the row to which the child should be added. (>= 0)
colspan (int) – how many columns should be used to store this object. (>= 1)
rowspan (int) – how many rows should be used to store this object. (>= 1)

Raises

RuntimeError – when packing an item fails

Changed in version 1.8: Raises RuntimeError if adding the child fails

table_unpack(part, child_obj)¶

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

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

See also

table_pack() table_clear()

Parameters

part (string) – The table part name to remove child.
child_obj (Object) – The object to remove from table.

Returns

The object that was being used, or None if not found.

Return type

Object

text_get(part=None)¶

Get the text set in the given part

Parameters: part (string) – The TEXT part to retrieve the text off
Returns: The text set in part
Return type: string

text_set(part=None, text=None)¶

Set the text of the given part

Parameters

part (string) – The TEXT part where to set the text
text (string) – The text to set

Changed in version 1.8: Raises RuntimeError if setting the text fails

thaw()¶

Thaws the Elementary object.

This function thaws the given Edje object and the Elementary sizing calc.

Returns: The frozen state or 0 if the object is not frozen or on error.

Note

If successive freezes were done, an equal number of thaws will be required.

See: freeze()

New in version 1.8.

theme¶

Set the edje group class, group name and style from the elementary theme that will be used as layout.

Note that style will be the new style too, as in setting style.

Type: tuple of strings
Raises: RuntimeError – when setting the theme fails

Changed in version 1.8: Raises RuntimeError if setting the theme fails

theme_set(clas, group, style)¶

Layout¶

Widget description¶

Layout Class¶

Available styles¶

Emitted signals¶

Inheritance diagram¶

Table of Contents

Previous topic

Next topic