1Curses::UI::Tutorial(3)User Contributed Perl DocumentatioCnurses::UI::Tutorial(3)
2
3
4

NAME

6       Curses::UI::Tutorial - Tutorial for the Curses::UI framework
7

Introduction

9       The intention of this tutorial is a quick overview of Curses::UI and
10       it's widgets. The target of this example is to write a simple text
11       editor using the Curses::UI framework.
12

First requirements

14       In order to use Curses::UI start your program with "use Curses::UI;"
15       and, as it is always a good idea,
16        add "use strict" and the -w switch too.  After that an instance of
17       Curses::UI must be created. From now on, this instance will be called
18       "the UI". You  also want to redirect STDERR to a file (e.g. perl
19       myscript.pl 2> debug.out), so output that does not come from Curses::UI
20       doesn't clobber your display.  You want fancy colors, so the option
21       -color_support is set to a true value.
22
23           #!/usr/bin/perl -w
24
25           use strict;
26           use Curses::UI;
27           my $cui = new Curses::UI( -color_support => 1 );
28

Create a menu

30               my @menu = (
31                 { -label => 'File',
32                   -submenu => [
33                  { -label => 'Exit      ^Q', -value => \&exit_dialog  }
34                               ]
35                  },
36               );
37
38       In order to describe the structure of a menu Curses::UI uses a rather
39       ugly construct out of hash and arrayrefs. See Curses::UI::Menubar for
40       details. What you do at this point is to create a Menubar with just one
41       entry and one submenu. The entry is 'File' and the submenu is 'Exit'.
42       The value of this menu item is a reference to a sub called exit_dialog.
43

Dialogs

45               sub exit_dialog()
46               {
47                       my $return = $cui->dialog(
48                               -message   => "Do you really want to quit?",
49                               -title     => "Are you sure???",
50                               -buttons   => ['yes', 'no'],
51
52                       );
53
54               exit(0) if $return;
55               }
56
57       The dialog method of Curses::UI gives us an easy and convenient way to
58       create dialogs on the main screen. A dialog is a way to interact with
59       the user in order to ask him a question or give him important
60       information.  This dialog is a more complex one, which asks the
61       question whether or not you really want to exit. As the button for
62       "yes" would return us a true value, you can easily exit on this return
63       value.
64

Add the Menubar

66               my $menu = $cui->add(
67                       'menu','Menubar',
68                       -menu => \@menu,
69                       -fg  => "blue",
70               );
71
72       To finally add the Menubar to our root object, you have to call the add
73       method on the Curses UI object. You specify the internal name of the
74       widget as the first argument, the widget type as the second argument
75       (like Label, TextViewer, etc.) and the menu structure you created at
76       the beginning as an array reference as third object. Because you want
77       the Menubar to have a blue theme, you give him the -fg option "blue".
78       There are a couple of colors you can use, see Curses::UI::Color for
79       details.
80

Add a window

82               my $win1 = $cui->add(
83                                    'win1', 'Window',
84                                    -border => 1,
85                                    -y    => 1,
86                                    -bfg  => 'red',
87                            );
88
89       There are only two types of object you can add to the Curses::UI root
90       object: Menubars and Windows. All other widgets have to be inserted
91       into a window. Of course you can add a Menubar to a window, but not
92       vice versa ;-).  The add method always has the same two first
93       arguments: the internal name and the widget type. The internal name can
94       be used to find an object. The method getobj takes this name and
95       returns us the corresponding object out of the hierarchy. See
96       Curses::UI for details.  Again you want some fancy colors, so you tell
97       the window to have a border, leave some space for the Menubar (-y => 1)
98       and set the border foreground color to red.
99

Add a widget

101               my $texteditor = $win1->add("text", "TextEditor",
102                                        -text => "Here is some text\n"
103                                               . "And some more");
104
105       The next step is to add a useful widget to our new small Curses::UI
106       app. Here you take a TextEditor widget which performs basic tasks as a
107       text editor. You add some initial text to the widget to make it not
108       seem that empty.
109

Making keybindings

111               $cui->set_binding(sub {$menu->focus()}, "\cX");
112               $cui->set_binding( \&exit_dialog , "\cQ");
113
114       You want to be able to focus the Menubar if you finished editing in the
115       TextEditor widget. Therefore you set a binding to the focus function of
116       the menu and the key sequence Control (specified by \c) combined with
117       X. Now you can easily return to the menu after editing.  Because it is
118       easier to have a shortcut for closing the application you add a binding
119       for the sequence Control-Q to our nice exit_dialog method.
120

The final steps

122               $texteditor->focus();
123               $cui->mainloop();
124
125       You want to start editing directly. Therefore you set the initial focus
126       on the TextEditor by calling it's focus method directly.  The last
127       thing you got to do is to tell Curses that it now contoles the program
128       flow by starting it's MainLoop.
129

You're done!

131       You have built a genuine Curses::UI application! Not that it is a very
132       useful one, but who cares? Now try out if it works like you think it
133       should. The complete source code of this application is located in the
134       examples directory of the distribution (examples/tutorial.pl).
135
136       Now you can enhance this application to become a full featured editor
137       like Emacs :-)
138

Author

140       2003-2004 (c) by Marcus Thiesen (marcus@cpan.org) All rights reserved
141       This Tutorial is licensed under the same terms as perl itself.
142
143       If you have some additions to this tutorial feel free to send me a
144       mail.
145
146
147
148perl v5.36.0                      2023-01-20           Curses::UI::Tutorial(3)
Impressum