oracular (3) Tickit::ContainerWidget.3pm.gz

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>