Definition for initializing for a whole Evas_Object_Box_Api structure, with NULL values on its specific fields.

Parameters:

smart_class_init

The initializer to use for the "base" field (Evas_Smart_Class)

See also:

EVAS_SMART_CLASS_INIT_NULL

EVAS_SMART_CLASS_INIT_VERSION

EVAS_SMART_CLASS_INIT_NAME_VERSION

EVAS_OBJECT_BOX_API_INIT_NULL

EVAS_OBJECT_BOX_API_INIT_VERSION

EVAS_OBJECT_BOX_API_INIT_NAME_VERSION

Definition for initializing to zero out a whole Evas_Object_Box_Api structure and set its name and version.

Remarks:

This is similar to EVAS_OBJECT_BOX_API_INIT_NULL, but it also sets the version field of Evas_Smart_Class (base field) to the latest EVAS_SMART_CLASS_VERSION and name it to the specific value.

It keeps a reference to the name field as a "const char *", i.e., the name must be available while the structure is used (hint: static or global variable) and must not be modified.

See also:

EVAS_OBJECT_BOX_API_INIT_NULL

EVAS_OBJECT_BOX_API_INIT_VERSION

EVAS_OBJECT_BOX_API_INIT

Definition for initializing to zero out a whole Evas_Object_Box_Api structure.

See also:

EVAS_OBJECT_BOX_API_INIT_VERSION

EVAS_OBJECT_BOX_API_INIT_NAME_VERSION

EVAS_OBJECT_BOX_API_INIT

Definition for initializing to zero out a whole Evas_Object_Box_Api structure and set a specific version on it.

Remarks:

This is similar to EVAS_OBJECT_BOX_API_INIT_NULL, but it sets the version field of Evas_Smart_Class (base field) to the latest EVAS_SMART_CLASS_VERSION.

See also:

EVAS_OBJECT_BOX_API_INIT_NULL

EVAS_OBJECT_BOX_API_INIT_NAME_VERSION

EVAS_OBJECT_BOX_API_INIT

The structure type containing the base structure for a box option. Box options are a way of extending box items properties, which are taken into account for layouting decisions. The box layouting functions provided by Evas only relies on objects' canonical size hints to layout them, so the basic box option has no (custom) property set.

Users creating their own layouts, but not depending on extra child items' properties, would be fine just using evas_object_box_layout_set(). But if one desires a layout depending on extra child properties, he or she has to subclass the box smart object. Thus, by using evas_object_box_smart_class_get() and evas_object_box_smart_set(), the option_new() and option_free() smart class functions should be properly redefined or extended.

Object properties are bound to an integer identifier and must have a name string. Their values are open to any data. See the API on option properties for more details.

Gets an accessor (a structure providing random items access) to the list of children of a given box object.

Since :

2.3.1

Remarks:

Do not remove or delete objects while walking the list.

Parameters:

[in]

o

The box to retrieve an items iterator from

Returns:

An accessor on o's child objects,
otherwise NULL on errors

Adds a new box object on the provided canvas.

Since :

2.3.1

Remarks:

After instantiation, if a box object has not its layout function set, via evas_object_box_layout_set(), it has it by default set to evas_object_box_layout_horizontal(). The remaining properties of the box must be set/retrieved via evas_object_box_{h,v}_{align,padding}_{get,set)().

Parameters:

[in]

evas

The canvas to create the box object on

Returns:

A pointer to a new box object,
otherwise NULL on error

Adds a new box as a child of a given smart object.

Since :

2.3.1

Remarks:

This function is a helper function that has the same effect of putting a new box object into parent by use of evas_object_smart_member_add().

Parameters:

[in]

parent

The parent smart object to put the new box in

Returns:

A pointer to a new box object,
otherwise NULL on error

See also:

evas_object_box_add()

Gets the alignment of the whole bounding box of contents, for a given box object.

Since :

2.3.1

Parameters:

