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

NAME

6       Curses::UI - A curses based OO user interface framework
7

VERSION

9       Version 0.9609
10

SYNOPSIS

12           use Curses::UI;
13
14           # create a new C::UI object
15           my $cui = Curses::UI->new( -clear_on_exit => 1,
16                                      -debug => $debug, );
17
18           # this is where we gloss over setting up all the widgets and data
19           # structures :)
20
21           # start the event loop
22           $cui->mainloop;
23

DESCRIPTION

25       Curses::UI is an object-oriented user interface framework for Perl.
26
27       It contains basic widgets (like buttons and text areas), more
28       "advanced" widgets (like UI tabs and a fully-functional basic text
29       editor), and some higher-level classes like pre-fab error dialogues.
30
31       See Curses::UI::Tutorial and the "examples" directory of the source
32       distribution for more introductory material.
33

CONSTRUCTOR

35       Create a new Curses::UI object:
36
37           my $cui = Curses::UI->new( OPTIONS );
38
39       where "OPTIONS" is one or more of the following.
40
41   -clear_on_exit
42       If true, Curses::UI will call "clear" on exit. Defaults to false.
43
44   -color_support
45       If true, Curses::UI tries to enable color for the application. Defaults
46       to false.
47
48   -compat
49       If true, Curses::UI will run in compatibility mode, meaning that only
50       very simple characters will be used for creating the widgets. Defaults
51       to false.
52
53   -keydelay
54       If set to a positive integer, Curses::UI will track elapsed seconds
55       since the user's last keystroke, preventing timer events from occurring
56       for the specified number of seconds afterwards. By default this option
57       is set to '0' (disabled).
58
59   -mouse_support
60       Curses::UI attempts to auto-discover if mouse support should be enabled
61       or not. This option allows a hard override. Expects a boolean value.
62
63   -userdata
64       Takes a scalar (frequently a hashref) as its argument, and stows that
65       scalar inside the Curses::UI object where it can be retrieved with the
66       #userdata method. Handy inside callbacks and the like.
67
68   -default_colors
69       Directs the underlying Curses library to allow use of default color
70       pairs on terminals. Is preset to true and you almost certainly don't
71       want to twiddle it. See "man use_default_colors" if you think you do.
72

EVENT HANDLING METHODS

74   mainloop
75       The Curses::UI event handling loop. Call once setup is finished to
76       "start" a C::UI program.
77
78   mainloopExit
79       This exits the main loop.
80
81   schedule_event
82       Pushes its argument (a coderef) onto the scheduled event stack
83

WINDOW/LAYOUT METHODS

85   layout
86       The layout method of Curses::UI tries to find the size of the screen
87       then calls the "layout" method of every contained object (i.e. window
88       or widget). It is not normally necessary to call this method directly.
89

CONVENIENCE DIALOG METHODS

