NAME

Tickit::ContainerWidget - abstract base class for widgets that contain other widgets

SYNOPSIS

 TODO

DESCRIPTION

This class acts as an abstract base class for widgets that contain at leaast one other widget object. It provides storage for a hash of "options" associated with each child widget.

STYLE

The following style tags are used:

:focus-child: Set whenever a child widget within the container has the input focus.

CONSTRUCTOR

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.

METHODS

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

SUBCLASS METHODS

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.