[in]	o	The given box object to get alignment from
[out]	horizontal	The pointer to a variable where to store the horizontal alignment
[out]	vertical	The pointer to a variable where to store the vertical alignment

See also:

evas_object_box_align_set() for more information

Sets the alignment of the whole bounding box of contents, for a given box object.

This influences how a box object is to align its bounding box of contents within its own area. The values must be in the range 0.0 - 1.0, or undefined behavior is expected. For horizontal alignment, 0.0 means to the left, with 1.0 meaning to the right. For vertical alignment, 0.0 means to the top, with 1.0 meaning to the bottom.

Since :

2.3.1

Remarks:

The default values for both alignments is 0.5.

Parameters:

[in]	o	The given box object to set alignment from
[in]	horizontal	The horizontal alignment, in pixels
[in]	vertical	The vertical alignment, in pixels

See also:

evas_object_box_align_get()

Appends a new child object to the given box object o.

Since :

2.3.1

Remarks:

On success, the "child,added" smart event takes place.

The actual placing of the item relative to the area of o depends on the layout set to it. For example, on horizontal layouts an item in the end of the box's list of children appear on its right.

This call triggers the box's _Evas_Object_Box_Api::append smart function.

Parameters:

[in]	o	The given box object
[in]	child	A child Evas object to be made a member of o

Returns:

A box option bound to the recently added box item,
otherwise NULL on errors

Gets the list of children objects in a given box object.

Since :

2.3.1

Remarks:

The returned list should be freed with eina_list_free() when you no longer need it.

This is a duplicate of the list kept by the box internally. It is up to the user to destroy it when it no longer needs it. It is possible to remove objects from the box when walking this list, but these removals are not reflected on it.

Parameters:

[in]

o

The box to retrieve an items list from

Returns:

A list of o's child objects,
otherwise NULL on errors or if it has no child objects

Inserts a new child object after another existing one, in a given box object o.

Since :

2.3.1

Remarks:

On success, the "child,added" smart event takes place.

This function fails if reference is not a member of o.

The actual placing of the item relative to the area of o depends on the layout set to it.

This call triggers the box's _Evas_Object_Box_Api::insert_after smart function.

Parameters:

[in]	o	The given box object
[in]	child	A child Evas object to be made a member of o
[in]	reference	The child object to place this new one after

Returns:

A box option bound to the recently added box item,
otherwise NULL on errors

Inserts a new child object at a given position, in a given box object o.

Since :

2.3.1

Remarks:

On success, the "child,added" smart event takes place.

This function fails if the given position is invalid, given the internal list of elements of o.

The actual placing of the item relative to the area of o depends on the layout set to it.

This call triggers the box's _Evas_Object_Box_Api::insert_at smart function.

Parameters:

[in]	o	The given box object
[in]	child	A child Evas object to be made a member of o
[in]	pos	The numeric position (starting from 0) to place the new child object at

Returns:

A box option bound to the recently added box item,
otherwise NULL on errors

Inserts a new child object before another existing one, in a given box object o.

Since :

2.3.1

Remarks:

On success, the "child,added" smart event takes place.

This function fails if reference is not a member of o.

The actual placing of the item relative to the area of o depends on the layout set to it.

This call triggers the box's _Evas_Object_Box_Api::insert_before smart function.

Parameters:

[in]	o	The given box object
[in]	child	A child Evas object to be made a member of o
[in]	reference	The child object to place this new one before

Returns:

A box option bound to the recently added box item,
otherwise NULL on errors

Gets an iterator to walk the list of children of a given box object.

Since :

2.3.1

Remarks:

Do not remove or delete objects while walking the list.

Parameters:

[in]

o

The box to retrieve an items iterator from

Returns:

An iterator on o's child objects,
otherwise NULL on errors

Sets the box o to a flow horizontal box.

