.\" 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::Tutorial 3"
.TH Curses::UI::Tutorial 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::Tutorial \- Tutorial for the Curses::UI framework
.SH "Introduction"
.IX Header "Introduction"
The intention of this tutorial is a quick overview of Curses::UI and
it's widgets. The target of this example is to write a simple text
editor using the Curses::UI framework.
.SH "First requirements"
.IX Header "First requirements"
In order to use Curses::UI start your program with 
\&\*(L"use Curses::UI;\*(R" and, as it is always a good idea,
 add \*(L"use strict\*(R" and the \-w switch too.
After that an instance of Curses::UI must
be created. From now on, this instance will be called
\&\*(L"the \s-1UI\*(R".\s0 You  also want to redirect \s-1STDERR\s0 to a file 
(e.g. perl myscript.pl 2> debug.out), so output that does
not come from Curses::UI doesn't clobber your display.
You want fancy colors, so the option \-color_support is set
to a true value.
.PP
.Vb 1
\&    #!/usr/bin/perl \-w
\&
\&    use strict;
\&    use Curses::UI;
\&    my $cui = new Curses::UI( \-color_support => 1 );
.Ve
.SH "Create a menu"
.IX Header "Create a menu"
.Vb 7
\&        my @menu = (
\&          { \-label => \*(AqFile\*(Aq, 
\&            \-submenu => [
\&           { \-label => \*(AqExit      ^Q\*(Aq, \-value => \e&exit_dialog  }
\&                        ]
\&           },
\&        );
.Ve
.PP
In order to describe the structure of a menu Curses::UI uses
a rather ugly construct out of hash and arrayrefs. See
Curses::UI::Menubar for details. What you do at this point is to
create a Menubar with just one entry and one submenu. The entry
is 'File' and the submenu is 'Exit'. 
The value of this menu item is a reference to a sub called
exit_dialog.
.SH "Dialogs"
.IX Header "Dialogs"
.Vb 6
\&        sub exit_dialog()
\&        {
\&                my $return = $cui\->dialog(
\&                        \-message   => "Do you really want to quit?",
\&                        \-title     => "Are you sure???", 
\&                        \-buttons   => [\*(Aqyes\*(Aq, \*(Aqno\*(Aq],
\&
\&                );
\&
\&        exit(0) if $return;
\&        }
.Ve
.PP
The dialog method of Curses::UI gives us an easy and convenient way to
create dialogs on the main screen. A dialog is a way to interact with
the user in order to ask him a question or give him important
information.  This dialog is a more complex one, which asks the
question whether or not you really want to exit. As the button for 
\&\*(L"yes\*(R" would return us a true value, you can easily exit on this return 
value.
.SH "Add the Menubar"
.IX Header "Add the Menubar"
.Vb 5
\&        my $menu = $cui\->add(
\&                \*(Aqmenu\*(Aq,\*(AqMenubar\*(Aq, 
\&                \-menu => \e@menu,
\&                \-fg  => "blue",
\&        );
.Ve
.PP
To finally add the Menubar to our root object, you have to call the add
method on the Curses \s-1UI\s0 object. You specify the internal name of the
widget as the first argument, the widget type as the second argument
(like Label, TextViewer, etc.) and the menu structure you created at
the beginning as an array reference as third object. Because you want
the Menubar to have a blue theme, you give him the \-fg option
\&\*(L"blue\*(R". There are a couple of colors you can use, see
Curses::UI::Color for details.
.SH "Add a window"
.IX Header "Add a window"
.Vb 6
\&        my $win1 = $cui\->add(
\&                             \*(Aqwin1\*(Aq, \*(AqWindow\*(Aq,
\&                             \-border => 1,
\&                             \-y    => 1,
\&                             \-bfg  => \*(Aqred\*(Aq,
\&                     );
.Ve
.PP
There are only two types of object you can add to the Curses::UI root
object: Menubars and Windows. All other widgets have to be inserted
into a window. Of course you can add a Menubar to a window, but not
vice versa ;\-).
The add method always has the same two first arguments: the internal
name and the widget type. The internal name can be used to find an
object. The method getobj takes this name and returns us the
corresponding object out of the hierarchy. See Curses::UI for details.
Again you want some fancy colors, so you tell the window to have a
border, leave some space for the Menubar (\-y => 1) and set the border
foreground color to red.
.SH "Add a widget"
.IX Header "Add a widget"
.Vb 3
\&        my $texteditor = $win1\->add("text", "TextEditor",
\&                                 \-text => "Here is some text\en"
\&                                        . "And some more");
.Ve
.PP
The next step is to add a useful widget to our new small Curses::UI
app. Here you take a TextEditor widget which performs basic tasks as a
text editor. You add some initial text to the widget to make it not
seem that empty.
.SH "Making keybindings"
.IX Header "Making keybindings"
.Vb 2
\&        $cui\->set_binding(sub {$menu\->focus()}, "\ecX");
\&        $cui\->set_binding( \e&exit_dialog , "\ecQ");
.Ve
.PP
You want to be able to focus the Menubar if you finished editing in the
TextEditor widget. Therefore you set a binding to the focus function of
the menu and the key sequence Control (specified by \ec) combined with
X. Now you can easily return to the menu after editing.
Because it is easier to have a shortcut for closing the application you
add a binding for the sequence Control-Q to our nice exit_dialog
method.
.SH "The final steps"
.IX Header "The final steps"
.Vb 2
\&        $texteditor\->focus();
\&        $cui\->mainloop();
.Ve
.PP
You want to start editing directly. Therefore you set the initial focus
on the TextEditor by calling it's focus method directly. 
The last thing you got to do is to tell Curses that it now contoles the
program flow by starting it's MainLoop.
.SH "You're done!"
.IX Header "You're done!"
You have built a genuine Curses::UI application! Not that it is a
very useful one, but who cares? Now try out if it works like you 
think it should. The complete source code of this application 
is located in the examples directory of the distribution (examples/tutorial.pl).
.PP
Now you can enhance this application to become a full featured editor
like Emacs :\-)
.SH "Author"
.IX Header "Author"
2003\-2004 (c) by Marcus Thiesen (marcus@cpan.org)
All rights reserved
This Tutorial is licensed under the same terms as perl itself.
.PP
If you have some additions to this tutorial feel free to send me a
mail.