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.

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

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>