path: root/src/lib/evas/canvas/evas_box.eo

class Evas.Box (Evas.Smart_Clipped)
{
   legacy_prefix: evas_object_box;
   eo_prefix: evas_obj_box;
   data: Evas_Object_Box_Data;
   properties {
      align {
         set {
            /*@
            Set the alignment of the whole bounding box of contents, for a
            given box object.

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

            @note The default values for both alignments is @c 0.5.

            @see evas_object_box_align_get() */
         }
         get {
            /*@
            Get the alignment of the whole bounding box of contents, for a
            given box object.

            @see evas_object_box_align_set() for more information */
         }
         values {
            double horizontal; /*@ The horizontal alignment, in pixels */
            double vertical; /*@ the vertical alignment, in pixels */
         }
      }
      padding {
         set {
            /*@
            Set the (space) padding between cells set for a given box object.

            @note The default values for both padding components is @c 0.

            @see evas_object_box_padding_get() */
         }
         get {
            /*@
            Get the (space) padding between cells set for a given box object.

            @see evas_object_box_padding_set() */
         }
         values {
            Evas_Coord horizontal; /*@ The horizontal padding, in pixels */
            Evas_Coord vertical; /*@ the vertical padding, in pixels */
         }
      }
      layout {
         set {
            /*@
            Set a new layouting function to a given box object

            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()

            Refer to each of their documentation texts for details on them.

            @note A box layouting function will be triggered by the @c
            'calculate' smart callback of the box's smart class. */
         }
         values {
            Evas_Object_Box_Layout cb @nonull; /*@ The new layout function to set on @p o. */
            const void *data; /*@ Data pointer to be passed to @p cb. */
            Eina_Free_Cb free_data; /*@ Function to free @p data, if need be. */
         }
      }
   }
   methods {
      layout_horizontal {
         /*@
         Layout function which sets the box @a 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
         <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
         functions. The size hints of the elements in the box -- set by the
         <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
         -- also control the way this function works.

         \par Box's properties:
         @c align_h controls the horizontal alignment of the child objects
         relative to the containing box. When set to @c 0.0, children are
         aligned to the left. A value of @c 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 @c padding_h property of the box, is bigger than the
         their container's width, the children will be displayed out of the
         box's bounds. A negative value of @c align_h makes the box to
         @b 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 @c align_v and @c padding_v properties of the box
         @b don't contribute to its behaviour when this layout is chosen.

         \par Child element's properties:
         @c align_x does @b not influence the box's behavior. @c padding_l
         and @c padding_r sum up to the container's horizontal padding
         between elements. The child's @c padding_t, @c padding_b and
         @c align_y properties apply for padding/alignment relative to the
         overall height of the box. Finally, there is the @c weight_x
         property, which, if set to a non-zero value, tells the container
         that the child width is @b not pre-defined. If the container can't
         accommodate all its children, it sets the widths of the ones
         <b>with weights</b> 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 @c weight_x property,
         besides telling the element is resizable, gives a @b weight for the
         resizing process.  The parent box will try to distribute (or take
         off) widths accordingly to the @b normalized list of weights: most
         weighted children remain/get larger in this process than the least
         ones. @c weight_y does not influence the layout.

         If one desires that, besides having weights, child elements must be
         resized bounded to a minimum or maximum size, those size hints must
         be set, by the <c>evas_object_size_hint_{min,max}_set()</c>
         functions. */
         params {
              Evas_Object_Box_Data *priv;
              void *data;
         }
      }
      layout_vertical {
         /*@
         Layout function which sets the box @a o to a (basic) vertical box

         This function behaves analogously to
         evas_object_box_layout_horizontal(). The description of its
         behaviour can be derived from that function's documentation. */
         params {
              Evas_Object_Box_Data *priv;
              void *data;
         }
      }
      layout_homogeneous_max_size_horizontal {
         /*@
         Layout function which sets the box @a o to a <b>maximum size,
         homogeneous</b> horizontal box

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

         \par Box's properties:
         @c padding_h tells the box to draw empty spaces of that size, in
         pixels, between the child objects' cells. @c align_h controls the
         horizontal alignment of the child objects, relative to the
         containing box. When set to @c 0.0, children are aligned to the
         left. A value of @c 1.0 lets them aligned to the right
         border. Values in between align them proportionally. A negative
         value of @c align_h makes the box to @b 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
         @c align_v and @c padding_v properties of the box don't contribute to
         its behaviour when this layout is chosen.

         \par Child element's properties:
         @c padding_l and @c padding_r sum up to the required width of the
         child element. The @c align_x property tells the relative position
         of this overall child width in its allocated cell (@c 0.0 to
         extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
         @c 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 @c padding_t, @c padding_b and @c align_y
         properties apply for padding/alignment relative to the overall
         height of the box. A value of @c -1.0 to @c 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). */
         params {
              Evas_Object_Box_Data *priv;
              void *data;
         }

      }
      internal_remove {
         /*@ No description supplied by the EAPI. */
         return Evas_Object *;
         legacy null;
         params {
            @in Evas_Object *child;
         }
      }
      layout_flow_vertical {
         /*@
         Layout function which sets the box @a o to a @b 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. */
         params {
              Evas_Object_Box_Data *priv;
              void *data;
         }
      }
      internal_option_free {
         /*@ No description supplied by the EAPI. */
         legacy null;
         params {
            @in Evas_Object_Box_Option *opt;
         }
      }
      insert_after {
         /*@
         Insert a new @a child object <b>after another existing one</b>, in
         a given box object @a o.

         @return A box option bound to the recently added box item or @c
         NULL, on errors

         On success, the @c "child,added" smart event will take place.

         @note This function will fail if @p reference is not a member of @p
         o.

         @note The actual placing of the item relative to @p o's area will
         depend on the layout set to it.

         @note This call will trigger the box's
         _Evas_Object_Box_Api.insert_after smart function. */

         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child @nonull; /*@ A child Evas object to be made a member of @p o */
            @in const Evas_Object *reference @nonull; /*@ The child object to place this new one after */
         }
      }
      remove_all {
         /*@
         Remove @b all child objects from a box object, unparenting them
         again.

         @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

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

         return Eina_Bool;
         params {
            @in Eina_Bool clear; /*@ if true, it will delete just removed children. */
         }
      }
      iterator_new {
         /*@
         Get an iterator to walk the list of children of a given box object.

         @return An iterator on @p o's child objects, on success, or @c NULL,
         on errors

         @note Do @b not remove or delete objects while walking the list. */

         const;
         return Eina_Iterator * @warn_unused;
      }
      add_to {
         /*@
         Add a new box as a @b child of a given smart object.

         @return @c NULL on error, a pointer to a new box object on
         success.

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

         @see evas_object_box_add() */

         return Evas_Object * @warn_unused;
      }
      append {
         /*@
         Append a new @a child object to the given box object @a o.

         @return A box option bound to the recently added box item or @c
         NULL, on errors

         On success, the @c "child,added" smart event will take place.

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

         @note This call will trigger the box's _Evas_Object_Box_Api.append
         smart function. */

         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child @nonull; /*@ A child Evas object to be made a member of @p o */
         }
      }
      option_property_id_get {
         /*@
         Get the numerical identifier of the property of the child elements
         of the box @a o which have @a name as name string

         @return The numerical ID of the given property or @c -1, on
         errors.

         @note This call won't do anything for a canonical Evas box. Only
         users which have @b 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_id_get smart class function of the
         box, which is originally set to @c NULL. */

         const;
         return int @warn_unused;
         params {
            @in const char *name @nonull; /*@ The name string of the option being searched, for
            its ID */
         }
      }
      prepend {
         /*@
         Prepend a new @a child object to the given box object @a o.

         @return A box option bound to the recently added box item or @c
         NULL, on errors

         On success, the @c "child,added" smart event will take place.

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

         @note This call will trigger the box's
         _Evas_Object_Box_Api.prepend smart function. */

         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child @nonull; /*@ A child Evas object to be made a member of @p o */
         }
      }
      accessor_new {
         /*@
         Get an accessor (a structure providing random items access) to the
         list of children of a given box object.

         @return An accessor on @p o's child objects, on success, or @c NULL,
         on errors

         @note Do not remove or delete objects while walking the list. */

         const;
         return Eina_Accessor * @warn_unused;
      }
      internal_append {
         /*@ No description supplied by the EAPI. */
         legacy null;
         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child;
         }
      }
      option_property_vset {
         /*@
         Set a property value (by its given numerical identifier), on a
         given box child element -- by a variable argument list

         @return @c EINA_TRUE on success, @c 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. */

         return Eina_Bool;
         params {
            @in Evas_Object_Box_Option *opt @nonull; /*@ The box option structure bound to the child box element
            to set a property on */
            @in int property; /*@ The numerical ID of the given property */
            @in va_list *args; /*@ The variable argument list implementing the value to
            be set for this property. It @b must be of the same type the user has
            defined for it. */
         }
         legacy null;
      }
      internal_remove_at {
         /*@ No description supplied by the EAPI. */
         legacy null;
         return Evas_Object *;
         params {
            @in unsigned int pos;
         }
      }
      remove_at {
         /*@
         Remove an object, <b>bound to a given position</b> in a box object,
         unparenting it again.

         @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

         On removal, you'll get an unparented object again, just as it was
         before you inserted it in the box. The @c option_free() box smart
         callback will be called automatically for you and, also, the
         @c "child,removed" smart event will take place.

         @note This function will fail if the given position is invalid,
         given @p o's internal list of elements.

         @note This call will trigger the box's
         _Evas_Object_Box_Api.remove_at smart function. */

         return Eina_Bool;
         params {
            @in unsigned int pos; /*@ The numeric position (starting from @c 0) of the child
            object to be removed */
         }
      }
      option_property_vget {
         /*@
         Get a property's value (by its given numerical identifier), on a
         given box child element -- by a variable argument list

         @return @c EINA_TRUE on success, @c 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. */

         const;
         return Eina_Bool;
         params {
            @in Evas_Object_Box_Option *opt @nonull; /*@ The box option structure bound to the child box element
            to get a property from */
            @in int property; /*@ The numerical ID of the given property */
            @in va_list *args; /*@ The variable argument list with pointers to where to
            store the values of this property. They @b must point to variables
            of the same type the user has defined for them. */
         }
         legacy null;
      }
      internal_insert_at {
         /*@ No description supplied by the EAPI. */
         legacy null;
         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child;
            @in unsigned int pos;
         }
      }
      insert_before {
         /*@
         Insert a new @a child object <b>before another existing one</b>, in
         a given box object @a o.

         @return A box option bound to the recently added box item or @c
         NULL, on errors

         On success, the @c "child,added" smart event will take place.

         @note This function will fail if @p reference is not a member of @p
         o.

         @note The actual placing of the item relative to @p o's area will
         depend on the layout set to it.

         @note This call will trigger the box's
         _Evas_Object_Box_Api.insert_before smart function. */

         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child @nonull; /*@ A child Evas object to be made a member of @p o */
            @in const Evas_Object *reference @nonull; /*@ The child object to place this new one before */
         }
      }
      option_property_name_get {
         /*@
         Get the name of the property of the child elements of the box @a o
         which have @a id as identifier

         @return The name of the given property or @c NULL, on errors.

         @note This call won't do anything for a canonical Evas box. Only
         users which have @b 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_name_get smart class function of the
         box, which is originally set to @c NULL. */

         const;
         return const char * @warn_unused;
         params {
            @in int property; /*@ The numerical identifier of the option being searched,
            for its name */
         }
      }
      internal_insert_before {
         /*@ No description supplied by the EAPI. */
         legacy null;
         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child;
            @in const Evas_Object *reference;
         }
      }
      layout_homogeneous_horizontal {
         /*@
         Layout function which sets the box @a o to a @b homogeneous
         horizontal box

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

         \par Box's properties:
         @c align_h has no influence on the box for this layout.
         @c padding_h tells the box to draw empty spaces of that size, in
         pixels, between the (equal) child objects' cells. The @c align_v
         and @c padding_v properties of the box don't contribute to its
         behaviour when this layout is chosen.

         \par Child element's properties:
         @c padding_l and @c padding_r sum up to the required width of the
         child element. The @c align_x property tells the relative position
         of this overall child width in its allocated cell (@c 0.0 to
         extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
         @c 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 @c padding_t, @c padding_b and @c align_y
         properties apply for padding/alignment relative to the overall
         height of the box. A value of @c -1.0 to @c 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). */
         params {
            @in  Evas_Object_Box_Data *priv;
            @in  void *data;
         }
      }
      internal_option_new {
         /*@ No description supplied by the EAPI. */
         legacy null;
         return Evas_Object_Box_Option*;
         params {
            @in Evas_Object *child;
         }
      }
      layout_homogeneous_max_size_vertical {
         /*@
         Layout function which sets the box @a o to a <b>maximum size,
         homogeneous</b> vertical box

         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. */
         params {
            @in Evas_Object_Box_Data *priv;
            @in void *data;
         }
      }
      internal_insert_after {
         /*@ No description supplied by the EAPI. */
         legacy null;
         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child;
            @in const Evas_Object *reference;
         }
      }
      insert_at {
         /*@
         Insert a new @a child object <b>at a given position</b>, in a given
         box object @a o.

         @return A box option bound to the recently added box item or @c
         NULL, on errors

         On success, the @c "child,added" smart event will take place.

         @note This function will fail if the given position is invalid,
         given @p o's internal list of elements.

         @note The actual placing of the item relative to @p o's area will
         depend on the layout set to it.

         @note This call will trigger the box's
         _Evas_Object_Box_Api.insert_at smart function. */

         return Evas_Object_Box_Option *;
         params {
            @in Evas_Object *child @nonull; /*@ A child Evas object to be made a member of @p o */
            @in unsigned int pos; /*@ The numeric position (starting from @c 0) to place the
            new child object at */
         }
      }
      internal_prepend {
         /*@ No description supplied by the EAPI. */
         legacy null;
         return Evas_Object_Box_Option*;
         params {
            @in Evas_Object *child;
         }
      }
      remove {
         /*@
         Remove a given object from a box object, unparenting it again.

         @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

         On removal, you'll get an unparented object again, just as it was
         before you inserted it in the box. The
         _Evas_Object_Box_Api.option_free box smart callback will be called
         automatically for you and, also, the @c "child,removed" smart event
         will take place.

         @note This call will trigger the box's _Evas_Object_Box_Api.remove
         smart function. */

         return Eina_Bool;
         params {
            @in Evas_Object *child @nonull; /*@ The handle to the child object to be removed */
         }
      }
      layout_stack {
         /*@
         Layout function which sets the box @a o to a @b stacking box

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

         \par Box's properties:
         No box properties are used.

         \par Child element's properties:
         @c padding_l and @c padding_r sum up to the required width of the
         child element. The @c align_x property tells the relative position
         of this overall child width in its allocated cell (@c 0.0 to
         extreme left, @c 1.0 to extreme right). A value of @c -1.0 to @c
         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. */
         params {
            @in  Evas_Object_Box_Data *priv;
            @in  void *data;
         }
      }
      layout_homogeneous_vertical {
         /*@
         Layout function which sets the box @a o to a @b homogeneous
         vertical box

         This function behaves analogously to
         evas_object_box_layout_homogeneous_horizontal().  The description
         of its behaviour can be derived from that function's documentation. */
         params {
              Evas_Object_Box_Data *priv;
              void *data;
         }
      }
      layout_flow_horizontal {
         /*@
         Layout function which sets the box @a o to a @b flow horizontal
         box.

         In a flow horizontal box, the box's child elements are placed in
         @b 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
         <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
         functions.  The size hints of the elements in the box -- set by the
         <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
         -- also control the way this function works.

         \par Box's properties:
         @c padding_h tells the box to draw empty spaces of that size, in
         pixels, between the child objects' cells. @c align_h dictates the
         horizontal alignment of the rows (@c 0.0 to left align them, @c 1.0
         to right align). A value of @c -1.0 to @c align_h lets the rows
         @b justified horizontally. @c align_v controls the vertical alignment
         of the entire set of rows (@c 0.0 to top, @c 1.0 to bottom). A
         value of @c -1.0 to @c align_v makes the box to @b 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). @c padding_v has no
         influence on the layout.

         \par Child element's properties:
         @c padding_l and @c padding_r sum up to the required width of the
         child element. The @c align_x property has no influence on the
         layout. The child's @c padding_t and @c 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
         @c align_y dictates positioning relative to the <b>largest
         height</b> required by a child object in the actual row. */
         params {
              Evas_Object_Box_Data *priv;
              void *data;
         }

      }
   }
   implements {
      class.constructor;
      Eo.Base.constructor;
      Evas_Object.smart_data.get;
      Evas.Object_Smart.calculate;
      Evas.Object_Smart.add;
      Evas.Object_Smart.del;
      Evas.Object_Smart.resize;
   }
   events {
      child,added;
      child,removed;
   }

}