.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Tickit::ContainerWidget 3pm" .TH Tickit::ContainerWidget 3pm "2018-07-30" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Tickit::ContainerWidget" \- abstract base class for widgets that contain other widgets .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& TODO .Ve .SH "DESCRIPTION" .IX Header "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 \*(L"options\*(R" associated with each child widget. .SH "STYLE" .IX Header "STYLE" The following style tags are used: .IP ":focus\-child" 4 .IX Item ":focus-child" Set whenever a child widget within the container has the input focus. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" .Vb 1 \& $widget = Tickit::ContainerWidget\->new( %args ) .Ve .PP Constructs a new \f(CW\*(C`Tickit::ContainerWidget\*(C'\fR object. Must be called on a subclass that implements the required methods; see the \fB\s-1SUBCLASS METHODS\s0\fR section below. .SH "METHODS" .IX Header "METHODS" .SS "add" .IX Subsection "add" .Vb 1 \& $widget\->add( $child, %opts ) .Ve .PP Sets the child widget's parent, stores the options for the child, and calls the \f(CW\*(C`children_changed\*(C'\fR method. The concrete implementation will have to implement storage of this child widget. .PP Returns the container \f(CW$widget\fR itself, for easy chaining. .SS "remove" .IX Subsection "remove" .Vb 1 \& $widget\->remove( $child_or_index ) .Ve .PP Removes the child widget's parent, and calls the \f(CW\*(C`children_changed\*(C'\fR method. The concrete implementation will have to remove this child from its storage. .PP Returns the container \f(CW$widget\fR itself, for easy chaining. .SS "child_opts" .IX Subsection "child_opts" .Vb 1 \& %opts = $widget\->child_opts( $child ) \& \& $opts = $widget\->child_opts( $child ) .Ve .PP Returns the options currently set for the given child as a key/value list in list context, or as a \s-1HASH\s0 reference in scalar context. The \s-1HASH\s0 reference in scalar context is the actual hash used to store the options \- modifications to it will be preserved. .SS "set_child_opts" .IX Subsection "set_child_opts" .Vb 1 \& $widget\->set_child_opts( $child, %newopts ) .Ve .PP Sets new options on the given child. Any options whose value is given as \&\f(CW\*(C`undef\*(C'\fR are deleted. .SS "find_child" .IX Subsection "find_child" .Vb 1 \& $child = $widget\->find_child( $how, $other, %args ) .Ve .PP Returns a child widget. The \f(CW$how\fR argument determines how this is done, relative to the child widget given by \f(CW$other\fR: .IP "first" 4 .IX Item "first" The first child returned by \f(CW\*(C`children\*(C'\fR (\f(CW$other\fR is ignored) .IP "last" 4 .IX Item "last" The last child returned by \f(CW\*(C`children\*(C'\fR (\f(CW$other\fR is ignored) .IP "before" 4 .IX Item "before" The child widget just before \f(CW$other\fR in the order given by \f(CW\*(C`children\*(C'\fR .IP "after" 4 .IX Item "after" The child widget just after \f(CW$other\fR in the order given by \f(CW\*(C`children\*(C'\fR .PP Takes the following named arguments: .IP "where => \s-1CODE\s0" 8 .IX Item "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 \f(CW$_\fR; it should return a boolean value to indicate if that child should be included in the search. .SS "focus_next" .IX Subsection "focus_next" .Vb 1 \& $widget\->focus_next( $how, $other ) .Ve .PP Moves the input focus to the next widget in the widget tree, by searching in the direction given by \f(CW$how\fR relative to the widget given by \f(CW$other\fR (which must be an immediate child of \f(CW$widget\fR). .PP The direction \f(CW$how\fR must be one of the following four values: .IP "first" 4 .IX Item "first" .PD 0 .IP "last" 4 .IX Item "last" .PD Moves focus to the first or last child widget that can take focus. Recurses into child widgets that are themselves containers. \f(CW$other\fR is ignored. .IP "after" 4 .IX Item "after" .PD 0 .IP "before" 4 .IX Item "before" .PD Moves focus to the next or previous child widget in tree order from the one given by \f(CW$other\fR. Recurses into child widgets that are themselves containers, and out into parent containers. .Sp These searches will wrap around the widget tree; moving \f(CW\*(C`after\*(C'\fR the last node in the widget tree will move to the first, and vice versa. .PP This differs from \f(CW\*(C`find_child\*(C'\fR in that it performs a full tree search through the widget tree, considering parents and children. If a \f(CW\*(C`before\*(C'\fR or \f(CW\*(C`after\*(C'\fR search falls off the end of one node, it will recurse up to its parent and search within the next child, and so on. .PP Usually this would be used via the widget itself: .PP .Vb 1 \& $self\->parent\->focus_next( $how => $self ); .Ve .SH "SUBCLASS METHODS" .IX Header "SUBCLASS METHODS" .SS "children" .IX Subsection "children" .Vb 1 \& @children = $widget\->children .Ve .PP 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. .PP This method is used by \f(CW\*(C`window_lost\*(C'\fR to remove the windows from all the child widgets automatically, and by \f(CW\*(C`find_child\*(C'\fR to obtain a child relative to another given one. .SS "children_for_focus" .IX Subsection "children_for_focus" .Vb 1 \& @children = $widget\->children_for_focus .Ve .PP 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 \&\f(CW\*(C`focus_next\*(C'\fR method. If it is not implemented, the regular \f(CW\*(C`children\*(C'\fR method is called instead. .PP Normally this method shouldn't be used, but it may be useful on container widgets that also display \*(L"helper\*(R" widgets that should not be considered as part of the main focus set. This method can then exclude them. .SS "children_changed" .IX Subsection "children_changed" .Vb 1 \& $widget\->children_changed .Ve .PP 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. .PP If not overridden, the base implementation will call \f(CW\*(C`reshape\*(C'\fR. .SS "child_resized" .IX Subsection "child_resized" .Vb 1 \& $widget\->child_resized( $child ) .Ve .PP 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. .PP If not overridden, the base implementation will call \f(CW\*(C`reshape\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans