.\" 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 3"
.TH Curses::UI 3 "2011-09-03" "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 \- A curses based OO user interface framework
.SH "VERSION"
.IX Header "VERSION"
Version 0.9609
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Curses::UI;
\&
\&    # create a new C::UI object
\&    my $cui = Curses::UI\->new( \-clear_on_exit => 1,
\&                               \-debug => $debug, );
\&
\&    # this is where we gloss over setting up all the widgets and data
\&    # structures :)
\&
\&    # start the event loop
\&    $cui\->mainloop;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Curses::UI is an object-oriented user interface framework for Perl.
.PP
It contains basic widgets (like buttons and text areas), more
\&\*(L"advanced\*(R" widgets (like \s-1UI\s0 tabs and a fully-functional basic text
editor), and some higher-level classes like pre-fab error dialogues.
.PP
See Curses::UI::Tutorial and the \f(CW\*(C`examples\*(C'\fR directory of the
source distribution for more introductory material.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
Create a new Curses::UI object:
.PP
.Vb 1
\&    my $cui = Curses::UI\->new( OPTIONS );
.Ve
.PP
where \f(CW\*(C`OPTIONS\*(C'\fR is one or more of the following.
.SS "\-clear_on_exit"
.IX Subsection "-clear_on_exit"
If true, Curses::UI will call \f(CW\*(C`clear\*(C'\fR on exit. Defaults to false.
.SS "\-color_support"
.IX Subsection "-color_support"
If true, Curses::UI tries to enable color for the
application. Defaults to false.
.SS "\-compat"
.IX Subsection "-compat"
If true, Curses::UI will run in compatibility mode, meaning that only
very simple characters will be used for creating the widgets. Defaults
to false.
.SS "\-keydelay"
.IX Subsection "-keydelay"
If set to a positive integer, Curses::UI will track elapsed seconds
since the user's last keystroke, preventing timer events from
occurring for the specified number of seconds afterwards. By default
this option is set to '0' (disabled).
.SS "\-mouse_support"
.IX Subsection "-mouse_support"
Curses::UI attempts to auto-discover if mouse support should be
enabled or not. This option allows a hard override. Expects a boolean
value.
.SS "\-userdata"
.IX Subsection "-userdata"
Takes a scalar (frequently a hashref) as its argument, and stows that
scalar inside the Curses::UI object where it can be retrieved with the
#userdata method. Handy inside callbacks and the like.
.SS "\-default_colors"
.IX Subsection "-default_colors"
Directs the underlying Curses library to allow use of default color
pairs on terminals. Is preset to true and you almost certainly don't
want to twiddle it. See \f(CW\*(C`man use_default_colors\*(C'\fR if you think you do.
.SH "EVENT HANDLING METHODS"
.IX Header "EVENT HANDLING METHODS"
.SS "mainloop"
.IX Subsection "mainloop"
The Curses::UI event handling loop. Call once setup is finished to
\&\*(L"start\*(R" a C::UI program.
.SS "mainloopExit"
.IX Subsection "mainloopExit"
This exits the main loop.
.SS "schedule_event"
.IX Subsection "schedule_event"
Pushes its argument (a coderef) onto the scheduled event stack
.SH "WINDOW/LAYOUT METHODS"
.IX Header "WINDOW/LAYOUT METHODS"
.SS "layout"
.IX Subsection "layout"
The layout method of Curses::UI tries to find the size of the screen
then calls the \f(CW\*(C`layout\*(C'\fR method of every contained object (i.e. window
or widget). It is not normally necessary to call this method directly.
.SH "CONVENIENCE DIALOG METHODS"
.IX Header "CONVENIENCE DIALOG METHODS"
.SS "dialog"
.IX Subsection "dialog"
Use the \f(CW\*(C`dialog\*(C'\fR method to show a dialog window. If you only provide
a single argument, this argument will be used as the message to
show. Example:
.PP
.Vb 1
\&    $cui\->dialog("Hello, world!");
.Ve
.PP
If you want to have some more control over the dialog window, you will
have to provide more arguments (for an explanation of the arguments
that can be used, see Curses::UI::Dialog::Basic.  Example:
.PP
.Vb 6
\&    my $yes = $cui\->dialog(
\&        \-message => "Hello, world?",
\&        \-buttons =3D> [\*(Aqyes\*(Aq,\*(Aqno\*(Aq],
\&        \-values  => [1,0],
\&        \-title   => \*(AqQuestion\*(Aq,
\&    );
\&
\&    if ($yes) {
\&        # whatever
\&    }
.Ve
.SS "error"
.IX Subsection "error"
The \f(CW\*(C`error\*(C'\fR method will create an error dialog. This is basically a
Curses::UI::Dialog::Basic, but it has an ASCII-art exclamation sign
drawn left to the message. For the rest it's just like
\&\f(CW\*(C`dialog\*(C'\fR. Example:
.PP
.Vb 2
\&    $cui\->error("It\*(Aqs the end of the\en"
\&               ."world as we know it!");
.Ve
.SS "filebrowser"
.IX Subsection "filebrowser"
Creates a file browser dialog. For an explanation of the arguments
that can be used, see Curses::UI::Dialog::Filebrowser.  Example:
.PP
.Vb 4
\&    my $file = $cui\->filebrowser(
\&        \-path => "/tmp",
\&        \-show_hidden => 1,
\&    );
\&
\&    # Filebrowser will return undef
\&    # if no file was selected.
\&    if (defined $file) {
\&        unless (open F, ">$file") {
\&            print F "Hello, world!\en";
\&            close F;
\&    } else {
\&        $cui\->error(qq(Error on writing to "$file":\en$!));
\&    }
.Ve
.SS "loadfilebrowser, savefilebrowser"
.IX Subsection "loadfilebrowser, savefilebrowser"
These two methods will create file browser dialogs as well.  The
difference is that these will have the dialogs set up correctly for
loading and saving files. Moreover, the save dialog will check if the
selected file exists or not. If it does exist, it will show an
overwrite confirmation to check if the user really wants to overwrite
the selected file.
.SS "status, nostatus"
.IX Subsection "status, nostatus"
Using these methods it's easy to provide status information for the
user of your program. The status dialog is a dialog with only a label
on it. The status dialog doesn't really get the focus. It's only used
to display some information. If you need more than one status, you can
call \f(CW\*(C`status\*(C'\fR subsequently.  Any existing status dialog will be
cleaned up and a new one will be created.
.PP
If you are finished, you can delete the status dialog by calling the
\&\f(CW\*(C`nostatus\*(C'\fR method. Example:
.PP
.Vb 2
\&    $cui\->status("Saying hello to the world...");
\&    # code for saying "Hello, world!"
\&
\&    $cui\->status("Saying goodbye to the world...");
\&    # code for saying "Goodbye, world!"
\&
\&    $cui\->nostatus;
.Ve
.SS "progress, setprogress, noprogress"
.IX Subsection "progress, setprogress, noprogress"
Using these methods it's easy to provide progress information to the
user. The progress dialog is a dialog with an optional label on it and
a progress bar. Similar to the status dialog, this dialog does not get
the focus.
.PP
Using the \f(CW\*(C`progress\*(C'\fR method, a new progress dialog can be created.
This method takes the same arguments as the
Curses::IU::Dialog::Progress class.
.PP
After that the progress can be set using \f(CW\*(C`setprogress\*(C'\fR. This method
takes one or two arguments. The first argument is the current position
of the progressbar. The second argument is the message to show in the
label. If one of these arguments is undefined, the current value will
be kept.
.PP
If you are finished, you can delete the progress dialog by calling the
\&\f(CW\*(C`noprogress\*(C'\fR method.
.PP
.Vb 4
\&    $cui\->progress(
\&        \-max => 10,
\&        \-message => "Counting 10 seconds...",
\&    );
\&
\&    for my $second (0..10) {
\&        $cui\->setprogress($second)
\&        sleep 1;
\&    }
\&
\&    $cui\->noprogress;
.Ve
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.IP "\fBleave_curses\fR ( )" 4
.IX Item "leave_curses ( )"
Temporarily leaves curses mode and recovers normal terminal mode.
.IP "\fBreset_curses\fR ( )" 4
.IX Item "reset_curses ( )"
Return to curses mode after \fB\f(BIleave_curses()\fB\fR.
.IP "\fBadd\fR ( \s-1ID, CLASS, OPTIONS \s0)" 4
.IX Item "add ( ID, CLASS, OPTIONS )"
The \fBadd\fR method of Curses::UI is almost the same as the \fBadd\fR
method of Curses::UI::Container. The difference is that Curses::UI
will only accept classes that are (descendants) of the
Curses::UI::Window class. For the rest of the information see
Curses::UI::Container.
.IP "\fBadd_callback\fR ( \s-1ID, CODE\s0)" 4
.IX Item "add_callback ( ID, CODE)"
This method lets you add a callback into the mainloop permanently.
The code is executed after the input handler has run.
.IP "\fBdelete_callback\fR ( \s-1ID \s0)" 4
.IX Item "delete_callback ( ID )"
This method deletes the \s-1CODE\s0 specified by \s-1ID\s0 from the mainloop.
.IP "\fBusemodule\fR ( \s-1CLASSNAME \s0)" 4
.IX Item "usemodule ( CLASSNAME )"
Loads the with \s-1CLASSNAME\s0 given module.
.IP "\fBuserdata\fR ( [ \s-1SCALAR \s0] )" 4
.IX Item "userdata ( [ SCALAR ] )"
This method will return the user internal data stored in the \s-1UI\s0
object.  If a \s-1SCALAR\s0 parameter is specified it will also set the
current user data to it.
.IP "\fBkeydelay\fR ( )" 4
.IX Item "keydelay ( )"
This method is used internally to control timer events when the
\&\fB\-keydelay\fR option is set, but it can be called directly it to find
out if the required amount of time has passed since the user's last
action. \fBkeydelay\fR() will return 0 if insufficent time has passed,
and will return the number of elapsed seconds otherwise.
.IP "\fBcompat\fR ( [\s-1BOOLEAN\s0] )" 4
.IX Item "compat ( [BOOLEAN] )"
The \fB\-compat\fR option will be set to the \s-1BOOLEAN\s0 value, unless \s-1BOOLEAN\s0
is omitted. The method returns the current value for \fB\-compat\fR.
.IP "\fBclear_on_exit\fR ( [\s-1BOOLEAN\s0] )" 4
.IX Item "clear_on_exit ( [BOOLEAN] )"
The \fB\-clear_on_exit\fR option will be set to the \s-1BOOLEAN\s0 value, unless
\&\s-1BOOLEAN\s0 is omitted. The method returns the current value for
\&\fB\-clear_on_exit\fR.
.IP "\fBcolor\fR ( )" 4
.IX Item "color ( )"
Returns the currently used Curses::UI::Color object
.IP "\fBset_color\fR ( \s-1OBJECT \s0)" 4
.IX Item "set_color ( OBJECT )"
Replaces the currently used Color object with another. This can be
used to fast change all colors in a Curses::UI application.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "Curses" 4
.IX Item "Curses"
.PD 0
.IP "Curses::UI::POE (a \s-1POE\s0 eventsystem and mainloop for Curses::UI)" 4
.IX Item "Curses::UI::POE (a POE eventsystem and mainloop for Curses::UI)"
.IP "<http://curses\-ui.googlecode.com/> (\s-1SVN\s0 repo, info, and links)" 4
.IX Item "<http://curses-ui.googlecode.com/> (SVN repo, info, and links)"
.PD
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-curses\-ui@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Curses\-UI>.  I will be
notified, and then you'll automatically be notified of progress on
your bug as I make changes.
.SH "AUTHOR"
.IX Header "AUTHOR"
Shawn Boyette \f(CW\*(C`<mdxi@cpan.org>\*(C'\fR
.PP
See the \s-1CREDITS\s0 file for additional information.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2001\-2002 Maurice Makaay; 2003\-2006 Marcus Thiesen; 2007,
2008 Shawn Boyette. All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.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.
.SH "CLASS LISTING"
.IX Header "CLASS LISTING"
.SS "Widgets"
.IX Subsection "Widgets"
.IP "Curses::UI::Buttonbox" 4
.IX Item "Curses::UI::Buttonbox"
.PD 0
.IP "Curses::UI::Calendar" 4
.IX Item "Curses::UI::Calendar"
.IP "Curses::UI::Checkbox" 4
.IX Item "Curses::UI::Checkbox"
.IP "Curses::UI::Label" 4
.IX Item "Curses::UI::Label"
.IP "Curses::UI::Listbox" 4
.IX Item "Curses::UI::Listbox"
.IP "Curses::UI::Menubar" 4
.IX Item "Curses::UI::Menubar"
.IP "Curses::UI::MenuListbox (used by Curses::UI::Menubar)" 4
.IX Item "Curses::UI::MenuListbox (used by Curses::UI::Menubar)"
.IP "Curses::UI::Notebook" 4
.IX Item "Curses::UI::Notebook"
.IP "Curses::UI::PasswordEntry" 4
.IX Item "Curses::UI::PasswordEntry"
.IP "Curses::UI::Popupmenu" 4
.IX Item "Curses::UI::Popupmenu"
.IP "Curses::UI::Progressbar" 4
.IX Item "Curses::UI::Progressbar"
.IP "Curses::UI::Radiobuttonbox" 4
.IX Item "Curses::UI::Radiobuttonbox"
.IP "Curses::UI::SearchEntry (used by Curses::UI::Searchable)" 4
.IX Item "Curses::UI::SearchEntry (used by Curses::UI::Searchable)"
.IP "Curses::UI::TextEditor" 4
.IX Item "Curses::UI::TextEditor"
.IP "Curses::UI::TextEntry" 4
.IX Item "Curses::UI::TextEntry"
.IP "Curses::UI::TextViewer" 4
.IX Item "Curses::UI::TextViewer"
.IP "Curses::UI::Window" 4
.IX Item "Curses::UI::Window"
.PD
.SS "Dialogs"
.IX Subsection "Dialogs"
.IP "Curses::UI::Dialog::Basic" 4
.IX Item "Curses::UI::Dialog::Basic"
.PD 0
.IP "Curses::UI::Dialog::Error" 4
.IX Item "Curses::UI::Dialog::Error"
.IP "Curses::UI::Dialog::Filebrowser" 4
.IX Item "Curses::UI::Dialog::Filebrowser"
.IP "Curses::UI::Dialog::Status" 4
.IX Item "Curses::UI::Dialog::Status"
.PD
.SS "Base and Support Classes"
.IX Subsection "Base and Support Classes"
.IP "Curses::UI::Widget" 4
.IX Item "Curses::UI::Widget"
.PD 0
.IP "Curses::UI::Container" 4
.IX Item "Curses::UI::Container"
.IP "Curses::UI::Color" 4
.IX Item "Curses::UI::Color"
.IP "Curses::UI::Common" 4
.IX Item "Curses::UI::Common"
.IP "Curses::UI::Searchable" 4
.IX Item "Curses::UI::Searchable"