.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Curses::UI::Container 3"
.TH Curses::UI::Container 3 "2011-09-01" "perl v5.16.3" "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"
Curses::UI::Container \- Create and manipulate container widgets
.SH "CLASS HIERARCHY"
.IX Header "CLASS HIERARCHY"
.Vb 3
\& Curses::UI::Widget
\&    |
\&    +\-\-\-\-Curses::UI::Container
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Curses::UI;
\&    my $cui = new Curses::UI;
\&    my $win = $cui\->add(\*(Aqwindow_id\*(Aq, \*(AqWindow\*(Aq);
\&
\&    my $container = $win\->add(
\&        \*(Aqmycontainer\*(Aq, \*(AqContainer\*(Aq
\&    );
\&
\&    $container\->add(
\&        \*(Aqcontained\*(Aq, \*(AqSomeWidget\*(Aq,
\&        .....
\&    );
\&
\&    $container\->focus();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A container provides an easy way of managing multiple widgets
in a single \*(L"form\*(R". A lot of Curses::UI functionality is
built around containers. The main class Curses::UI 
itself is a container. A Curses::UI::Window
is a container. Some of the widgets are implemented as 
containers.
.SH "STANDARD OPTIONS"
.IX Header "STANDARD OPTIONS"
\&\fB\-parent\fR, \fB\-x\fR, \fB\-y\fR, \fB\-width\fR, \fB\-height\fR, 
\&\fB\-pad\fR, \fB\-padleft\fR, \fB\-padright\fR, \fB\-padtop\fR, \fB\-padbottom\fR,
\&\fB\-ipad\fR, \fB\-ipadleft\fR, \fB\-ipadright\fR, \fB\-ipadtop\fR, \fB\-ipadbottom\fR,
\&\fB\-title\fR, \fB\-titlefullwidth\fR, \fB\-titlereverse\fR, \fB\-onfocus\fR,
\&\fB\-onblur\fR
.PP
For an explanation of these standard options, see 
Curses::UI::Widget.
.SH "WIDGET-SPECIFIC OPTIONS"
.IX Header "WIDGET-SPECIFIC OPTIONS"
.IP "\(bu" 4
\&\fB\-releasefocus\fR
.Sp
If this option is set, the widgets inside this Container will be
part of the focus ordering of the parent widget.
This means that when this Container gets the focus, its first widget
will be focused.  When the focus leaves the last widget inside the 
Container it will give the focus back to the parent instead
of cycling back to the first widget in this Container.
This option is useful to create a sub-class packed with common used 
widgets, making the reuse easier.
.SH "METHODS"
.IX Header "METHODS"
.IP "\(bu" 4
\&\fBnew\fR ( )
.Sp
Create a new instance of the Curses::UI::Container class.
.IP "\(bu" 4
\&\fBadd\fR ( \s-1ID, CLASS, OPTIONS \s0)
.Sp
This is the main method for this class. Using this method
it is easy to add widgets to the container.
.Sp
The \s-1ID\s0 is an identifier that you want to use for the
added widget. This may be any string you want. If you
do not need an \s-1ID,\s0 you may also us an undefined
value. The container will automatically create
an \s-1ID\s0 for you.
.Sp
The \s-1CLASS\s0 is the class which you want to add to the
container. If \s-1CLASS\s0 does not contain '::' or \s-1CLASS\s0
matches 'Dialog::...' then 'Curses::UI' will be prepended
to it. This way you do not have to specifiy the full
class name for widgets that are in the Curses::UI 
hierarchy. It is not necessary to call \*(L"use \s-1CLASS\*(R"\s0
yourself. The \fBadd\fR method will call the \fBusemodule\fR
method from Curses::UI to automatically load the module.
.Sp
The hash \s-1OPTIONS\s0 contains the options that you want to pass
on to the new instance of \s-1CLASS.\s0
.Sp
Example:
.Sp
.Vb 7
\&    $container\->add(
\&        \*(Aqmyid\*(Aq,                   # ID 
\&        \*(AqLabel\*(Aq,                  # CLASS
\&        \-text => \*(AqHello, world!\*(Aq, # OPTIONS
\&        \-x    => 10,
\&        \-y    => 5,
\&    );
.Ve
.IP "\(bu" 4
\&\fBdelete\fR ( \s-1ID \s0)
.Sp
This method deletes the contained widget with the given \s-1ID\s0
from the container.
.IP "\(bu" 4
\&\fBhasa\fR ( \s-1CLASS \s0)
.Sp
This method returns true if the container contains one or
more widgets of the class \s-1CLASS.\s0
.IP "\(bu" 4
\&\fBlayout\fR ( )
.Sp
Layout the Container and all its contained widgets.
.IP "\(bu" 4
\&\fBdraw\fR ( \s-1BOOLEAN \s0)
.Sp
Draw the Container and all its contained widgets.
 If \s-1BOOLEAN\s0 is true, the screen will not update after 
drawing. By default this argument is false, so the 
screen will update after drawing the container.
.IP "\(bu" 4
\&\fBintellidraw\fR ( )
.Sp
See Curses::UI::Widget for an
explanation of this method.
.IP "\(bu" 4
\&\fBfocus\fR ( )
.Sp
If the container contains no widgets, this routine will
return immediately. Else the container will get focus.
.Sp
If the container gets focus, one of the contained widgets
will get the focus. The returnvalue of this widget determines
what has to be done next. Here are the possible cases:
.Sp
* The returnvalue is \fB\s-1LEAVE_CONTAINER\s0\fR
.Sp
.Vb 3
\&  As soon as a widget returns this value, the container
\&  will loose its focus and return the returnvalue and the
\&  last pressed key to the caller.
.Ve
.Sp
* The returnvalue is \fB\s-1STAY_AT_FOCUSPOSITION\s0\fR
.Sp
.Vb 2
\&  The container will not loose focus and the focus will stay
\&  at the same widget of the container.
.Ve
.Sp
* Any other returnvalue
.Sp
.Vb 1
\&  The focus will go to the next widget in the container.
.Ve
.IP "\(bu" 4
\&\fBgetobj\fR ( \s-1ID \s0)
.Sp
This method returns the object reference of the contained
widget with the given \s-1ID.\s0
.IP "\(bu" 4
\&\fBgetfocusobj\fR ( )
.Sp
This method returns the object reference of the contained
widget which currently has the focus.
.IP "\(bu" 4
\&\fBset_focusorder\fR ( \s-1IDLIST \s0)
.Sp
Normally the order in which widgets get focused in a 
container is determined by the order in which they
are added to the container. Use \fBset_focusorder\fR if you
want a different focus order. \s-1IDLIST\s0 contains a list
of id's.
.IP "\(bu" 4
\&\fBset_draworder\fR ( \s-1IDLIST \s0)
.Sp
Normally the order in which widgets are drawn in a 
container is determined by the order in which they
are added to the container. Use \fBset_draworder\fR if you
want a different draw order. \s-1IDLIST\s0 contains a list
of id's.
.IP "\(bu" 4
\&\fBloadmodule\fR ( \s-1CLASS \s0)
.Sp
This will load the module for the \s-1CLASS.\s0 If loading
fails, the program will die.
.IP "\(bu" 4
\&\fBonFocus\fR ( \s-1CODEREF \s0)
.Sp
This method can be used to set the \fB\-onfocus\fR event handler
(see above) after initialization of the widget.
.IP "\(bu" 4
\&\fBonBlur\fR ( \s-1CODEREF \s0)
.Sp
This method can be used to set the \fB\-onblur\fR event handler
(see above) after initialization of the widget.
.SH "DEFAULT BINDINGS"
.IX Header "DEFAULT BINDINGS"
Since interacting is not handled by the container itself, but 
by the contained widgets, this class does not have any key
bindings.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Curses::UI,
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2001\-2002 Maurice Makaay. All rights reserved.
.PP
Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)
.PP
This package is free software and is provided \*(L"as is\*(R" without express
or implied warranty. It may be used, redistributed and/or modified
under the same terms as perl itself.