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:
toolbar-content
- application with toolbar and main content areatoolbar-content-back
- application with toolbar and main content
area with a back button and title areatoolbar-content-back-next
- application with toolbar and main
content area with a back and next buttons and title areacontent-back
- application with a main content area with a back
button and title areacontent-back-next
- application with a main content area with a
back and next buttons and title areatoolbar-vbox
- application with toolbar and main content area as a
vertical boxtoolbar-table
- application with toolbar and main content area as a
tabletheme,changed
- The theme was changed.language,changed
- the program’s language changed
efl.elementary.
Layout
(Object parent, *args, **kwargs)¶Bases: efl.elementary.__init__.LayoutClass
Parameters: |
|
---|
efl.elementary.
LayoutClass
(...)¶Bases: efl.elementary.__init__.Object
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: |
|
---|---|
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: |
|
---|---|
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: | |
---|---|
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: |
|
---|---|
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
Parameters: |
|
---|---|
Returns: | The object that was being used, or None if not found. |
Return type: |
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
Parameters: |
|
---|---|
Raises RuntimeError: | |
when removing all items fails |
Changed in version 1.8: Raises RuntimeError if removing the children fails
callback_language_changed_add
(func, *args, **kwargs)¶the program’s language changed
callback_language_changed_del
(func)¶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: |
|
---|
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.
See also
signal_callback_add()
signal_emit()
part_text_set()
box_append()
table_pack()
data
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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
Parameters: |
|
---|---|
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
Parameters: |
|
---|---|
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
Parameters: |
|
---|---|
Returns: | The object that was being used, or None if not found. |
Return type: |
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: |
|
---|
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)¶