Box Smart Object

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files
- Examples

Data Structures | Macros | Typedefs | Functions
Box Smart Object
Evas » Smart Object Functions

A box is a convenience smart object that packs children inside it in sequence, using a layouting function specified by the user. More...

## Data Structures
struct | _Evas_Object_Box_Api
| This structure should be used by any smart class inheriting from the box's one, to provide custom box behavior which could not be achieved only by providing a layout function, with evas_object_box_layout_set(). More...
struct | _Evas_Object_Box_Data
| This structure augments clipped smart object's instance data, providing extra members required by generic box implementation. More...
struct | _Evas_Object_Box_Option
| Evas_Object_Box_Option struct fields More...

## Macros
#define | EVAS_OBJECT_BOX_API_VERSION 1
| Current version for Evas box object smart class, a value which goes to _Evas_Object_Box_Api::version.
#define | EVAS_OBJECT_BOX_API_INIT(smart_class_init) {smart_class_init, EVAS_OBJECT_BOX_API_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
| Initializer for a whole Evas_Object_Box_Api structure, with `NULL` values on its specific fields. More...
#define | EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
| Initializer to zero out a whole Evas_Object_Box_Api structure. More...
#define | EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
| Initializer to zero out a whole Evas_Object_Box_Api structure and set a specific version on it. More...
#define | EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
| Initializer to zero out a whole Evas_Object_Box_Api structure and set its name and version. More...

## Typedefs
typedef struct _Evas_Object_Box_Api | Evas_Object_Box_Api
| Smart class extension, providing extra box object requirements.
typedef struct _Evas_Object_Box_Data | Evas_Object_Box_Data
| Smart object instance data, providing box object requirements.
typedef struct _Evas_Object_Box_Option | Evas_Object_Box_Option
| The base structure for a box option. More...
typedef void(* | Evas_Object_Box_Layout) (Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data)
| Function signature for an Evas box object layouting routine. More...

## Functions
void | evas_object_box_smart_set (Evas_Object_Box_Api *api)
| Set the default box api struct (Evas_Object_Box_Api) with the default values. More...
const Evas_Object_Box_Api * | evas_object_box_smart_class_get (void)
| Get the Evas box smart class, for inheritance purposes. More...
Evas_Object * | evas_object_box_add (Evas *evas)
| Add a new box object on the provided canvas. More...
Eina_Bool | evas_object_box_option_property_vget (const Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args)
| Get a property's value (by its given numerical identifier), on a given box child element – by a variable argument list. More...
Eina_Bool | evas_object_box_option_property_vset (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args)
| Set a property value (by its given numerical identifier), on a given box child element – by a variable argument list. More...
Eina_Bool | evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property,...)
| Set a property value (by its given numerical identifier), on a given box child element. More...
Eina_Bool | evas_object_box_option_property_get (const Evas_Object *o, Evas_Object_Box_Option *opt, int property,...)
| Get a property's value (by its given numerical identifier), on a given box child element. More...
Eina_List * | evas_object_box_children_get (const Evas_Object *o)
| Get the list of children objects in a given box object. More...

## Detailed Description

A box is a convenience smart object that packs children inside it in sequence, using a layouting function specified by the user.

There are a couple of pre-made layouting functions built-in in Evas, all of them using children size hints to define their size and alignment inside their cell space.

Examples on this smart object's usage:

- Evas box example
- Evas alignment, minimum size, maximum size, padding and weight hints example

See also
  Size Hints

## Macro Definition Documentation

#define EVAS_OBJECT_BOX_API_INIT | ( |  | smart_class_init | ) | {smart_class_init, EVAS_OBJECT_BOX_API_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}

Initializer for a whole Evas_Object_Box_Api structure, with `NULL` values on its specific fields.

Parameters

  smart_class_init | 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

#define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)

Initializer 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

#define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)

Initializer to zero out a whole Evas_Object_Box_Api structure and set a specific version on it.

This is similar to EVAS_OBJECT_BOX_API_INIT_NULL, but it will set 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

#define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION | ( |  | name | ) | EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))

Initializer to zero out a whole Evas_Object_Box_Api structure and set its name and version.

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

It will keep 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

## Typedef Documentation

Evas_Object_Box_Option

The base structure for a box option.

Box options are a way of extending box items properties, which will be taken into account for layouting decisions. The box layouting functions provided by Evas will only rely 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/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/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.