In a flow horizontal box, the box's child elements are placed in rows (think of text as an analogy). A row has as much elements as can fit into the box's width. The box's overall behavior is controlled by its properties, which are set by the evas_object_box_{h,v}_{align,padding}_set() family of functions. The size hints of the elements in the box -- set by the evas_object_size_hint_{align,padding,weight}_set() functions -- also control the way this function works.

Box's properties:

padding_h tells the box to draw empty spaces of that size, in pixels, between the child objects' cells. align_h dictates the horizontal alignment of the rows (0.0 to left align them, 1.0 to right align). A value of -1.0 to align_h lets the rows justified horizontally. align_v controls the vertical alignment of the entire set of rows (0.0 to top, 1.0 to bottom). A value of -1.0 to align_v makes the box to justify the rows vertically. The padding between them, in this case, is corrected so that the first row touches the top border and the last one touches the bottom border (even if they must overlap). padding_v has no influence on the layout.

Child element's properties:

padding_l and padding_r sum up to the required width of the child element. The align_x property has no influence on the layout. The child's padding_t and padding_b sum up to the required height of the child element and is the only means (besides row justifying) of setting space between rows. Note, however, that align_y dictates positioning relative to the largest height required by a child object in the actual row.

Since :

2.3.1

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Sets the box o to a flow vertical box.

This function behaves analogously to evas_object_box_layout_flow_horizontal(). The description of its behaviour can be derived from that function's documentation.

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Since :

2.3.1

Sets the box o to a homogeneous horizontal box.

In a homogeneous horizontal box, its width is divided equally between the contained objects. The box's overall behavior is controlled by its padding or alignment properties, which are set by the evas_object_box_{h,v}_{align,padding}_set() family of functions. The size hints the elements in the box -- set by the evas_object_size_hint_{align,padding,weight}_set() functions -- also control the way this function works.

Box's properties:

align_h has no influence on the box for this layout. padding_h tells the box to draw empty spaces of that size, in pixels, between the (equal) child objects' cells. The align_v and padding_v properties of the box do not contribute to its behaviour when this layout is chosen.

Child element's properties:

