Provided by: libcurses-ui-perl_0.9609-1_all 
NAME
Curses::UI - A curses based OO user interface framework
VERSION
Version 0.9609
SYNOPSIS
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;
DESCRIPTION
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.
CONSTRUCTOR
Create a new Curses::UI object:
my $cui = Curses::UI->new( OPTIONS );
where "OPTIONS" is one or more of the following.
-clear_on_exit
If true, Curses::UI will call "clear" on exit. Defaults to false.
-color_support
If true, Curses::UI tries to enable color for the application. Defaults to false.
-compat
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.
-keydelay
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).
-mouse_support
Curses::UI attempts to auto-discover if mouse support should be enabled or not. This option allows a hard
override. Expects a boolean value.
-userdata
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.
-default_colors
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.
EVENT HANDLING METHODS
mainloop
The Curses::UI event handling loop. Call once setup is finished to "start" a C::UI program.
mainloopExit
This exits the main loop.
schedule_event
Pushes its argument (a coderef) onto the scheduled event stack
WINDOW/LAYOUT METHODS
layout
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.
CONVENIENCE DIALOG METHODS
dialog
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
}
error
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!");
filebrowser
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$!));
}
loadfilebrowser, savefilebrowser
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.
status, nostatus
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;
progress, setprogress, noprogress
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;
OTHER METHODS
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.
SEE ALSO
Curses
Curses::UI::POE (a POE eventsystem and mainloop for Curses::UI)
http://curses-ui.googlecode.com/ <http://curses-ui.googlecode.com/> (SVN repo, info, and links)
BUGS
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?Queue=Curses-UI
<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.
AUTHOR
Shawn Boyette "<mdxi@cpan.org>"
See the CREDITS file for additional information.
COPYRIGHT & LICENSE
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.
CLASS LISTING
Widgets
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
Dialogs
Curses::UI::Dialog::Basic
Curses::UI::Dialog::Error
Curses::UI::Dialog::Filebrowser
Curses::UI::Dialog::Status
Base and Support Classes
Curses::UI::Widget
Curses::UI::Container
Curses::UI::Color
Curses::UI::Common
Curses::UI::Searchable