src/lib/elm_box.h

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