NAME

       dtk_create_composite_shape - Create or modify a shape holding other shapes

SYNOPSIS

       #include <drawtk.h>

       dtk_hshape dtk_create_composite_shape(dtk_hshape shp,
                                             unsigned int num,
                                             const dtk_hshape *list,
                                             int free_children);

DESCRIPTION

       dtk_create_composite_shape() creates a shape made of num different shapes specified by the
       array list. When dtk_draw_shape(3) is called on the composite shape, all referenced shapes
       will  be  rendered  in  the  order of list. The composite shape create its own copy of the
       shape list, so there is no need to keep the array pointed  by  list  allocated  after  the
       function returns.

       If  free_children is a non-zero value, the destruction of the composite shape will destroy
       the underlaying shapes. If free_children is zero,  destroying  the  composite  shape  will
       leave  the  referenced  shapes untouched, so that dtk_destroy_shape() should be called for
       all individual shapes.

       shp can be used to modify a previously created shape. If it is non-null, the  handle  will
       be  used  to  modify the shape referenced by shp: no new shape is created and the returned
       value is ensured to be shp in case of  success,  NULL  otherwise.  If  shp  is  NULL,  the
       function will attempt to create a new shape.

RETURN VALUE

       In case of success the function returns the handle to the newly created or modified shape.
       If the shp argument is non-null, the handle returned is the same value. In case of  error,
       NULL is returned.

SEE ALSO

       dtk_destroy_shape(3), dtk_create_shape(3)