Curses::UI - A curses based OO user interface framework

Here's the obligatory Hello, world! example.

    use Curses::UI;
    my $cui = new Curses::UI;
    $cui->dialog("Hello, world!");

Curses::UI can be used for the development of curses based user interfaces. Currently, it contains the following classes:

Base elements

* Curses::UI::Widget

* Curses::UI::Container

* Curses::UI::Color

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::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

Support classes

* Curses::UI::Common

* Curses::UI::Searchable

-compat < BOOLEAN >

If the -compat option is set to a true value, the Curses::UI program will run in compatibility mode. This means that only very simple characters will be used for creating the widgets. By default this option is set to false.

-clear_on_exit < BOOLEAN >

If the -clear_on_exit option is set to a true value, a Curses::UI program will call the clear program on exit (through the DESTROY method of Curses::UI). By default this option is set to false.

-mouse_support < BOOLEAN >

If the -mouse_support option is set to a false value mouse support will be disabled. This is used to override the auto determined value and to disable mouse support.

-userdata < SCALAR >

This option specifies a user data that can be retrieved with the userdata() method. It is usefull to store application's internal data that otherwise would not be accessible in callbacks.

-color_support < BOOLEAN >

If this option is set to a true value Curses::UI will try to determine if color is available on the terminal and if so enable it.

-default_colors < BOOLEAN >

If -default_colors is set to a true value Curses::UI will try to enable color support without changing the original terminal settings.

The UI is a descendant of Curses::UI::Container, so you can use the Container methods. Here's an overview of the methods that are specific for Curses::UI.

new ( OPTIONS )

Create a new Curses::UI instance. See the OPTIONS section above to find out what options can be used.

leave_curses ( )

Temporarily leaves curses mode and recovers normal terminal mode.

reset_curses ( )

Return to curses mode after BIleave_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.

mainloop ( )

Starts a Tk like main loop that will handle input and events.

MainLoop ( )

Same as mainloop, for Tk compatibility.

schedule_event ( CODE )

The schedule_event method adds a method to the mainloop. This method is executed one time after the input handler has run and deleted from the mainloop afterwards.

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.

layout ( )

The layout method of Curses::UI will try to find out the size of the screen. After that it will call the layout routine of every contained object. So running layout on a Curses::UI object will effectively layout the complete application. Normally you will not have to call this method directly.

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.

dialog ( MESSAGE or OPTIONS )

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 => ['< Yes >','< No >'],
        -values  => [1,0],
        -title   => 'Question',
    );

    if ($yes) {
        # whatever
    }

error ( MESSAGE or OPTIONS )

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 ( OPTIONS )

The filebrowser method will create 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("Error on writing to "
                       ."\"$file\":\n$!");
    }
    }

loadfilebrowser( OPTIONS )

savefilebrowser( OPTIONS )

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 ( MESSAGE )

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 ( OPTIONS )

setprogress ( POSITION, MESSAGE )

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 (see also Curses::IU::Dialog::Progress). 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. Example:

    $cui->progress(
        -max => 10,
    -message => "Counting 10 seconds...",
    );

    for my $second (0..10) {
    $cui->setprogress($second)
    sleep 1;
    }

    $cui->noprogress;

color ( )

Returns the currently used Curses::UI::Color object

set_color ( OBJECT )

Replaces the currently used Color object with an other. This can be used to fast change all colors in a Curses::UI application.

Curses Curses::UI::Container,

see 'perldoc Curses::UI::Tutorial'

Curses::UI::POE is a POE eventsystem and mainloop for Curses::UI

Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.

Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)

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.