Box

Typedefs
typedef struct _Elm_Box_Transition	Elm_Box_Transition
	Opaque handler containing the parameters to perform an animated transition of the layout the box uses. More...

Functions
void	elm_box::pack_end (evas::object subobj_) const
	Add an object at the end of the pack list. More...
void	elm_box::unpack_all () const
	Remove all items from the box, without deleting them. More...
void	elm_box::unpack (evas::object subobj_) const
	Unpack a box item. More...
void	elm_box::pack_after (evas::object subobj_, evas::object after_) const
	Adds an object to the box after the indicated object. More...
void	elm_box::pack_start (evas::object subobj_) const
	Add an object to the beginning of the pack list. More...
void	elm_box::recalculate () const
	Force the box to recalculate its children packing. More...
void	elm_box::pack_before (evas::object subobj_, evas::object before_) const
	Adds an object to the box before the indicated object. More...
void	elm_box::clear () const
	Clear the box of all children. More...
bool	elm_box::homogeneous_get () const
	Get whether the box is using homogeneous mode or not. More...
void	elm_box::homogeneous_set (bool homogeneous_) const
	Get whether the box is using homogeneous mode or not. More...
void	elm_box::align_get (double *horizontal_, double *vertical_) const
	Get the alignment of the whole bounding box of contents. More...
void	elm_box::align_set (double horizontal_, double vertical_) const
	Get the alignment of the whole bounding box of contents. More...
void	elm_box::padding_get (Evas_Coord *horizontal_, Evas_Coord *vertical_) const
	Get the space (padding) between the box's elements. More...
void	elm_box::padding_set (Evas_Coord horizontal_, Evas_Coord vertical_) const
	Get the space (padding) between the box's elements. More...
efl::eina::list< evas::object >	elm_box::children_get () const
	Retrieve a list of the objects packed into the box. More...
void	elm_box_layout_transition (Evas_Object *obj, Evas_Object_Box_Data *priv, void *data)
	Special layout function that animates the transition from one layout to another. More...
Elm_Box_Transition *	elm_box_transition_new (const double duration, Evas_Object_Box_Layout start_layout, void *start_layout_data, Ecore_Cb start_layout_free_data, Evas_Object_Box_Layout end_layout, void *end_layout_data, Ecore_Cb end_layout_free_data, Ecore_Cb transition_end_cb, void *transition_end_data)
	Create a new Elm_Box_Transition to animate the switch of layouts. More...
void	elm_box_transition_free (void *data)
	Free a Elm_Box_Transition instance created with elm_box_transition_new(). More...
Evas_Object *	elm_box_add (Evas_Object *parent)
	Add a new box to the parent. More...

Detailed 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 elm_box_homogeneous_set(), the values given by elm_box_padding_set() and elm_box_align_set() and the hints set to each object in the box.

For this default layout, it's possible to change the orientation with elm_box_horizontal_set(). 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 elm_box_align_set(), 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. evas_object_size_hint_min_set() 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.

evas_object_size_hint_weight_set(), 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 evas_object_size_hint_align_set(). 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 elm_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.

Some examples on how to use boxes follow:

• Box - Basic API
• Box - Layout transitions

Typedef Documentation

Elm_Box_Transition

Opaque handler containing the parameters to perform an animated transition of the layout the box uses.

See also

elm_box_transition_new()

elm_box_layout_set()

elm_box_layout_transition()

Function Documentation

void elm_box::align_get ( double *  horizontal_, double *  vertical_  ) const

inline

Get the alignment of the whole bounding box of contents.

See also

elm_box_align_set()

Parameters

horizontal	The horizontal alignment of elements
vertical	The vertical alignment of elements

void elm_box::align_set ( double  horizontal_, double  vertical_  ) const

inline

Get the alignment of the whole bounding box of contents.

See also

elm_box_align_set()

Parameters

horizontal	The horizontal alignment of elements
vertical	The vertical alignment of elements

efl::eina::list< evas::object > elm_box::children_get ( ) const

inline

Retrieve a list of the objects packed into the box.

Returns a new Eina_List with a pointer to Evas_Object in its nodes. The order of the list corresponds to the packing order the box uses.

You must free this list with eina_list_free() once you are done with it.

void elm_box::clear ( ) const

inline

Clear the box of all children.

Remove all the elements contained by the box, deleting the respective objects.

See also

elm_box_unpack()

elm_box_unpack_all()

Evas_Object* elm_box_add

(

Evas_Object *

parent

)

Add a new box to the parent.

By default, the box will be in vertical mode and non-homogeneous.

Parameters

parent

The parent object

Returns

The new object or NULL if it cannot be created

void elm_box_layout_transition	(	Evas_Object *	obj,
		Evas_Object_Box_Data *	priv,
		void *	data
	)

Special layout function that animates the transition from one layout to another.

Normally, when switching the layout function for a box, this will be reflected immediately on screen on the next render, but it's also possible to do this through an animated transition.

This is done by creating an Elm_Box_Transition and setting the box layout to this function.

For example:

Elm_Box_Transition *t = elm_box_transition_new(1.0,
                           evas_object_box_layout_vertical, // start
                           NULL, // data for initial layout
                           NULL, // free function for initial data
                           evas_object_box_layout_horizontal, // end
                           NULL, // data for final layout
                           NULL, // free function for final data
                           anim_end, // will be called when animation ends
                           NULL); // data for anim_end function\
