Box¶
Widget description¶
A box arranges objects in a linear fashion, governed by a layout function that defines the details of this arrangement.
By default, the box will use an internal function to set the layout to
a single row, either vertical or horizontal. This layout is affected
by a number of parameters, such as the homogeneous flag set by
homogeneous
, the values given by padding
and
align
and the hints set to each object in the box.
For this default layout, it’s possible to change the orientation with
horizontal
. The box will start in the vertical orientation,
placing its elements ordered from top to bottom. When horizontal is set,
the order will go from left to right. If the box is set to be
homogeneous, every object in it will be assigned the same space, that
of the largest object. Padding can be used to set some spacing between
the cell given to each object. The alignment of the box, set with
align
, determines how the bounding box of all the elements
will be placed within the space given to the box widget itself.
The size hints of each object also affect how they are placed and sized
within the box. size_hint_min
will give the minimum
size the object can have, and the box will use it as the basis for all
latter calculations. Elementary widgets set their own minimum size as
needed, so there’s rarely any need to use it manually.
size_hint_weight
, when not in homogeneous mode, is
used to tell whether the object will be allocated the minimum size it
needs or if the space given to it should be expanded. It’s important
to realize that expanding the size given to the object is not the same
thing as resizing the object. It could very well end being a small
widget floating in a much larger empty space. If not set, the weight
for objects will normally be 0.0 for both axis, meaning the widget will
not be expanded. To take as much space possible, set the weight to
EVAS_HINT_EXPAND
(defined to 1.0) for the desired axis to expand.
Besides how much space each object is allocated, it’s possible to control
how the widget will be placed within that space using
size_hint_align
. By default, this value will be 0.5
for both axis, meaning the object will be centered, but any value from
0.0 (left or top, for the x
and y
axis, respectively) to 1.0
(right or bottom) can be used. The special value EVAS_HINT_FILL, which
is -1.0, means the object will be resized to fill the entire space it
was allocated.
In addition, customized functions to define the layout can be set, which allow the application developer to organize the objects within the box in any number of ways.
The special Box.layout_transition()
function can be used
to switch from one layout to another, animating the motion of the
children of the box.
Note
Objects should not be added to box objects using _add() calls.
Enumerations¶
Box layout modes¶
- efl.elementary.ELM_BOX_LAYOUT_HORIZONTAL¶
Horizontal layout
- efl.elementary.ELM_BOX_LAYOUT_VERTICAL¶
Vertical layout
- efl.elementary.ELM_BOX_LAYOUT_HOMOGENEOUS_VERTICAL¶
Homogeneous vertical layout
- efl.elementary.ELM_BOX_LAYOUT_HOMOGENEOUS_HORIZONTAL¶
Homogeneous horizontal layout
- efl.elementary.ELM_BOX_LAYOUT_HOMOGENEOUS_MAX_SIZE_HORIZONTAL¶
Homogeneous layout, maximum size on the horizontal axis
- efl.elementary.ELM_BOX_LAYOUT_HOMOGENEOUS_MAX_SIZE_VERTICAL¶
Homogeneous layout, maximum size on the horizontal axis
- efl.elementary.ELM_BOX_LAYOUT_FLOW_HORIZONTAL¶
Horizontally flowing layout
- efl.elementary.ELM_BOX_LAYOUT_FLOW_VERTICAL¶
Vertically flowing layout
- efl.elementary.ELM_BOX_LAYOUT_STACK¶
Stacking layout
Inheritance diagram¶
- class efl.elementary.Box(Object parent, *args, **kwargs)¶
Bases:
efl.elementary.__init__.Object
This is the class that actually implements the widget.
By default, the box will be in vertical mode and non-homogeneous.
- Parameters
parent (
efl.evas.Object
) – The parent object**kwargs – All the remaining keyword arguments are interpreted as properties of the instance
- align¶
Set the alignment of the whole bounding box of contents.
Sets how the bounding box containing all the elements of the box, after their sizes and position has been calculated, will be aligned within the space given for the whole box widget.
- Return type
(float h, float v)
- align_get()¶
- align_set(horizontal, vertical)¶
- children¶
Retrieve a list of the objects packed into the box
Returns a
list
with the childObjects
. The order of the list corresponds to the packing order the box uses.- Type
list of
Object
- children_get()¶
- clear()¶
Clear the box of all children
Remove all the elements contained by the box, deleting the respective objects.
- homogeneous¶
Whether the box is using homogeneous mode or not
If enabled, homogeneous layout makes all items the same size, according to the size of the largest of its children.
Note
This flag is ignored if a custom layout function is set.
- Type
bool
- homogeneous_get()¶
- homogeneous_set(homogeneous)¶
- horizontal¶
The horizontal orientation.
By default, box object arranges their contents vertically from top to bottom. By setting this property as True, the box will become horizontal, arranging contents from left to right.
Note
This flag is ignored if a custom layout function is set.
- Type
bool
- horizontal_get()¶
- horizontal_set(horizontal)¶
- layout¶
Set the layout function for the box.
A box layout function affects how a box object displays child elements within its area.
Note that you cannot set a custom layout function.
- Type
- layout_set(layout)¶
- layout_transition(duration, from_layout, to_layout)¶
Perform an animation between two given different layout.
If you want to animate the change from one layout to another, you just need to call this function with the starting layout and the final one.
- Parameters
duration (float) – the animation duration in seconds
from_layout (Box layout modes) – one of elementary.ELM_BOX_LAYOUT
to_layout (Box layout modes) – one of elementary.ELM_BOX_LAYOUT
- pack_after(obj, after)¶
Adds an object to the box after the indicated object.
This will add the
subobj
to the box indicated after the object indicated with after. Ifafter
is not already in the box, results are undefined. After means either to the right of the indicated object or below it depending on orientation.
- pack_before(obj, before)¶
Adds an object to the box before the indicated object.
This will add the
subobj
to the box indicated before the object indicated withbefore
. Ifbefore
is not already in the box, results are undefined. Before means either to the left of the indicated object or above it depending on orientation.
- pack_end(obj)¶
Add an object at the end of the pack list.
Pack
subobj
into the box, placing it last in the list of children objects. The actual position the object will get on screen depends on the layout used. If no custom layout is set, it will be at the bottom or right, depending if the box is vertical or horizontal, respectively.- Parameters
subobj (
Object
) – The object to add to the box
- pack_start(obj)¶
Add an object to the beginning of the pack list.
Pack
subobj
into the box, placing it first in the list of children objects. The actual position the object will get on screen depends on the layout used. If no custom layout is set, it will be at the top or left, depending if the box is vertical or horizontal, respectively.- Parameters
subobj (
Object
) – The object to add to the box
- padding¶
The space (padding) between the box’s elements.
Extra space in pixels that will be added between a box child and its neighbors after its containing cell has been calculated. This padding is set for all elements in the box, besides any possible padding that individual elements may have through their size hints.
- Type
(int h, int v)
- padding_get()¶
- padding_set(horizontal, vertical)¶
- recalculate()¶
Force the box to recalculate its children packing.
If any children was added or removed, box will not calculate the values immediately rather leaving it to the next main loop iteration. While this is great as it would save lots of recalculation, whenever you need to get the position of a just added item you must force recalculate before doing so.
- unpack(obj)¶
Unpack a box item.
Remove the object given by
subobj
from the box without deleting it.- Parameters
subobj (
Object
) – The object to unpack
- unpack_all()¶
Remove all items from the box, without deleting them.
Clear the box from all children, but don’t delete the respective objects. If no other references of the box children exist, the objects will never be deleted, and thus the application will leak the memory. Make sure when using this function that you hold a reference to all the objects in the box.