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.9609
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 mainloopExit
79 This exits the main loop.
80 schedule_event
82 Pushes its argument (a coderef) onto the scheduled event stack
83
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
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 $cui->dialog("Hello, world!");
97 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 my $yes = $cui->dialog(
103 -message => "Hello, world?",
104 -buttons =3D> ['yes','no'],
105 -values => [1,0],
106 -title => 'Question',
107 );
108 if ($yes) {
110 # whatever
111 }
112 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 $cui->error("It's the end of the\n"
120 ."world as we know it!");
121 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 my $file = $cui->filebrowser(
127 -path => "/tmp",
128 -show_hidden => 1,
129 );
130 # 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 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 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 If you are finished, you can delete the status dialog by calling the
158 "nostatus" method. Example:
159 $cui->status("Saying hello to the world...");
161 # code for saying "Hello, world!"
162 $cui->status("Saying goodbye to the world...");
164 # code for saying "Goodbye, world!"
165 $cui->nostatus;
167 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 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 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 If you are finished, you can delete the progress dialog by calling the
185 "noprogress" method.
186 $cui->progress(
188 -max => 10,
189 -message => "Counting 10 seconds...",
190 );
191 for my $second (0..10) {
193 $cui->setprogress($second)
194 sleep 1;
195 }
196 $cui->noprogress;
198
200 leave_curses ( )
201 Temporarily leaves curses mode and recovers normal terminal mode.
202 reset_curses ( )
204 Return to curses mode after leave_curses().
205 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 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 delete_callback ( ID )
218 This method deletes the CODE specified by ID from the mainloop.
219 usemodule ( CLASSNAME )
221 Loads the with CLASSNAME given module.
222 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 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 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 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 color ( )
245 Returns the currently used Curses::UI::Color object
246 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
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
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
264 Shawn Boyette "<mdxi@cpan.org>"
265 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 This program is free software; you can redistribute it and/or modify it
273 under the same terms as Perl itself.
274 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
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 Dialogs
300 Curses::UI::Dialog::Basic
301 Curses::UI::Dialog::Error
302 Curses::UI::Dialog::Filebrowser
303 Curses::UI::Dialog::Status
304 Base and Support Classes
306 Curses::UI::Widget
307 Curses::UI::Container
308 Curses::UI::Color
309 Curses::UI::Common
310 Curses::UI::Searchable
311perl v5.38.0 2023-07-20 Curses::UI(3)