5 * @image html box_inheritance_tree.png
6 * @image latex box_inheritance_tree.eps
8 * @image html img/widget/box/preview-00.png
9 * @image latex img/widget/box/preview-00.eps width=\textwidth
11 * @image html img/box.png
12 * @image latex img/box.eps width=\textwidth
14 * A box arranges objects in a linear fashion, governed by a layout function
15 * that defines the details of this arrangement.
17 * By default, the box will use an internal function to set the layout to
18 * a single row, either vertical or horizontal. This layout is affected
19 * by a number of parameters, such as the homogeneous flag set by
20 * elm_box_homogeneous_set(), the values given by elm_box_padding_set() and
21 * elm_box_align_set() and the hints set to each object in the box.
23 * For this default layout, it's possible to change the orientation with
24 * elm_box_horizontal_set(). The box will start in the vertical orientation,
25 * placing its elements ordered from top to bottom. When horizontal is set,
26 * the order will go from left to right. If the box is set to be
27 * homogeneous, every object in it will be assigned the same space, that
28 * of the largest object. Padding can be used to set some spacing between
29 * the cell given to each object. The alignment of the box, set with
30 * elm_box_align_set(), determines how the bounding box of all the elements
31 * will be placed within the space given to the box widget itself.
33 * The size hints of each object also affect how they are placed and sized
34 * within the box. evas_object_size_hint_min_set() will give the minimum
35 * size the object can have, and the box will use it as the basis for all
36 * latter calculations. Elementary widgets set their own minimum size as
37 * needed, so there's rarely any need to use it manually.
39 * evas_object_size_hint_weight_set(), when not in homogeneous mode, is
40 * used to tell whether the object will be allocated the minimum size it
41 * needs or if the space given to it should be expanded. It's important
42 * to realize that expanding the size given to the object is not the same
43 * thing as resizing the object. It could very well end being a small
44 * widget floating in a much larger empty space. If not set, the weight
45 * for objects will normally be 0.0 for both axis, meaning the widget will
46 * not be expanded. To take as much space possible, set the weight to
47 * EVAS_HINT_EXPAND (defined to 1.0) for the desired axis to expand.
49 * Besides how much space each object is allocated, it's possible to control
50 * how the widget will be placed within that space using
51 * evas_object_size_hint_align_set(). By default, this value will be 0.5
52 * for both axis, meaning the object will be centered, but any value from
53 * 0.0 (left or top, for the @c x and @c y axis, respectively) to 1.0
54 * (right or bottom) can be used. The special value EVAS_HINT_FILL, which
55 * is -1.0, means the object will be resized to fill the entire space it
58 * In addition, customized functions to define the layout can be set, which
59 * allow the application developer to organize the objects within the box
60 * in any number of ways.
62 * The special elm_box_layout_transition() function can be used
63 * to switch from one layout to another, animating the motion of the
64 * children of the box.
66 * @note Objects should not be added to box objects using _add() calls.
68 * Some examples on how to use boxes follow:
69 * @li @ref box_example_01
70 * @li @ref box_example_02
75 * @typedef Elm_Box_Transition
77 * Opaque handler containing the parameters to perform an animated
78 * transition of the layout the box uses.
80 * @see elm_box_transition_new()
81 * @see elm_box_layout_set()
82 * @see elm_box_layout_transition()
84 typedef struct _Elm_Box_Transition Elm_Box_Transition;
87 * Add a new box to the parent
89 * By default, the box will be in vertical mode and non-homogeneous.
91 * @param parent The parent object
92 * @return The new object or NULL if it cannot be created
96 EAPI Evas_Object *elm_box_add(Evas_Object *parent);
99 * Set the horizontal orientation
101 * By default, box object arranges their contents vertically from top to
103 * By calling this function with @p horizontal as EINA_TRUE, the box will
104 * become horizontal, arranging contents from left to right.
106 * @note This flag is ignored if a custom layout function is set.
108 * @param obj The box object
109 * @param horizontal The horizontal flag (EINA_TRUE = horizontal,
110 * EINA_FALSE = vertical)
114 EAPI void elm_box_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
117 * Get the horizontal orientation
119 * @param obj The box object
120 * @return EINA_TRUE if the box is set to horizontal mode, EINA_FALSE otherwise
122 EAPI Eina_Bool elm_box_horizontal_get(const Evas_Object *obj);
125 * Set the box to arrange its children homogeneously
127 * If enabled, homogeneous layout makes all items the same size, according
128 * to the size of the largest of its children.
130 * @note This flag is ignored if a custom layout function is set.
132 * @param obj The box object
133 * @param homogeneous The homogeneous flag
137 EAPI void elm_box_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous);
140 * Get whether the box is using homogeneous mode or not
142 * @param obj The box object
143 * @return EINA_TRUE if it's homogeneous, EINA_FALSE otherwise
147 EAPI Eina_Bool elm_box_homogeneous_get(const Evas_Object *obj);
150 * Add an object to the beginning of the pack list
152 * Pack @p subobj into the box @p obj, placing it first in the list of
153 * children objects. The actual position the object will get on screen
154 * depends on the layout used. If no custom layout is set, it will be at
155 * the top or left, depending if the box is vertical or horizontal,
158 * @param obj The box object
159 * @param subobj The object to add to the box
161 * @see elm_box_pack_end()
162 * @see elm_box_pack_before()
163 * @see elm_box_pack_after()
164 * @see elm_box_unpack()
165 * @see elm_box_unpack_all()
166 * @see elm_box_clear()
170 EAPI void elm_box_pack_start(Evas_Object *obj, Evas_Object *subobj);
173 * Add an object at the end of the pack list
175 * Pack @p subobj into the box @p obj, placing it last in the list of
176 * children objects. The actual position the object will get on screen
177 * depends on the layout used. If no custom layout is set, it will be at
178 * the bottom or right, depending if the box is vertical or horizontal,
181 * @param obj The box object
182 * @param subobj The object to add to the box
184 * @see elm_box_pack_start()
185 * @see elm_box_pack_before()
186 * @see elm_box_pack_after()
187 * @see elm_box_unpack()
188 * @see elm_box_unpack_all()
189 * @see elm_box_clear()
193 EAPI void elm_box_pack_end(Evas_Object *obj, Evas_Object *subobj);
196 * Adds an object to the box before the indicated object
198 * This will add the @p subobj to the box indicated before the object
199 * indicated with @p before. If @p before is not already in the box, results
200 * are undefined. Before means either to the left of the indicated object or
201 * above it depending on orientation.
203 * @param obj The box object
204 * @param subobj The object to add to the box
205 * @param before The object before which to add it
207 * @see elm_box_pack_start()
208 * @see elm_box_pack_end()
209 * @see elm_box_pack_after()
210 * @see elm_box_unpack()
211 * @see elm_box_unpack_all()
212 * @see elm_box_clear()
216 EAPI void elm_box_pack_before(Evas_Object *obj, Evas_Object *subobj, Evas_Object *before);
219 * Adds an object to the box after the indicated object
221 * This will add the @p subobj to the box indicated after the object
222 * indicated with @p after. If @p after is not already in the box, results
223 * are undefined. After means either to the right of the indicated object or
224 * below it depending on orientation.
226 * @param obj The box object
227 * @param subobj The object to add to the box
228 * @param after The object after which to add it
230 * @see elm_box_pack_start()
231 * @see elm_box_pack_end()
232 * @see elm_box_pack_before()
233 * @see elm_box_unpack()
234 * @see elm_box_unpack_all()
235 * @see elm_box_clear()
239 EAPI void elm_box_pack_after(Evas_Object *obj, Evas_Object *subobj, Evas_Object *after);
242 * Clear the box of all children
244 * Remove all the elements contained by the box, deleting the respective
247 * @param obj The box object
249 * @see elm_box_unpack()
250 * @see elm_box_unpack_all()
254 EAPI void elm_box_clear(Evas_Object *obj);
259 * Remove the object given by @p subobj from the box @p obj without
262 * @param obj The box object
263 * @param subobj The object to unpack
265 * @see elm_box_unpack_all()
266 * @see elm_box_clear()
270 EAPI void elm_box_unpack(Evas_Object *obj, Evas_Object *subobj);
273 * Remove all items from the box, without deleting them
275 * Clear the box from all children, but don't delete the respective objects.
276 * If no other references of the box children exist, the objects will never
277 * be deleted, and thus the application will leak the memory. Make sure
278 * when using this function that you hold a reference to all the objects
281 * @param obj The box object
283 * @see elm_box_clear()
284 * @see elm_box_unpack()
288 EAPI void elm_box_unpack_all(Evas_Object *obj);
291 * Retrieve a list of the objects packed into the box
293 * Returns a new @c Eina_List with a pointer to @c Evas_Object in its nodes.
294 * The order of the list corresponds to the packing order the box uses.
296 * You must free this list with eina_list_free() once you are done with it.
298 * @param obj The box object
302 EAPI Eina_List *elm_box_children_get(const Evas_Object *obj);
305 * Set the space (padding) between the box's elements.
307 * Extra space in pixels that will be added between a box child and its
308 * neighbors after its containing cell has been calculated. This padding
309 * is set for all elements in the box, besides any possible padding that
310 * individual elements may have through their size hints.
312 * @param obj The box object
313 * @param horizontal The horizontal space between elements
314 * @param vertical The vertical space between elements
318 EAPI void elm_box_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical);
321 * Get the space (padding) between the box's elements.
323 * @param obj The box object
324 * @param horizontal The horizontal space between elements
325 * @param vertical The vertical space between elements
327 * @see elm_box_padding_set()
331 EAPI void elm_box_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical);
334 * Set the alignment of the whole bounding box of contents.
336 * Sets how the bounding box containing all the elements of the box, after
337 * their sizes and position has been calculated, will be aligned within
338 * the space given for the whole box widget.
340 * @param obj The box object
341 * @param horizontal The horizontal alignment of elements
342 * @param vertical The vertical alignment of elements
346 EAPI void elm_box_align_set(Evas_Object *obj, double horizontal, double vertical);
349 * Get the alignment of the whole bounding box of contents.
351 * @param obj The box object
352 * @param horizontal The horizontal alignment of elements
353 * @param vertical The vertical alignment of elements
355 * @see elm_box_align_set()
359 EAPI void elm_box_align_get(const Evas_Object *obj, double *horizontal, double *vertical);
362 * Force the box to recalculate its children packing.
364 * If any children was added or removed, box will not calculate the
365 * values immediately rather leaving it to the next main loop
366 * iteration. While this is great as it would save lots of
367 * recalculation, whenever you need to get the position of a just
368 * added item you must force recalculate before doing so.
370 * @param obj The box object.
374 EAPI void elm_box_recalculate(Evas_Object *obj);
377 * Set the layout defining function to be used by the box
379 * Whenever anything changes that requires the box in @p obj to recalculate
380 * the size and position of its elements, the function @p cb will be called
381 * to determine what the layout of the children will be.
383 * Once a custom function is set, everything about the children layout
384 * is defined by it. The flags set by elm_box_horizontal_set() and
385 * elm_box_homogeneous_set() no longer have any meaning, and the values
386 * given by elm_box_padding_set() and elm_box_align_set() are up to this
387 * layout function to decide if they are used and how. These last two
388 * will be found in the @c priv parameter, of type @c Evas_Object_Box_Data,
389 * passed to @p cb. The @c Evas_Object the function receives is not the
390 * Elementary widget, but the internal Evas Box it uses, so none of the
391 * functions described here can be used on it.
393 * Any of the layout functions in @c Evas can be used here, as well as the
394 * special elm_box_layout_transition().
396 * The final @p data argument received by @p cb is the same @p data passed
397 * here, and the @p free_data function will be called to free it
398 * whenever the box is destroyed or another layout function is set.
400 * Setting @p cb to NULL will revert back to the default layout function.
402 * @param obj The box object
403 * @param cb The callback function used for layout
404 * @param data Data that will be passed to layout function
405 * @param free_data Function called to free @p data
407 * @see elm_box_layout_transition()
411 EAPI void elm_box_layout_set(Evas_Object *obj, Evas_Object_Box_Layout cb, const void *data, Ecore_Cb free_data);
414 * Special layout function that animates the transition from one layout to another
416 * Normally, when switching the layout function for a box, this will be
417 * reflected immediately on screen on the next render, but it's also
418 * possible to do this through an animated transition.
420 * This is done by creating an ::Elm_Box_Transition and setting the box
421 * layout to this function.
425 * Elm_Box_Transition *t = elm_box_transition_new(1.0,
426 * evas_object_box_layout_vertical, // start
427 * NULL, // data for initial layout
428 * NULL, // free function for initial data
429 * evas_object_box_layout_horizontal, // end
430 * NULL, // data for final layout
431 * NULL, // free function for final data
432 * anim_end, // will be called when animation ends
433 * NULL); // data for anim_end function\
434 * elm_box_layout_set(box, elm_box_layout_transition, t,
435 * elm_box_transition_free);
438 * @note This function can only be used with elm_box_layout_set(). Calling
439 * it directly will not have the expected results.
441 * @see elm_box_transition_new
442 * @see elm_box_transition_free
443 * @see elm_box_layout_set
447 EAPI void elm_box_layout_transition(Evas_Object *obj, Evas_Object_Box_Data *priv, void *data);
450 * Create a new ::Elm_Box_Transition to animate the switch of layouts
452 * If you want to animate the change from one layout to another, you need
453 * to set the layout function of the box to elm_box_layout_transition(),
454 * passing as user data to it an instance of ::Elm_Box_Transition with the
455 * necessary information to perform this animation. The free function to
456 * set for the layout is elm_box_transition_free().
458 * The parameters to create an ::Elm_Box_Transition sum up to how long
459 * will it be, in seconds, a layout function to describe the initial point,
460 * another for the final position of the children and one function to be
461 * called when the whole animation ends. This last function is useful to
462 * set the definitive layout for the box, usually the same as the end
463 * layout for the animation, but could be used to start another transition.
465 * @param duration The duration of the transition in seconds
466 * @param start_layout The layout function that will be used to start the animation
467 * @param start_layout_data The data to be passed the @p start_layout function
468 * @param start_layout_free_data Function to free @p start_layout_data
469 * @param end_layout The layout function that will be used to end the animation
470 * @param end_layout_data Data param passed to @p end_layout
471 * @param end_layout_free_data The data to be passed the @p end_layout function
472 * @param end_layout_free_data Function to free @p end_layout_data
473 * @param transition_end_cb Callback function called when animation ends
474 * @param transition_end_data Data to be passed to @p transition_end_cb
475 * @return An instance of ::Elm_Box_Transition
477 * @see elm_box_transition_new
478 * @see elm_box_layout_transition
482 EAPI 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);
485 * Free a Elm_Box_Transition instance created with elm_box_transition_new().
487 * This function is mostly useful as the @c free_data parameter in
488 * elm_box_layout_set() when elm_box_layout_transition().
490 * @param data The Elm_Box_Transition instance to be freed.
492 * @see elm_box_transition_new
493 * @see elm_box_layout_transition
497 EAPI void elm_box_transition_free(void *data);