new

   $widget = Tickit::ContainerWidget->new( %args )

Constructs a new "Tickit::ContainerWidget" object. Must be called on a subclass that implements the required methods; see the SUBCLASS METHODS section below.

add

   $widget->add( $child, %opts )

Sets the child widget's parent, stores the options for the child, and calls the "children_changed" method. The concrete implementation will have to implement storage of this child widget.

Returns the container $widget itself, for easy chaining.

remove

   $widget->remove( $child_or_index )

Removes the child widget's parent, and calls the "children_changed" method. The concrete implementation will have to remove this child from its storage.

Returns the container $widget itself, for easy chaining.

child_opts

   %opts = $widget->child_opts( $child )

   $opts = $widget->child_opts( $child )

Returns the options currently set for the given child as a key/value list in list context, or as a HASH reference in scalar context. The HASH reference in scalar context is the actual hash used to store the options - modifications to it will be preserved.

set_child_opts

   $widget->set_child_opts( $child, %newopts )

Sets new options on the given child. Any options whose value is given as "undef" are deleted.

find_child

   $child = $widget->find_child( $how, $other, %args )

Returns a child widget. The $how argument determines how this is done, relative to the child widget given by $other:

first

The first child returned by "children" ($other is ignored)

last

The last child returned by "children" ($other is ignored)

before

The child widget just before $other in the order given by "children"

after

The child widget just after $other in the order given by "children"

Takes the following named arguments:

where => CODE

Optional. If defined, gives a filter function to filter the list of children before searching for the required one. Will be invoked once per child, with the child widget set as $_; it should return a boolean value to indicate if that child should be included in the search.

focus_next

   $widget->focus_next( $how, $other )

Moves the input focus to the next widget in the widget tree, by searching in the direction given by $how relative to the widget given by $other (which must be an immediate child of $widget).

The direction $how must be one of the following four values:

first

last

Moves focus to the first or last child widget that can take focus. Recurses into child widgets that are themselves containers. $other is ignored.

after

before

Moves focus to the next or previous child widget in tree order from the one given by $other. Recurses into child widgets that are themselves containers, and out into parent containers.

These searches will wrap around the widget tree; moving "after" the last node in the widget tree will move to the first, and vice versa.

This differs from "find_child" in that it performs a full tree search through the widget tree, considering parents and children. If a "before" or "after" search falls off the end of one node, it will recurse up to its parent and search within the next child, and so on.

Usually this would be used via the widget itself:

 $self->parent->focus_next( $how => $self );

children

   @children = $widget->children

Required. Should return a list of all the contained child widgets. The order is not specified, but should be in some stable order that makes sense given the layout of the widget's children.

This method is used by "window_lost" to remove the windows from all the child widgets automatically, and by "find_child" to obtain a child relative to another given one.

children_for_focus

   @children = $widget->children_for_focus

Optional. If implemented, this method is called to obtain a list of child widgets to perform a child search on when changing focus using the "focus_next" method. If it is not implemented, the regular "children" method is called instead.

Normally this method shouldn't be used, but it may be useful on container widgets that also display "helper" widgets that should not be considered as part of the main focus set. This method can then exclude them.

children_changed

   $widget->children_changed

Optional. If implemented, this method will be called after any change of the contained child widgets or their options. Typically this will be used to set windows on them by sub-dividing the window of the parent.

If not overridden, the base implementation will call "reshape".

child_resized

   $widget->child_resized( $child )

Optional. If implemented, this method will be called after a child widget changes or may have changed its size requirements. Typically this will be used to adjusts the windows allocated to children.

If not overridden, the base implementation will call "reshape".