Implementing Container Actors

You can create container actors that arrange child actors by implementing the Clutter::Container interface in your actor. This is done by using multiple inheritance to specify that the type is derived from Clutter::Actor and also implements the Clutter::Container interface. For instance:

class ExampleContainer : public Clutter::Actor, public Clutter::Container
{
  ExampleContainer();
  // ...
};

ExampleContainer::ExampleContainer()
:
  // Create a named GObject type for the custom container class
  Glib::ObjectBase(typeid(ExampleContainer))
{}

Clutter::Actor virtual functions to implement

If your container should control the position or size of its children then it should implement the Clutter::Actor's allocate_vfunc(), get_preferred_width_vfunc() and get_preferred_height_vfunc() virtual methods.

For instance, your allocate_vfunc() implementation should use the provided allocation to layout its child actors, by calling Clutter::Actor::allocate() on each child actor with appropriate allocations.

Your get_preferred_width_vfunc() and get_preferred_height_vfunc() implementations should return the size desired by your container, by providing both the minimum and natural size as output parameters. Depending on your container, this might be dependent on the child actors. By calling Clutter::Actor::get_preferred_size() you can discover the preferred height and width of a child actor.

Your actor should implement one of two geometry management modes -- either height for width (Clutter::REQUEST_HEIGHT_FOR_WIDTH) or width for height Clutter::REQUEST_WIDTH_FOR_HEIGHT) and should set its property_request_mode() property to indicate which one it uses. For instance, in height-for-width mode, the parent actor first asks for the preferred height and then asks for a preferred width appropriate for that height. Clutter::Actor::get_preferred_size() checks this property and then calls either Clutter::Actor::get_preferred_width() or Clutter::Actor::get_preferred_height() in the correct sequence.

You should implement the on_paint() method, usually calling Clutter::Actor::paint() on the child actors. All containers should also implement the pick_vfunc() method, calling Clutter::Actor::pick() on each child actor.

See the Custom Actor section for more details these virtual methods.

Clutter::Container virtual methods to implement

Your container implementation should also implement some of the Clutter::Container virtual methods so that the container's children will be affected appropriately when methods are called on the container.

For instance, your add_vfunc() and remove_vfunc() implementions should manage your container's internal list of child actors and might need to trigger repositioning or resizing of the child actors by calling Clutter::Actor::queue_relayout().

Your foreach_vfunc() implementation would simply call the provided callback on your container's list of child actors. Note that your container could actually contain additional actors that are not considered to be child actors for the purposes of add_vfunc(), remove_vfunc() and foreach_vfunc().