docs: Clarify Group's sizing semantics

The documentation for ClutterGroup behaviour when setting an explicit
size is not accurate - or, actually, it was accurate by the time
ClutterGroup was first written but has been neglected in the following
release cycles.

To avoid confusion for new users of Clutter the documentation should be
slightly expanded, mentioning the exact semantics of ClutterGroup with
regards to: preferred size, explicitly set size and how to constrain the
visible area of a ClutterGroup to an explicitly set size.

Based on a patch by: Neil Roberts <neil@linux.intel.com>
This commit is contained in:
Emmanuele Bassi 2010-02-02 14:50:03 +00:00
parent 12b004b0e7
commit c9a6e63fa4

View File

@ -25,15 +25,23 @@
/** /**
* SECTION:clutter-group * SECTION:clutter-group
* @short_description: Actor class containing multiple children. * @short_description: A fixed layout container
* actors.
* *
* A #ClutterGroup is an Actor which contains multiple child actors positioned * A #ClutterGroup is an Actor which contains multiple child actors positioned
* relative to the #ClutterGroup position. Other operations such as scaling, * relative to the #ClutterGroup position. Other operations such as scaling,
* rotating and clipping of the group will apply to the child actors. * rotating and clipping of the group will apply to the child actors.
* *
* A #ClutterGroup's size is defined by the size and position of its children. * A #ClutterGroup's size is defined by the size and position of its children;
* Resize requests via the #ClutterActor API will be ignored. * it will be the smallest non-negative size that covers the right and bottom
* edges of all of its children.
*
* Setting the size on a Group using #ClutterActor methods like
* clutter_actor_set_size() will override the natural size of the Group,
* however this will not affect the size of the children and they may still
* be painted outside of the allocation of the group. One way to constrain
* the visible area of a #ClutterGroup to a specified allocation is to
* explicitly set the size of the #ClutterGroup and then use the
* #ClutterActor:clip-to-allocation property.
*/ */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H