src/lib/elm_box.h

   1 /**
   2  * @defgroup Box Box
   3  *
   4  * @image html img/widget/box/preview-00.png
   5  * @image latex img/widget/box/preview-00.eps width=\textwidth
   6  *
   7  * @image html img/box.png
   8  * @image latex img/box.eps width=\textwidth
   9  *
  10  * A box arranges objects in a linear fashion, governed by a layout function
  11  * that defines the details of this arrangement.
  12  *
  13  * By default, the box will use an internal function to set the layout to
  14  * a single row, either vertical or horizontal. This layout is affected
  15  * by a number of parameters, such as the homogeneous flag set by
  16  * elm_box_homogeneous_set(), the values given by elm_box_padding_set() and
  17  * elm_box_align_set() and the hints set to each object in the box.
  18  *
  19  * For this default layout, it's possible to change the orientation with
  20  * elm_box_horizontal_set(). The box will start in the vertical orientation,
  21  * placing its elements ordered from top to bottom. When horizontal is set,
  22  * the order will go from left to right. If the box is set to be
  23  * homogeneous, every object in it will be assigned the same space, that
  24  * of the largest object. Padding can be used to set some spacing between
  25  * the cell given to each object. The alignment of the box, set with
  26  * elm_box_align_set(), determines how the bounding box of all the elements
  27  * will be placed within the space given to the box widget itself.
  28  *
  29  * The size hints of each object also affect how they are placed and sized
  30  * within the box. evas_object_size_hint_min_set() will give the minimum
  31  * size the object can have, and the box will use it as the basis for all
  32  * latter calculations. Elementary widgets set their own minimum size as
  33  * needed, so there's rarely any need to use it manually.
  34  *
  35  * evas_object_size_hint_weight_set(), when not in homogeneous mode, is
  36  * used to tell whether the object will be allocated the minimum size it
  37  * needs or if the space given to it should be expanded. It's important
  38  * to realize that expanding the size given to the object is not the same
  39  * thing as resizing the object. It could very well end being a small
  40  * widget floating in a much larger empty space. If not set, the weight
  41  * for objects will normally be 0.0 for both axis, meaning the widget will
  42  * not be expanded. To take as much space possible, set the weight to
  43  * EVAS_HINT_EXPAND (defined to 1.0) for the desired axis to expand.
  44  *
  45  * Besides how much space each object is allocated, it's possible to control
  46  * how the widget will be placed within that space using
  47  * evas_object_size_hint_align_set(). By default, this value will be 0.5
  48  * for both axis, meaning the object will be centered, but any value from
  49  * 0.0 (left or top, for the @c x and @c y axis, respectively) to 1.0
  50  * (right or bottom) can be used. The special value EVAS_HINT_FILL, which
  51  * is -1.0, means the object will be resized to fill the entire space it
  52  * was allocated.
  53  *
  54  * In addition, customized functions to define the layout can be set, which
  55  * allow the application developer to organize the objects within the box
  56  * in any number of ways.
  57  *
  58  * The special elm_box_layout_transition() function can be used
  59  * to switch from one layout to another, animating the motion of the
  60  * children of the box.
  61  *
  62  * @note Objects should not be added to box objects using _add() calls.
  63  *
  64  * Some examples on how to use boxes follow:
  65  * @li @ref box_example_01
  66  * @li @ref box_example_02
  67  *
  68  * @{
  69  */
  70 /**
  71  * @typedef Elm_Box_Transition
  72  *
  73  * Opaque handler containing the parameters to perform an animated
  74  * transition of the layout the box uses.
  75  *
  76  * @see elm_box_transition_new()
  77  * @see elm_box_layout_set()
  78  * @see elm_box_layout_transition()
  79  */
  80 typedef struct _Elm_Box_Transition Elm_Box_Transition;
  81
  82 /**
  83  * Add a new box to the parent
  84  *
  85  * By default, the box will be in vertical mode and non-homogeneous.
  86  *
  87  * @param parent The parent object
  88  * @return The new object or NULL if it cannot be created
  89  */
  90 EAPI Evas_Object *
  91                          elm_box_add(Evas_Object *parent)
  92 EINA_ARG_NONNULL(1);
  93
  94 /**
  95  * Set the horizontal orientation
  96  *
  97  * By default, box object arranges their contents vertically from top to
  98  * bottom.
  99  * By calling this function with @p horizontal as EINA_TRUE, the box will
 100  * become horizontal, arranging contents from left to right.
 101  *
 102  * @note This flag is ignored if a custom layout function is set.
 103  *
 104  * @param obj The box object
 105  * @param horizontal The horizontal flag (EINA_TRUE = horizontal,
 106  * EINA_FALSE = vertical)
 107  */
 108 EAPI void                elm_box_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
 109
 110 /**
 111  * Get the horizontal orientation
 112  *
 113  * @param obj The box object
 114  * @return EINA_TRUE if the box is set to horizontal mode, EINA_FALSE otherwise
 115  */
 116 EAPI Eina_Bool           elm_box_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 117
 118 /**
 119  * Set the box to arrange its children homogeneously
 120  *
 121  * If enabled, homogeneous layout makes all items the same size, according
 122  * to the size of the largest of its children.
 123  *
 124  * @note This flag is ignored if a custom layout function is set.
 125  *
 126  * @param obj The box object
 127  * @param homogeneous The homogeneous flag
 128  */
 129 EAPI void                elm_box_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
 130
 131 /**
 132  * Get whether the box is using homogeneous mode or not
 133  *
 134  * @param obj The box object
 135  * @return EINA_TRUE if it's homogeneous, EINA_FALSE otherwise
 136  */
 137 EAPI Eina_Bool           elm_box_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 138
 139 /**
 140  * Add an object to the beginning of the pack list
 141  *
 142  * Pack @p subobj into the box @p obj, placing it first in the list of
 143  * children objects. The actual position the object will get on screen
 144  * depends on the layout used. If no custom layout is set, it will be at
 145  * the top or left, depending if the box is vertical or horizontal,
 146  * respectively.
 147  *
 148  * @param obj The box object
 149  * @param subobj The object to add to the box
 150  *
 151  * @see elm_box_pack_end()
 152  * @see elm_box_pack_before()
 153  * @see elm_box_pack_after()
 154  * @see elm_box_unpack()
 155  * @see elm_box_unpack_all()
 156  * @see elm_box_clear()
 157  */
 158 EAPI void                elm_box_pack_start(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
 159
 160 /**
 161  * Add an object at the end of the pack list
 162  *
 163  * Pack @p subobj into the box @p obj, placing it last in the list of
 164  * children objects. The actual position the object will get on screen
 165  * depends on the layout used. If no custom layout is set, it will be at
 166  * the bottom or right, depending if the box is vertical or horizontal,
 167  * respectively.
 168  *
 169  * @param obj The box object
 170  * @param subobj The object to add to the box
 171  *
 172  * @see elm_box_pack_start()
 173  * @see elm_box_pack_before()
 174  * @see elm_box_pack_after()
 175  * @see elm_box_unpack()
 176  * @see elm_box_unpack_all()
 177  * @see elm_box_clear()
 178  */
 179 EAPI void                elm_box_pack_end(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
 180
 181 /**
 182  * Adds an object to the box before the indicated object
 183  *
 184  * This will add the @p subobj to the box indicated before the object
 185  * indicated with @p before. If @p before is not already in the box, results
 186  * are undefined. Before means either to the left of the indicated object or
 187  * above it depending on orientation.
 188  *
 189  * @param obj The box object
 190  * @param subobj The object to add to the box
 191  * @param before The object before which to add it
 192  *
 193  * @see elm_box_pack_start()
 194  * @see elm_box_pack_end()
 195  * @see elm_box_pack_after()
 196  * @see elm_box_unpack()
 197  * @see elm_box_unpack_all()
 198  * @see elm_box_clear()
 199  */
 200 EAPI void                elm_box_pack_before(Evas_Object *obj, Evas_Object *subobj, Evas_Object *before) EINA_ARG_NONNULL(1);
 201
 202 /**
 203  * Adds an object to the box after the indicated object
 204  *
 205  * This will add the @p subobj to the box indicated after the object
 206  * indicated with @p after. If @p after is not already in the box, results
 207  * are undefined. After means either to the right of the indicated object or
 208  * below it depending on orientation.
 209  *
 210  * @param obj The box object
 211  * @param subobj The object to add to the box
 212  * @param after The object after which to add it
 213  *
 214  * @see elm_box_pack_start()
 215  * @see elm_box_pack_end()
 216  * @see elm_box_pack_before()
 217  * @see elm_box_unpack()
 218  * @see elm_box_unpack_all()
 219  * @see elm_box_clear()
 220  */
 221 EAPI void                elm_box_pack_after(Evas_Object *obj, Evas_Object *subobj, Evas_Object *after) EINA_ARG_NONNULL(1);
 222
 223 /**
 224  * Clear the box of all children
 225  *
 226  * Remove all the elements contained by the box, deleting the respective
 227  * objects.
 228  *
 229  * @param obj The box object
 230  *
 231  * @see elm_box_unpack()
 232  * @see elm_box_unpack_all()
 233  */
 234 EAPI void                elm_box_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
 235
 236 /**
 237  * Unpack a box item
 238  *
 239  * Remove the object given by @p subobj from the box @p obj without
 240  * deleting it.
 241  *
 242  * @param obj The box object
 243  * @param subobj The object to unpack
 244  *
 245  * @see elm_box_unpack_all()
 246  * @see elm_box_clear()
 247  */
 248 EAPI void                elm_box_unpack(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
 249
 250 /**
 251  * Remove all items from the box, without deleting them
 252  *
 253  * Clear the box from all children, but don't delete the respective objects.
 254  * If no other references of the box children exist, the objects will never
 255  * be deleted, and thus the application will leak the memory. Make sure
 256  * when using this function that you hold a reference to all the objects
 257  * in the box @p obj.
 258  *
 259  * @param obj The box object
 260  *
 261  * @see elm_box_clear()
 262  * @see elm_box_unpack()
 263  */
 264 EAPI void                elm_box_unpack_all(Evas_Object *obj) EINA_ARG_NONNULL(1);
 265
 266 /**
 267  * Retrieve a list of the objects packed into the box
 268  *
 269  * Returns a new @c Eina_List with a pointer to @c Evas_Object in its nodes.
 270  * The order of the list corresponds to the packing order the box uses.
 271  *
 272  * You must free this list with eina_list_free() once you are done with it.
 273  *
 274  * @param obj The box object
 275  */
 276 EAPI const Eina_List    *elm_box_children_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 277
 278 /**
 279  * Set the space (padding) between the box's elements.
 280  *
 281  * Extra space in pixels that will be added between a box child and its
 282  * neighbors after its containing cell has been calculated. This padding
 283  * is set for all elements in the box, besides any possible padding that
 284  * individual elements may have through their size hints.
 285  *
 286  * @param obj The box object
 287  * @param horizontal The horizontal space between elements
 288  * @param vertical The vertical space between elements
 289  */
 290 EAPI void                elm_box_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
 291
 292 /**
 293  * Get the space (padding) between the box's elements.
 294  *
 295  * @param obj The box object
 296  * @param horizontal The horizontal space between elements
 297  * @param vertical The vertical space between elements
 298  *
 299  * @see elm_box_padding_set()
 300  */
 301 EAPI void                elm_box_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
 302
 303 /**
 304  * Set the alignment of the whole bouding box of contents.
 305  *
 306  * Sets how the bounding box containing all the elements of the box, after
 307  * their sizes and position has been calculated, will be aligned within
 308  * the space given for the whole box widget.
 309  *
 310  * @param obj The box object
 311  * @param horizontal The horizontal alignment of elements
 312  * @param vertical The vertical alignment of elements
 313  */
 314 EAPI void                elm_box_align_set(Evas_Object *obj, double horizontal, double vertical) EINA_ARG_NONNULL(1);
 315
 316 /**
 317  * Get the alignment of the whole bouding box of contents.
 318  *
 319  * @param obj The box object
 320  * @param horizontal The horizontal alignment of elements
 321  * @param vertical The vertical alignment of elements
 322  *
 323  * @see elm_box_align_set()
 324  */
 325 EAPI void                elm_box_align_get(const Evas_Object *obj, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
 326
 327 /**
 328  * Force the box to recalculate its children packing.
 329  *
 330  * If any children was added or removed, box will not calculate the
 331  * values immediately rather leaving it to the next main loop
 332  * iteration. While this is great as it would save lots of
 333  * recalculation, whenever you need to get the position of a just
 334  * added item you must force recalculate before doing so.
 335  *
 336  * @param obj The box object.
 337  */
 338 EAPI void                elm_box_recalculate(Evas_Object *obj);
 339
 340 /**
 341  * Set the layout defining function to be used by the box
 342  *
 343  * Whenever anything changes that requires the box in @p obj to recalculate
 344  * the size and position of its elements, the function @p cb will be called
 345  * to determine what the layout of the children will be.
 346  *
 347  * Once a custom function is set, everything about the children layout
 348  * is defined by it. The flags set by elm_box_horizontal_set() and
 349  * elm_box_homogeneous_set() no longer have any meaning, and the values
 350  * given by elm_box_padding_set() and elm_box_align_set() are up to this
 351  * layout function to decide if they are used and how. These last two
 352  * will be found in the @c priv parameter, of type @c Evas_Object_Box_Data,
 353  * passed to @p cb. The @c Evas_Object the function receives is not the
 354  * Elementary widget, but the internal Evas Box it uses, so none of the
 355  * functions described here can be used on it.
 356  *
 357  * Any of the layout functions in @c Evas can be used here, as well as the
 358  * special elm_box_layout_transition().
 359  *
 360  * The final @p data argument received by @p cb is the same @p data passed
 361  * here, and the @p free_data function will be called to free it
 362  * whenever the box is destroyed or another layout function is set.
 363  *
 364  * Setting @p cb to NULL will revert back to the default layout function.
 365  *
 366  * @param obj The box object
 367  * @param cb The callback function used for layout
 368  * @param data Data that will be passed to layout function
 369  * @param free_data Function called to free @p data
 370  *
 371  * @see elm_box_layout_transition()
 372  */
 373 EAPI void                elm_box_layout_set(Evas_Object *obj, Evas_Object_Box_Layout cb, const void *data, void (*free_data)(void *data)) EINA_ARG_NONNULL(1);
 374
 375 /**
 376  * Special layout function that animates the transition from one layout to another
 377  *
 378  * Normally, when switching the layout function for a box, this will be
 379  * reflected immediately on screen on the next render, but it's also
 380  * possible to do this through an animated transition.
 381  *
 382  * This is done by creating an ::Elm_Box_Transition and setting the box
 383  * layout to this function.
 384  *
 385  * For example:
 386  * @code
 387  * Elm_Box_Transition *t = elm_box_transition_new(1.0,
 388  *                            evas_object_box_layout_vertical, // start
 389  *                            NULL, // data for initial layout
 390  *                            NULL, // free function for initial data
 391  *                            evas_object_box_layout_horizontal, // end
 392  *                            NULL, // data for final layout
 393  *                            NULL, // free function for final data
 394  *                            anim_end, // will be called when animation ends
 395  *                            NULL); // data for anim_end function\
 396  * elm_box_layout_set(box, elm_box_layout_transition, t,
 397  *                    elm_box_transition_free);
 398  * @endcode
 399  *
 400  * @note This function can only be used with elm_box_layout_set(). Calling
 401  * it directly will not have the expected results.
 402  *
 403  * @see elm_box_transition_new
 404  * @see elm_box_transition_free
 405  * @see elm_box_layout_set
 406  */
 407 EAPI void                elm_box_layout_transition(Evas_Object *obj, Evas_Object_Box_Data *priv, void *data);
 408
 409 /**
 410  * Create a new ::Elm_Box_Transition to animate the switch of layouts
 411  *
 412  * If you want to animate the change from one layout to another, you need
 413  * to set the layout function of the box to elm_box_layout_transition(),
 414  * passing as user data to it an instance of ::Elm_Box_Transition with the
 415  * necessary information to perform this animation. The free function to
 416  * set for the layout is elm_box_transition_free().
 417  *
 418  * The parameters to create an ::Elm_Box_Transition sum up to how long
 419  * will it be, in seconds, a layout function to describe the initial point,
 420  * another for the final position of the children and one function to be
 421  * called when the whole animation ends. This last function is useful to
 422  * set the definitive layout for the box, usually the same as the end
 423  * layout for the animation, but could be used to start another transition.
 424  *
 425  * @param duration The duration of the transition in seconds
 426  * @param start_layout The layout function that will be used to start the animation
 427  * @param start_layout_data The data to be passed the @p start_layout function
 428  * @param start_layout_free_data Function to free @p start_layout_data
 429  * @param end_layout The layout function that will be used to end the animation
 430  * @param end_layout_data Data param passed to @p end_layout
 431  * @param end_layout_free_data The data to be passed the @p end_layout function
 432  * @param end_layout_free_data Function to free @p end_layout_data
 433  * @param transition_end_cb Callback function called when animation ends
 434  * @param transition_end_data Data to be passed to @p transition_end_cb
 435  * @return An instance of ::Elm_Box_Transition
 436  *
 437  * @see elm_box_transition_new
 438  * @see elm_box_layout_transition
 439  */
 440 EAPI Elm_Box_Transition *elm_box_transition_new(const double duration, Evas_Object_Box_Layout start_layout, void *start_layout_data, void (*start_layout_free_data)(void *data), Evas_Object_Box_Layout end_layout, void *end_layout_data, void (*end_layout_free_data)(void *data), void (*transition_end_cb)(void *data), void *transition_end_data) EINA_ARG_NONNULL(2, 5);
 441
 442 /**
 443  * Free a Elm_Box_Transition instance created with elm_box_transition_new().
 444  *
 445  * This function is mostly useful as the @c free_data parameter in
 446  * elm_box_layout_set() when elm_box_layout_transition().
 447  *
 448  * @param data The Elm_Box_Transition instance to be freed.
 449  *
 450  * @see elm_box_transition_new
 451  * @see elm_box_layout_transition
 452  */
 453 EAPI void                elm_box_transition_free(void *data);
 454
 455 /**
 456  * @}
 457  */