1Curses::UI(3) User Contributed Perl Documentation Curses::UI(3)
2
6 Curses::UI - A curses based OO user interface framework
7
9 Version 0.9607
10
12 use Curses::UI;
13 # create a new C::UI object
15 my $cui = Curses::UI->new( -clear_on_exit => 1,
16 -debug => $debug, );
17 # this is where we gloss over setting up all the widgets and data
19 # structures :)
20 # start the event loop
22 $cui->mainloop;
23
25 Curses::UI is an object-oriented user interface framework for Perl.
26 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 See Curses::UI::Tutorial and the "examples" directory of the source
32 distribution for more introductory material.
33
35 Create a new Curses::UI object:
36 my $cui = Curses::UI->new( OPTIONS );
38 where "OPTIONS" is one or more of the following.
40 -clear_on_exit
42 If true, Curses::UI will call "clear" on exit. Defaults to false.
43 -color_support
45 If true, Curses::UI tries to enable color for the application. Defaults
46 to false.
47 -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 -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 -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 -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 -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
74 mainloop
75 The Curses::UI event handling loop. Call once setup is finished to
76 "start" a C::UI program.
77 schedule_event
79 Pushes its argument (a coderef) onto the scheduled event stack
80
82 layout
83 The layout method of Curses::UI tries to find the size of the screen
84 then calls the "layout" method of every contained object (i.e. window
85 or widget). It is not normally neccessary to call this method directly.
86
88 dialog
89 Use the "dialog" method to show a dialog window. If you only provide a
90 single argument, this argument will be used as the message to show.
91 Example:
92 $cui->dialog("Hello, world!");
94 If you want to have some more control over the dialog window, you will
96 have to provide more arguments (for an explanation of the arguments
97 that can be used, see Curses::UI::Dialog::Basic. Example:
98 my $yes = $cui->dialog(
100 -message => "Hello, world?",
101 -buttons =3D> ['yes','no'],
102 -values => [1,0],
103 -title => 'Question',
104 );
105 if ($yes) {
107 # whatever
108 }
109 error
111 The "error" method will create an error dialog. This is basically a
112 Curses::UI::Dialog::Basic, but it has an ASCII-art exclamation sign
113 drawn left to the message. For the rest it's just like "dialog".
114 Example:
115 $cui->error("It's the end of the\n"
117 ."world as we know it!");
118 filebrowser
120 Creates a file browser dialog. For an explanation of the arguments that
121 can be used, see Curses::UI::Dialog::Filebrowser. Example:
122 my $file = $cui->filebrowser(
124 -path => "/tmp",
125 -show_hidden => 1,
126 );
127 # Filebrowser will return undef
129 # if no file was selected.
130 if (defined $file) {
131 unless (open F, ">$file") {
132 print F "Hello, world!\n";
133 close F;
134 } else {
135 $cui->error(qq(Error on writing to "$file":\n$!));
136 }
137 loadfilebrowser, savefilebrowser
139 These two methods will create file browser dialogs as well. The
140 difference is that these will have the dialogs set up correctly for
141 loading and saving files. Moreover, the save dialog will check if the
142 selected file exists or not. If it does exist, it will show an
143 overwrite confirmation to check if the user really wants to overwrite
144 the selected file.
145 status, nostatus
147 Using these methods it's easy to provide status information for the
148 user of your program. The status dialog is a dialog with only a label
149 on it. The status dialog doesn't really get the focus. It's only used
150 to display some information. If you need more than one status, you can
151 call "status" subsequently. Any existing status dialog will be cleaned
152 up and a new one will be created.
153 If you are finished, you can delete the status dialog by calling the
155 "nostatus" method. Example:
156 $cui->status("Saying hello to the world...");
158 # code for saying "Hello, world!"
159 $cui->status("Saying goodbye to the world...");
161 # code for saying "Goodbye, world!"
162 $cui->nostatus;
164 progress, setprogress, noprogress
166 Using these methods it's easy to provide progress information to the
167 user. The progress dialog is a dialog with an optional label on it and
168 a progress bar. Similar to the status dialog, this dialog does not get
169 the focus.
170 Using the "progress" method, a new progress dialog can be created.
172 This method takes the same arguments as the
173 Curses::IU::Dialog::Progress class.
174 After that the progress can be set using "setprogress". This method
176 takes one or two arguments. The first argument is the current position
177 of the progressbar. The second argument is the message to show in the
178 label. If one of these arguments is undefined, the current value will
179 be kept.
180 If you are finished, you can delete the progress dialog by calling the
182 "noprogress" method.
183 $cui->progress(
185 -max => 10,
186 -message => "Counting 10 seconds...",
187 );
188 for my $second (0..10) {
190 $cui->setprogress($second)
191 sleep 1;
192 }
193 $cui->noprogress;
195
197 leave_curses ( )
198 Temporarily leaves curses mode and recovers normal terminal mode.
199 reset_curses ( )
201 Return to curses mode after leave_curses().
202 add ( ID, CLASS, OPTIONS )
204 The add method of Curses::UI is almost the same as the add method
205 of Curses::UI::Container. The difference is that Curses::UI will
206 only accept classes that are (descendants) of the
207 Curses::UI::Window class. For the rest of the information see
208 Curses::UI::Container.
209 add_callback ( ID, CODE)
211 This method lets you add a callback into the mainloop permanently.
212 The code is executed after the input handler has run.
213 delete_callback ( ID )
215 This method deletes the CODE specified by ID from the mainloop.
216 usemodule ( CLASSNAME )
218 Loads the with CLASSNAME given module.
219 userdata ( [ SCALAR ] )
221 This method will return the user internal data stored in the UI
222 object. If a SCALAR parameter is specified it will also set the
223 current user data to it.
224 keydelay ( )
226 This method is used internally to control timer events when the
227 -keydelay option is set, but it can be called directly it to find
228 out if the required amount of time has passed since the user's last
229 action. keydelay() will return 0 if insufficent time has passed,
230 and will return the number of elapsed seconds otherwise.
231 compat ( [BOOLEAN] )
233 The -compat option will be set to the BOOLEAN value, unless BOOLEAN
234 is omitted. The method returns the current value for -compat.
235 clear_on_exit ( [BOOLEAN] )
237 The -clear_on_exit option will be set to the BOOLEAN value, unless
238 BOOLEAN is omitted. The method returns the current value for
239 -clear_on_exit.
240 color ( )
242 Returns the currently used Curses::UI::Color object
243 set_color ( OBJECT )
245 Replaces the currently used Color object with an other. This can be
246 used to fast change all colors in a Curses::UI application.
247
249 Curses
250 Curses::UI::POE (a POE eventsystem and mainloop for Curses::UI)
251 http://curses-ui.googlecode.com/ <http://curses-ui.googlecode.com/>
252 (SVN repo, info, and links)
253
255 Please report any bugs or feature requests to
256 "bug-curses-ui@rt.cpan.org", or through the web interface at
257 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Curses-UI
258 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Curses-UI>. I will be
259 notified, and then you'll automatically be notified of progress on your
260 bug as I make changes.
261
263 Shawn Boyette "<mdxi@cpan.org>"
264 See the CREDITS file for additional information.
266
268 Copyright 2001-2002 Maurice Makaay; 2003-2006 Marcus Thiesen; 2007,
269 2008 Shawn Boyette. All Rights Reserved.
270 This program is free software; you can redistribute it and/or modify it
272 under the same terms as Perl itself.
273 This package is free software and is provided "as is" without express
275 or implied warranty. It may be used, redistributed and/or modified
276 under the same terms as perl itself.
277
279 Widgets
280 Curses::UI::Buttonbox
281 Curses::UI::Calendar
282 Curses::UI::Checkbox
283 Curses::UI::Label
284 Curses::UI::Listbox
285 Curses::UI::Menubar
286 Curses::UI::MenuListbox (used by Curses::UI::Menubar)
287 Curses::UI::Notebook
288 Curses::UI::PasswordEntry
289 Curses::UI::Popupmenu
290 Curses::UI::Progressbar
291 Curses::UI::Radiobuttonbox
292 Curses::UI::SearchEntry (used by Curses::UI::Searchable)
293 Curses::UI::TextEditor
294 Curses::UI::TextEntry
295 Curses::UI::TextViewer
296 Curses::UI::Window
297 Dialogs
299 Curses::UI::Dialog::Basic
300 Curses::UI::Dialog::Error
301 Curses::UI::Dialog::Filebrowser
302 Curses::UI::Dialog::Status
303 Base and Support Classes
305 Curses::UI::Widget
306 Curses::UI::Container
307 Curses::UI::Color
308 Curses::UI::Common
309 Curses::UI::Searchable
310perl v5.12.0 2008-12-21 Curses::UI(3)