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>

perl v5.36.0                                       2024-01-02                       Tickit::ContainerWidget(3pm)