91   dialog
92       Use the "dialog" method to show a dialog window. If you only provide a
93       single argument, this argument will be used as the message to show.
94       Example:
95
96           $cui->dialog("Hello, world!");
97
98       If you want to have some more control over the dialog window, you will
99       have to provide more arguments (for an explanation of the arguments
100       that can be used, see Curses::UI::Dialog::Basic.  Example:
101
102           my $yes = $cui->dialog(
103               -message => "Hello, world?",
104               -buttons =3D> ['yes','no'],
105               -values  => [1,0],
106               -title   => 'Question',
107           );
108
109           if ($yes) {
110               # whatever
111           }
112
113   error
114       The "error" method will create an error dialog. This is basically a
115       Curses::UI::Dialog::Basic, but it has an ASCII-art exclamation sign
116       drawn left to the message. For the rest it's just like "dialog".
117       Example:
118
119           $cui->error("It's the end of the\n"
120                      ."world as we know it!");
121
122   filebrowser
123       Creates a file browser dialog. For an explanation of the arguments that
124       can be used, see Curses::UI::Dialog::Filebrowser.  Example:
125
126           my $file = $cui->filebrowser(
127               -path => "/tmp",
128               -show_hidden => 1,
129           );
130
131           # Filebrowser will return undef
132           # if no file was selected.
133           if (defined $file) {
134               unless (open F, ">$file") {
135                   print F "Hello, world!\n";
136                   close F;
137           } else {
138               $cui->error(qq(Error on writing to "$file":\n$!));
139           }
140
141   loadfilebrowser, savefilebrowser
142       These two methods will create file browser dialogs as well.  The
143       difference is that these will have the dialogs set up correctly for
144       loading and saving files. Moreover, the save dialog will check if the
145       selected file exists or not. If it does exist, it will show an
146       overwrite confirmation to check if the user really wants to overwrite
147       the selected file.
148
149   status, nostatus
150       Using these methods it's easy to provide status information for the
151       user of your program. The status dialog is a dialog with only a label
152       on it. The status dialog doesn't really get the focus. It's only used
153       to display some information. If you need more than one status, you can
154       call "status" subsequently.  Any existing status dialog will be cleaned
155       up and a new one will be created.
156
157       If you are finished, you can delete the status dialog by calling the
158       "nostatus" method. Example:
159
160           $cui->status("Saying hello to the world...");
161           # code for saying "Hello, world!"
162
163           $cui->status("Saying goodbye to the world...");
164           # code for saying "Goodbye, world!"
165
166           $cui->nostatus;
167
168   progress, setprogress, noprogress
169       Using these methods it's easy to provide progress information to the
170       user. The progress dialog is a dialog with an optional label on it and
171       a progress bar. Similar to the status dialog, this dialog does not get
172       the focus.
173
174       Using the "progress" method, a new progress dialog can be created.
175       This method takes the same arguments as the
176       Curses::IU::Dialog::Progress class.
177
178       After that the progress can be set using "setprogress". This method
179       takes one or two arguments. The first argument is the current position
180       of the progressbar. The second argument is the message to show in the
181       label. If one of these arguments is undefined, the current value will
182       be kept.
183
184       If you are finished, you can delete the progress dialog by calling the
185       "noprogress" method.
186
187           $cui->progress(
188               -max => 10,
189               -message => "Counting 10 seconds...",
190           );
191
192           for my $second (0..10) {
193               $cui->setprogress($second)
194               sleep 1;
195           }
196
197           $cui->noprogress;
198

OTHER METHODS

200       leave_curses ( )
201           Temporarily leaves curses mode and recovers normal terminal mode.
202
203       reset_curses ( )
204           Return to curses mode after leave_curses().
205
206       add ( ID, CLASS, OPTIONS )
207           The add method of Curses::UI is almost the same as the add method
208           of Curses::UI::Container. The difference is that Curses::UI will
209           only accept classes that are (descendants) of the
210           Curses::UI::Window class. For the rest of the information see
211           Curses::UI::Container.
212
213       add_callback ( ID, CODE)
214           This method lets you add a callback into the mainloop permanently.
215           The code is executed after the input handler has run.
216
217       delete_callback ( ID )
218           This method deletes the CODE specified by ID from the mainloop.
219
220       usemodule ( CLASSNAME )
221           Loads the with CLASSNAME given module.
222
223       userdata ( [ SCALAR ] )
224           This method will return the user internal data stored in the UI
225           object.  If a SCALAR parameter is specified it will also set the
226           current user data to it.
227
228       keydelay ( )
229           This method is used internally to control timer events when the
230           -keydelay option is set, but it can be called directly it to find
231           out if the required amount of time has passed since the user's last
232           action. keydelay() will return 0 if insufficent time has passed,
233           and will return the number of elapsed seconds otherwise.
234
235       compat ( [BOOLEAN] )
236           The -compat option will be set to the BOOLEAN value, unless BOOLEAN
237           is omitted. The method returns the current value for -compat.
238
239       clear_on_exit ( [BOOLEAN] )
240           The -clear_on_exit option will be set to the BOOLEAN value, unless
241           BOOLEAN is omitted. The method returns the current value for
242           -clear_on_exit.
243
244       color ( )
245           Returns the currently used Curses::UI::Color object
246
247       set_color ( OBJECT )
248           Replaces the currently used Color object with another. This can be
249           used to fast change all colors in a Curses::UI application.
250

SEE ALSO

252       Curses
253       Curses::UI::POE (a POE eventsystem and mainloop for Curses::UI)
254       <http://curses-ui.googlecode.com/> (SVN repo, info, and links)
255

BUGS

257       Please report any bugs or feature requests to
258       "bug-curses-ui@rt.cpan.org", or through the web interface at
259       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Curses-UI>.  I will be
260       notified, and then you'll automatically be notified of progress on your
261       bug as I make changes.
262

AUTHOR

264       Shawn Boyette "<mdxi@cpan.org>"
265
266       See the CREDITS file for additional information.
267
269       Copyright 2001-2002 Maurice Makaay; 2003-2006 Marcus Thiesen; 2007,
270       2008 Shawn Boyette. All Rights Reserved.
271
272       This program is free software; you can redistribute it and/or modify it
273       under the same terms as Perl itself.
274
275       This package is free software and is provided "as is" without express
276       or implied warranty. It may be used, redistributed and/or modified
277       under the same terms as perl itself.
278

CLASS LISTING

280   Widgets
281       Curses::UI::Buttonbox
282       Curses::UI::Calendar
283       Curses::UI::Checkbox
284       Curses::UI::Label
285       Curses::UI::Listbox
286       Curses::UI::Menubar
287       Curses::UI::MenuListbox (used by Curses::UI::Menubar)
288       Curses::UI::Notebook
289       Curses::UI::PasswordEntry
290       Curses::UI::Popupmenu
291       Curses::UI::Progressbar
292       Curses::UI::Radiobuttonbox
293       Curses::UI::SearchEntry (used by Curses::UI::Searchable)
294       Curses::UI::TextEditor
295       Curses::UI::TextEntry
296       Curses::UI::TextViewer
297       Curses::UI::Window
298
299   Dialogs
300       Curses::UI::Dialog::Basic
301       Curses::UI::Dialog::Error
302       Curses::UI::Dialog::Filebrowser
303       Curses::UI::Dialog::Status
304
305   Base and Support Classes
306       Curses::UI::Widget
307       Curses::UI::Container
308       Curses::UI::Color
309       Curses::UI::Common
310       Curses::UI::Searchable
311
312
313
314perl v5.38.0                      2023-07-20                     Curses::UI(3)
Impressum