elm_box_layout_set(box, elm_box_layout_transition, t,
                   elm_box_transition_free);

Note

This function can only be used with elm_box_layout_set(). Calling it directly will not have the expected results.

See also

elm_box_transition_new

elm_box_transition_free

elm_box_layout_set

void elm_box_transition_free

(

void *

data

)

Free a Elm_Box_Transition instance created with elm_box_transition_new().

This function is mostly useful as the free_data parameter in elm_box_layout_set() when elm_box_layout_transition().

Parameters

data	The Elm_Box_Transition instance to be freed.

See also

elm_box_transition_new

elm_box_layout_transition

Elm_Box_Transition* elm_box_transition_new	(	const double	duration,
		Evas_Object_Box_Layout	start_layout,
		void *	start_layout_data,
		Ecore_Cb	start_layout_free_data,
		Evas_Object_Box_Layout	end_layout,
		void *	end_layout_data,
		Ecore_Cb	end_layout_free_data,
		Ecore_Cb	transition_end_cb,
		void *	transition_end_data
	)

Create a new Elm_Box_Transition to animate the switch of layouts.

If you want to animate the change from one layout to another, you need to set the layout function of the box to elm_box_layout_transition(), passing as user data to it an instance of Elm_Box_Transition with the necessary information to perform this animation. The free function to set for the layout is elm_box_transition_free().

The parameters to create an Elm_Box_Transition sum up to how long will it be, in seconds, a layout function to describe the initial point, another for the final position of the children and one function to be called when the whole animation ends. This last function is useful to set the definitive layout for the box, usually the same as the end layout for the animation, but could be used to start another transition.

Parameters

duration	The duration of the transition in seconds
start_layout	The layout function that will be used to start the animation
start_layout_data	The data to be passed the start_layout function
start_layout_free_data	Function to free start_layout_data
end_layout	The layout function that will be used to end the animation
end_layout_data	Data param passed to end_layout
end_layout_free_data	The data to be passed the end_layout function
end_layout_free_data	Function to free end_layout_data
transition_end_cb	Callback function called when animation ends
transition_end_data	Data to be passed to transition_end_cb

Returns

An instance of Elm_Box_Transition

See also

elm_box_transition_new

elm_box_layout_transition

bool elm_box::homogeneous_get ( ) const

inline

Get whether the box is using homogeneous mode or not.

Returns

EINA_TRUE if it's homogeneous, EINA_FALSE otherwise

Parameters

homogeneous

The homogeneous flag

void elm_box::homogeneous_set ( bool  homogeneous_ ) const

inline

Get whether the box is using homogeneous mode or not.

Returns

EINA_TRUE if it's homogeneous, EINA_FALSE otherwise

Parameters

homogeneous

The homogeneous flag

void elm_box::pack_after ( evas::object  subobj_, evas::object  after_  ) const

inline

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

See also

elm_box_pack_start()

elm_box_pack_end()

elm_box_pack_before()

elm_box_unpack()

elm_box_unpack_all()

elm_box_clear()

Parameters

subobj	The object to add to the box
after	The object after which to add it

void elm_box::pack_before ( evas::object  subobj_, evas::object  before_  ) const

inline

Adds an object to the box before the indicated object.

This will add the subobj to the box indicated before the object indicated with before. If before 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.

See also

elm_box_pack_start()

elm_box_pack_end()

elm_box_pack_after()

elm_box_unpack()

elm_box_unpack_all()

elm_box_clear()

Parameters

subobj	The object to add to the box
before	The object before which to add it

void elm_box::pack_end ( evas::object  subobj_ ) const

inline

Add an object at the end of the pack list.

Pack subobj into the box obj, 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.

See also

elm_box_pack_start()

elm_box_pack_before()

elm_box_pack_after()

elm_box_unpack()

elm_box_unpack_all()

elm_box_clear()

Parameters

subobj

The object to add to the box

void elm_box::pack_start ( evas::object  subobj_ ) const

inline

Add an object to the beginning of the pack list.

Pack subobj into the box obj, 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.

See also

elm_box_pack_end()

elm_box_pack_before()

elm_box_pack_after()

elm_box_unpack()

elm_box_unpack_all()

elm_box_clear()

Parameters

subobj

The object to add to the box

void elm_box::padding_get ( Evas_Coord *  horizontal_, Evas_Coord *  vertical_  ) const

inline

Get the space (padding) between the box's elements.

See also

elm_box_padding_set()

Parameters

horizontal	The horizontal space between elements
vertical	The vertical space between elements

void elm_box::padding_set ( Evas_Coord  horizontal_, Evas_Coord  vertical_  ) const

inline

Get the space (padding) between the box's elements.

See also

elm_box_padding_set()

Parameters

horizontal	The horizontal space between elements
vertical	The vertical space between elements

void elm_box::recalculate ( ) const

inline

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.

void elm_box::unpack ( evas::object  subobj_ ) const

inline

Unpack a box item.

Remove the object given by subobj from the box obj without deleting it.

See also

elm_box_unpack_all()

elm_box_clear()

Parameters

subobj

The object to unpack

void elm_box::unpack_all ( ) const

inline

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

See also

elm_box_clear()

elm_box_unpack()