padding_l and padding_r sum up to the required width of the child element. The align_x property tells the relative position of this overall child width in its allocated cell (0.0 to extreme left, 1.0 to extreme right). A value of -1.0 to align_x makes the box try to resize this child element to the exact width of its cell (respecting the minimum and maximum size hints on the child's width and accounting for its horizontal padding hints). The child's padding_t, padding_b and align_y properties apply for padding or alignment relative to the overall height of the box. A value of -1.0 to align_y makes the box try to resize this child element to the exact height of its parent (respecting the maximum size hint on the child's height).

Since :

2.3.1

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Sets the box o to a maximum size, homogeneous horizontal box.

In a maximum size, homogeneous horizontal box, besides having cells of equal size reserved for the child objects, this size is defined by the size of the largest child in the box (in width). The box's overall behavior is controlled by its properties, which are set by the evas_object_box_{h,v}_{align,padding}_set() family of functions. The size hints of the elements in the box -- set by the evas_object_size_hint_{align,padding,weight}_set() functions -- also control the way this function works.

Box's properties:

padding_h tells the box to draw empty spaces of that size, in pixels, between the child objects' cells. align_h controls the horizontal alignment of the child objects, relative to the containing box. When set to 0.0, children are aligned to the left. A value of 1.0 lets them aligned to the right border. Values in between align them proportionally. A negative value of align_h makes the box to justify its children cells. The padding between them, in this case, is corrected so that the leftmost one touches the left border and the rightmost one touches the right border (even if they must overlap). The align_v and padding_v properties of the box do not contribute to its behaviour when this layout is chosen.

Child element's properties:

padding_l and padding_r sum up to the required width of the child element. The align_x property tells the relative position of this overall child width in its allocated cell (0.0 to extreme left, 1.0 to extreme right). A value of -1.0 to align_x makes the box try to resize this child element to the exact width of its cell (respecting the minimum and maximum size hints on the child's width and accounting for its horizontal padding hints). The child's padding_t, padding_b and align_y properties apply for padding/alignment relative to the overall height of the box. A value of -1.0 to align_y makes the box try to resize this child element to the exact height of its parent (respecting the max hint on the child's height).

Since :

2.3.1

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Sets the box o to a maximum size, homogeneous vertical box.

Since :

2.3.1

Remarks:

This function behaves analogously to evas_object_box_layout_homogeneous_max_size_horizontal(). The description of its behaviour can be derived from that function's documentation.

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Sets the box o to a homogeneous vertical box.

This Layout function behaves analogously to evas_object_box_layout_homogeneous_horizontal(). The description of its behaviour can be derived from that function's documentation.

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Since :

2.3.1

Layout function which sets the box o to a (basic) horizontal box.

In this layout, the box object's overall behavior is controlled by its padding/alignment properties, which are set by the evas_object_box_{h,v}_{align,padding}_set() family of functions. The size hints of the elements in the box -- set by the evas_object_size_hint_{align,padding,weight}_set() functions -- also control the way this function works.

Box's properties:

align_h controls the horizontal alignment of the child objects relative to the containing box. When set to 0.0, children are aligned to the left. A value of 1.0 makes them aligned to the right border. Values in between align them proportionally. Note that if the size required by the children, which is given by their widths and the padding_h property of the box, is bigger than the their container's width, the children are displayed out of the box's bounds. A negative value of align_h makes the box to justify its children. The padding between them, in this case, is corrected so that the leftmost one touches the left border and the rightmost one touches the right border (even if they must overlap). The align_v and padding_v properties of the box do not contribute to its behaviour when this layout is chosen.

Child element's properties:

align_x does not influence the box's behavior. padding_l and padding_r sum up to the container's horizontal padding between elements. The child's padding_t, padding_b and align_y properties apply for padding or alignment relative to the overall height of the box. Finally, there is the weight_x property, which, if set to a non-zero value, tells the container that the child width is not pre-defined. If the container can not accommodate all its children, it sets the widths of the ones with weights to sizes as small as they can all fit into it. If the size required by the children is less than the available, the box increases its childrens' (which have weights) widths as to fit the remaining space. The weight_x property, besides telling the element is resizable, gives a weight for the resizing process. The parent box tries to distribute (or take off) widths accordingly to the normalized list of weights: most weighted children remain or get larger in this process than the least ones. weight_y does not influence the layout.

If you desire that, besides having weights, child elements must be resized bounded to a minimum or maximum size, those size hints must be set, by the evas_object_size_hint_{min,max}_set() functions.

Since :

2.3.1

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Sets a new layouting function to a given box object.

Since :

2.3.1

Remarks:

A box layout function affects how a box object displays child elements within its area. The list of pre-defined box layouts available in Evas is:

• evas_object_box_layout_horizontal()
• evas_object_box_layout_vertical()
• evas_object_box_layout_homogeneous_horizontal()
• evas_object_box_layout_homogeneous_vertical()
• evas_object_box_layout_homogeneous_max_size_horizontal()
• evas_object_box_layout_homogeneous_max_size_vertical()
• evas_object_box_layout_flow_horizontal()
• evas_object_box_layout_flow_vertical()
• evas_object_box_layout_stack() See each of their documentation texts for details on them.

A box layouting function is triggered by the 'calculate' smart callback of the box's smart class.

Parameters:

[in]	o	The box object to operate on
[in]	cb	The new layout function to set on o
[in]	data	The data pointer to be passed to cb
[in]	free_data	The function to free data, if need be

Sets the box o to a stacking box.

In a stacking box, all children are given the same size -- the box's own size -- and they are stacked one above the other, so that the first object in o's internal list of child elements are the bottommost in the stack.

Box's properties:

No box properties are used.

Child element's properties:

padding_l and padding_r sum up to the required width of the child element. The align_x property tells the relative position of this overall child width in its allocated cell (0.0 to extreme left, 1.0 to extreme right). A value of -1.0 to align_x makes the box try to resize this child element to the exact width of its cell (respecting the min and max hints on the child's width and accounting for its horizontal padding properties). The same applies to the vertical axis.

Since :

2.3.1

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Sets the box o to a (basic) vertical box.

This Layout function behaves analogously to evas_object_box_layout_horizontal(). The description of its behaviour can be derived from that function's documentation.

Parameters:

[in]	o	The box object in question
[in]	priv	The smart data of the o
[in]	data	The data pointer passed on evas_object_box_layout_set(), if any

Since :

2.3.1

Gets a property's value (by its given numerical identifier), on a given box child element.

Since :

2.3.1

Remarks:

This call does not do anything for a canonical Evas box. Only users which have subclassed it, getting custom box items options (see Evas_Object_Box_Option) on it, would benefit from this function. They would have to implement it and get it to be the _Evas_Object_Box_Api::property_get smart class function of the box, which is originally get to NULL.

This function internally creates a variable argument list, with the values passed after property, and call evas_object_box_option_property_vget() with this list and the same previous arguments.

Parameters:

[in]	o	The box parenting the child element
[in]	opt	The box option structure bound to the child box element to get a property from
[in]	property	The numerical ID of the given property
[in]	...	(List of) pointer(s) where to store the value(s) set for this property, It (they) must point to variable(s) of the same type the user has defined for it (them).

Returns:

EINA_TRUE if the property values are obtained successfully,
otherwise EINA_FALSE on failure

Gets the numerical identifier of the property of the child elements of the box o which have name as name string.

Since :

2.3.1

Remarks:

This call does not do anything for a canonical Evas box. Only users which have subclassed it, setting custom box items options (see Evas_Object_Box_Option) on it, would benefit from this function. They would have to implement it and set it to be the _Evas_Object_Box_Api::property_id_get smart class function of the box, which is originally set to NULL.

Parameters:

[in]	o	The box to search child options from
[in]	name	The name string of the option being searched, for its ID

Returns:

The numerical ID of the given property,
otherwise -1 on errors

Gets the name of the property of the child elements of the box o which have id as identifier.

Since :

2.3.1

Remarks:

This call does not do anything for a canonical Evas box. Only users which have subclassed it, setting custom box items options (see Evas_Object_Box_Option) on it, would benefit from this function. They would have to implement it and set it to be the _Evas_Object_Box_Api::property_name_get smart class function of the box, which is originally set to NULL.

Parameters:

[in]	o	The box to search child options from
[in]	property	The numerical identifier of the option being searched, for its name

Returns:

The name of the given property,
otherwise NULL on errors

Sets a property value (by its given numerical identifier), on a given box child element.

Since :

2.3.1

Remarks:

This call does not do anything for a canonical Evas box. Only users which have subclassed it, setting custom box items options (see Evas_Object_Box_Option) on it, would benefit from this function. They would have to implement it and set it to be the _Evas_Object_Box_Api::property_set smart class function of the box, which is originally set to NULL.

This function internally creates a variable argument list, with the values passed after property, and call evas_object_box_option_property_vset() with this list and the same previous arguments.

Parameters:

[in]	o	The box parenting the child element
[in]	opt	The box option structure bound to the child box element to set a property on
[in]	property	The numerical ID of the given property
[in]	...	(List of) actual value(s) to be set for this property It (they) must be of the same type the user has defined for it (them).

Returns:

EINA_TRUE if the property value is set successfully, otherwise EINA_FALSE on failure

Gets a property's value (by its given numerical identifier), on a given box child element -- by a variable argument list.

Since :

2.3.1

Remarks:

This is a variable argument list variant of the evas_object_box_option_property_get(). See its documentation for more details.

Parameters:

[in]	o	The box parenting the child element
[in]	opt	The box option structure bound to the child box element to get a property from
[in]	property	The numerical ID of the given property
[in]	args	The variable argument list with pointers to where to store the values of this property They must point to variables of the same type the user has defined for them.

Returns:

EINA_TRUE if the property values are obtained successfully,
otherwise EINA_FALSE on failure

Sets a property value (by its given numerical identifier), on a given box child element -- by a variable argument list.

Since :

2.3.1

Remarks:

This is a variable argument list variant of the evas_object_box_option_property_set(). See its documentation for more details.

Parameters:

[in]	o	The box parenting the child element
[in]	opt	The box option structure bound to the child box element to set a property on
[in]	property	The numerical ID of the given property
[in]	args	The variable argument list implementing the value to be set for this property. It must be of the same type the user has defined for it.

Returns:

EINA_TRUE if teh property value is set successfully,
otherwise EINA_FALSE on failure

Gets the (space) padding between cells set for a given box object.

Since :

2.3.1

Parameters:

[in]	o	The given box object to get padding from
[out]	horizontal	The pointer to a variable where to store the horizontal padding
[out]	vertical	The pointer to a variable where to store the vertical padding

See also:

evas_object_box_padding_set()

Sets the (space) padding between cells set for a given box object.

Since :

2.3.1

Remarks:

The default values for both padding components is 0.

Parameters:

[in]	o	The given box object to set padding from
[in]	horizontal	The horizontal padding, in pixels
[in]	vertical	The vertical padding, in pixels

See also:

evas_object_box_padding_get()

Prepends a new child object to the given box object o.

Since :

2.3.1

Remarks:

On success, the "child,added" smart event takes place.

The actual placing of the item relative to the area of o depends on the layout set to it. For example, on horizontal layouts an item in the beginning of the box's list of children appear on its left.

This call triggers the box's _Evas_Object_Box_Api::prepend smart function.

Parameters:

[in]	o	The given box object
[in]	child	A child Evas object to be made a member of o

Returns:

A box option bound to the recently added box item,
otherwise NULL on errors

Removes a given object from a box object, unparenting it again.

Since :

2.3.1

Remarks:

On removal, you get an unparented object again, just as it is before you inserted it in the box. The _Evas_Object_Box_Api::option_free box smart callback is called automatically for you and, also, the "child,removed" smart event takes place.

This call triggers the box's _Evas_Object_Box_Api::remove smart function.

Parameters:

[in]	o	The box object to remove a child object from
[in]	child	The handle to the child object to be removed

Returns:

EINA_TRUE if the object is removed from the box object successfully,
otherwise EINA_FALSE on failure

Removes all child objects from a box object, unparenting them again.

Since :

2.3.1

Remarks:

This has the same effect of calling evas_object_box_remove() on each of o's child objects, in sequence. If, and only if, all those calls succeed, so does this one.

Parameters:

[in]	o	The box object to remove a child object from
[in]	clear	Set EINA_TRUE to delete the just removed children, otherwise set EINA_FALSE to not delete the children

Returns:

EINA_TRUE if the child objects are removed successfully,
otherwise EINA_FALSE on failure

Removes an object, bound to a given position in a box object, unparenting it again.

Since :

2.3.1

Remarks:

On removal, you get an unparented object again, just as it is before you inserted it in the box. The option_free() box smart callback is called automatically for you and, also, the "child,removed" smart event takes place.

This function fails if the given position is invalid, given the internal list of elements of o.

This call triggers the box's _Evas_Object_Box_Api::remove_at smart function.

Parameters:

[in]	o	The box object to remove a child object from
[in]	pos	The numeric position (starting from 0) of the child object to be removed

Returns:

EINA_TRUE if the object is removed successfully, otherwise EINA_FALSE on failure

Gets the Evas box smart class, for inheritance purposes.

Since :

2.3.1

Remarks:

The returned value is not to be modified, just use it as your parent class.

Returns:

The (canonical) Evas box smart class

Sets the default box api struct (Evas_Object_Box_Api) with the default values. This may be used to extend that API.

Since :

2.3.1

Parameters:

api	The box API struct to set back, most probably with overridden fields (on class extensions scenarios)