Evas_Object_Box_Layout

Function signature for an Evas box object layouting routine.

By o it will be passed the box object in question, by priv it will be passed the box's internal data and, by user_data, it will be passed any custom data one could have set to a given box layouting function, with evas_object_box_layout_set().

## Function Documentation

void evas_object_box_smart_set | ( | Evas_Object_Box_Api * | api | ) |

Set the default box api struct (Evas_Object_Box_Api) with the default values.

May be used to extend that API.

Parameters

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

const Evas_Object_Box_Api* evas_object_box_smart_class_get | ( | void |  | ) |

Get the Evas box smart class, for inheritance purposes.

Returns
  the (canonical) Evas box smart class.

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

References alloca(), _Eina_List::data, EINA_FALSE, eina_list_accessor_new(), eina_list_count(), EINA_LIST_FOREACH, eina_list_iterator_new(), EINA_MAGIC_SET, EINA_TRUE, evas_object_del(), evas_object_geometry_get(), evas_object_move(), evas_object_resize(), evas_object_smart_member_add(), evas_object_smart_member_del(), evas_object_stack_above(), FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, FUNC_ACCESSOR_GET_CONTAINER, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, FUNC_ITERATOR_NEXT, _Eina_List::next, and _Evas_Object_Box_Option::obj.

Evas_Object* evas_object_box_add | ( | Evas * | evas | ) |

Add a new box object on the provided canvas.

Parameters

  evas | The canvas to create the box object on.

Returns
  `NULL` on error, a pointer to a new box object on success.

After instantiation, if a box object hasn't its layout function set, via evas_object_box_layout_set(), it will have 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)()`.

References eo_add, evas_object_box_add(), and evas_object_smart_member_add().

Referenced by edje_edit_part_name_set(), edje_file_data_get(), and evas_object_box_add().

Eina_Bool evas_object_box_option_property_vget | ( | const Evas_Object * | o,
|  | Evas_Object_Box_Option * | opt,
|  | int | property,
|  | va_list | args
| ) |  |

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

Parameters

  o | The box parenting the child element
  opt | The box option structure bound to the child box element to get a property from
  property | The numerical ID of the given property
  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` on success, `EINA_FALSE` on failure.

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

References EINA_FALSE, and evas_smart_legacy_type_register().

Referenced by evas_object_box_option_property_get().

Eina_Bool evas_object_box_option_property_vset | ( | Evas_Object * | o,
|  | Evas_Object_Box_Option * | opt,
|  | int | property,
|  | va_list | args
| ) |  |

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

Parameters

  o | The box parenting the child element
  opt | The box option structure bound to the child box element to set a property on
  property | The numerical ID of the given property
  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` on success, `EINA_FALSE` on failure.

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

References EINA_FALSE.

Referenced by evas_object_box_option_property_set().

Eina_Bool evas_object_box_option_property_set | ( | Evas_Object * | o,
|  | Evas_Object_Box_Option * | opt,
|  | int | property,
|  |  | ...
| ) |  |

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

Parameters

  o | The box parenting the child element
  opt | The box option structure bound to the child box element to set a property on
  property | The numerical ID of the given property
  ... | (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` on success, `EINA_FALSE` on failure.

Note
  This call won't 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'd 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 will internally create 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.

References evas_object_box_option_property_vset().

Eina_Bool evas_object_box_option_property_get | ( | const Evas_Object * | o,
|  | Evas_Object_Box_Option * | opt,
|  | int | property,
|  |  | ...
| ) |  |

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

Parameters

  o | The box parenting the child element
  opt | The box option structure bound to the child box element to get a property from
  property | The numerical ID of the given property
  ... | (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` on success, `EINA_FALSE` on failure.

Note
  This call won't 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'd 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 will internally create 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.

References evas_object_box_option_property_vget().

Eina_List* evas_object_box_children_get | ( | const Evas_Object * | o | ) |

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

Parameters

  o | The box to retrieve an items list from

Returns
  A list of `o's` child objects, on success, or `NULL`, on errors (or if it has no child objects)

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

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

Examples:
  evas-box.c.

References eina_list_append(), EINA_LIST_FOREACH, and _Evas_Object_Box_Option::obj.

Referenced by edje_box_layout_register(), and edje_file_data_get().