Curses::UI - A curses based OO user interface framework
Version 0.9609
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 Curses::UI::Tutorial 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.
This exits the main loop.
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 necessary 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 Curses::UI::Dialog::Basic. 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 Curses::UI::Dialog::Filebrowser. 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 Curses::IU::Dialog::Progress
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;
-
leave_curses ( )
- Temporarily leaves curses mode and recovers normal terminal
mode.
-
reset_curses ( )
- Return to curses mode after
leave_curses().
-
add ( ID, CLASS, OPTIONS )
- The add method of Curses::UI is almost the same as
the add method of Curses::UI::Container. The difference is that
Curses::UI will only accept classes that are (descendants) of the
Curses::UI::Window class. For the rest of the information see
Curses::UI::Container.
-
add_callback ( ID, CODE)
- This method lets you add a callback into the mainloop
permanently. The code is executed after the input handler has run.
-
delete_callback ( ID )
- This method deletes the CODE specified by ID from the
mainloop.
-
usemodule ( CLASSNAME )
- Loads the with CLASSNAME given module.
-
userdata ( [ SCALAR ] )
- This method will return the user internal data stored in
the UI object. If a SCALAR parameter is specified it will also set the
current user data to it.
-
keydelay ( )
- This method is used internally to control timer events when
the -keydelay option is set, but it can be called directly it to
find out if the required amount of time has passed since the user's last
action. keydelay() will return 0 if insufficent time has passed,
and will return the number of elapsed seconds otherwise.
-
compat ( [BOOLEAN] )
- The -compat option will be set to the BOOLEAN value,
unless BOOLEAN is omitted. The method returns the current value for
-compat.
-
clear_on_exit ( [BOOLEAN] )
- The -clear_on_exit option will be set to the BOOLEAN
value, unless BOOLEAN is omitted. The method returns the current value for
-clear_on_exit.
-
color ( )
- Returns the currently used Curses::UI::Color object
-
set_color ( OBJECT )
- Replaces the currently used Color object with another. This
can be used to fast change all colors in a Curses::UI application.
- Curses
- Curses::UI::POE (a POE eventsystem and mainloop for
Curses::UI)
- <http://curses-ui.googlecode.com/> (SVN repo, info,
and links)
Please report any bugs or feature requests to
"
[email protected]", or through the web interface at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Curses-UI>. I will be
notified, and then you'll automatically be notified of progress on your bug as
I make changes.
Shawn Boyette "<
[email protected]>"
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::Buttonbox
- Curses::UI::Calendar
- Curses::UI::Checkbox
- Curses::UI::Label
- Curses::UI::Listbox
- Curses::UI::Menubar
- Curses::UI::MenuListbox (used by Curses::UI::Menubar)
- Curses::UI::Notebook
- Curses::UI::PasswordEntry
- Curses::UI::Popupmenu
- Curses::UI::Progressbar
- Curses::UI::Radiobuttonbox
- Curses::UI::SearchEntry (used by
Curses::UI::Searchable)
- Curses::UI::TextEditor
- Curses::UI::TextEntry
- Curses::UI::TextViewer
- Curses::UI::Window
- Curses::UI::Dialog::Basic
- Curses::UI::Dialog::Error
- Curses::UI::Dialog::Filebrowser
- Curses::UI::Dialog::Status
- Curses::UI::Widget
- Curses::UI::Container
- Curses::UI::Color
- Curses::UI::Common
- Curses::UI::Searchable