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:
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.
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.
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.
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:
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.
These are available predefined theme layouts. All of them have class = layout, group = application, and style = one of the following options:
Bases: efl.elementary.__init__.LayoutClass
This is the class that actually implements the widget.
Parameters: |
|
---|
Bases: efl.elementary.__init__.Object
This is the base class for the Layout widget and all the other widgets that inherit from it.
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: |
|
---|---|
Raises RuntimeError: | |
when adding the child fails |
Changed in version 1.8: Raises RuntimeError if adding the child fails
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: |
|
---|---|
Raises RuntimeError: | |
when inserting to box fails |
Changed in version 1.8: Raises RuntimeError if adding the child fails
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: | |
---|---|
Raises RuntimeError: | |
when inserting to box fails |
Changed in version 1.8: Raises RuntimeError if adding the child fails
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: |
|
---|---|
Raises RuntimeError: | |
when adding to box fails |
Changed in version 1.8: Raises RuntimeError if adding the child fails
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
Parameters: |
|
---|---|
Returns: | The object that was being used, or None if not found. |
Return type: |
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
Parameters: |
|
---|---|
Raises RuntimeError: | |
when removing all items fails |
Changed in version 1.8: Raises RuntimeError if removing the children fails
the program’s language changed
The theme was changed.
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 |
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: |
|
---|
Changed in version 1.8: Raises RuntimeError if setting the content fails.
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.
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 |
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 |
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.
See also
signal_callback_add() signal_emit() part_text_set() box_append() table_pack() data
Type: | Edje |
---|
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.
The end object in a layout that follows the Elementary naming convention for its parts.
Type: | Object |
---|
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
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.
The icon object in a layout that follows the Elementary naming convention for its parts.
Type: | Object |
---|
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 |
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: |
|
---|---|
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
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 |
Sets a specific cursor for an edje part.
Parameters: |
|
---|---|
Raises RuntimeError: | |
when setting the parts cursor fails |
Changed in version 1.8: Raises RuntimeError if setting the cursor fails
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 |
Sets a specific cursor style for an edje part.
Parameters: |
|
---|---|
Raises RuntimeError: | |
when setting the part cursor style fails |
Changed in version 1.8: Raises RuntimeError if setting the cursor style fails
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
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: |
|
---|
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: |
|
---|
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: |
|
---|
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.
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
Parameters: |
|
---|---|
Raises RuntimeError: | |
when clearing the table fails |
Changed in version 1.8: Raises RuntimeError if clearing the table fails
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
Parameters: |
|
---|---|
Raises RuntimeError: | |
when packing an item fails |
Changed in version 1.8: Raises RuntimeError if adding the child fails
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
Parameters: |
|
---|---|
Returns: | The object that was being used, or None if not found. |
Return type: |
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 |
Set the text of the given part
Parameters: |
|
---|
Changed in version 1.8: Raises RuntimeError if setting the text fails
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.
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