| Curses::UI - A curses based OO user interface framework |
Curses::UI - A curses based OO user interface framework
Version 0.9603
use Curses::UI;
# create a new C::UI object
my $cui = Curses::UI->new( -clear_on_exit => 1,
-debug => $debug, );
# this is where we gloss over setting up all the widgets and data
# structures :)
# start the event loop
$cui->mainloop;
Curses::UI is an object-oriented user interface framework for Perl.
It contains basic widgets (like buttons and text areas), more ``advanced'' widgets (like UI tabs and a fully-functional basic text editor), and some higher-level classes like pre-fab error dialogues.
See the Curses::UI::Tutorial manpage and the examples directory of the
source distribution for more introductory material.
Create a new Curses::UI object:
my $cui = Curses::UI->new( OPTIONS );
where OPTIONS is one or more of the following.
If true, Curses::UI will call clear on exit. Defaults to false.
If true, Curses::UI tries to enable color for the application. Defaults to false.
If true, Curses::UI will run in compatibility mode, meaning that only very simple characters will be used for creating the widgets. Defaults to false.
If set to a positive integer, Curses::UI will track elapsed seconds since the user's last keystroke, preventing timer events from occurring for the specified number of seconds afterwards. By default this option is set to '0' (disabled).
Curses::UI attempts to auto-discover if mouse support should be enabled or not. This option allows a hard override. Expects a boolean value.
Takes a scalar (frequently a hashref) as its argument, and stows that scalar inside the Curses::UI object where it can be retrieved with the #userdata method. Handy inside callbacks and the like.
Directs the underlying Curses library to allow use of default color
pairs on terminals. Is preset to true and you almost certainly don't
want to twiddle it. See man use_default_colors if you think you do.
The Curses::UI event handling loop. Call once setup is finished to ``start'' a C::UI program.
Pushes its argument (a coderef) onto the scheduled event stack
The layout method of Curses::UI tries to find the size of the screen
then calls the layout method of every contained object (i.e. window
or widget). It is not normally neccessary to call this method directly.
Use the dialog method to show a dialog window. If you only provide
a single argument, this argument will be used as the message to
show. Example:
$cui->dialog("Hello, world!");
If you want to have some more control over the dialog window, you will have to provide more arguments (for an explanation of the arguments that can be used, see the Curses::UI::Dialog::Basic manpage. Example:
my $yes = $cui->dialog(
-message => "Hello, world?",
-buttons =3D> ['yes','no'],
-values => [1,0],
-title => 'Question',
);
if ($yes) {
# whatever
}
The error method will create an error dialog. This is basically a
Curses::UI::Dialog::Basic, but it has an ASCII-art exclamation sign
drawn left to the message. For the rest it's just like
dialog. Example:
$cui->error("It's the end of the\n"
."world as we know it!");
Creates a file browser dialog. For an explanation of the arguments that can be used, see the Curses::UI::Dialog::Filebrowser manpage. Example:
my $file = $cui->filebrowser(
-path => "/tmp",
-show_hidden => 1,
);
# Filebrowser will return undef
# if no file was selected.
if (defined $file) {
unless (open F, ">$file") {
print F "Hello, world!\n";
close F;
} else {
$cui->error(qq(Error on writing to "$file":\n$!));
}
These two methods will create file browser dialogs as well. The difference is that these will have the dialogs set up correctly for loading and saving files. Moreover, the save dialog will check if the selected file exists or not. If it does exist, it will show an overwrite confirmation to check if the user really wants to overwrite the selected file.
Using these methods it's easy to provide status information for the
user of your program. The status dialog is a dialog with only a label
on it. The status dialog doesn't really get the focus. It's only used
to display some information. If you need more than one status, you can
call status subsequently. Any existing status dialog will be
cleaned up and a new one will be created.
If you are finished, you can delete the status dialog by calling the
nostatus method. Example:
$cui->status("Saying hello to the world...");
# code for saying "Hello, world!"
$cui->status("Saying goodbye to the world...");
# code for saying "Goodbye, world!"
$cui->nostatus;
Using these methods it's easy to provide progress information to the user. The progress dialog is a dialog with an optional label on it and a progress bar. Similar to the status dialog, this dialog does not get the focus.
Using the progress method, a new progress dialog can be created.
This method takes the same arguments as the
the Curses::IU::Dialog::Progress manpage class.
After that the progress can be set using setprogress. This method
takes one or two arguments. The first argument is the current position
of the progressbar. The second argument is the message to show in the
label. If one of these arguments is undefined, the current value will
be kept.
If you are finished, you can delete the progress dialog by calling the
noprogress method.
$cui->progress(
-max => 10,
-message => "Counting 10 seconds...",
);
for my $second (0..10) {
$cui->setprogress($second)
sleep 1;
}
$cui->noprogress;
Please report any bugs or feature requests to
bug-curses-ui@rt.cpan.org, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html. I will be
notified, and then you'll automatically be notified of progress on
your bug as I make changes.
Shawn Boyette <mdxi@cpan.org>
See the CREDITS file for additional information.
Copyright 2001-2002 Maurice Makaay; 2003-2006 Marcus Thiesen; 2007, 2008 Shawn Boyette. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This package is free software and is provided ``as is'' without express or implied warranty. It may be used, redistributed and/or modified under the same terms as perl itself.
| Curses::UI - A curses based OO user interface framework |