/ 
Curses-UI-0.71
River stage two • 20 direct dependents • 20 total dependents
/ Curses::UI

NAME

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

SYNOPSIS

Here's the obligatory "Hello, world!" example.

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

DESCRIPTION

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

Base elements

Widgets

Dialogs

Support classes

OPTIONS

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

METHODS

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.

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.

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;

SEE ALSO

Curses Curses::UI::Container,

BASIC TUTORIAL

First requirements

Any perl program that uses Curses::UI needs to include "use Curses::UI". A program should also use "use strict" and the -w switch to ensure the program is working without common errors (but of course Curses::UI will work without them). After that an instance of Curses::UI must be created. From now on, this instance will be called "the UI".

#!/usr/bin/perl -w

use strict;
use Curses::UI;
my $cui = new Curses::UI;

Create windows

After the initialization has been done, windows can be added to the UI. You will always have to do this. It is not possible to add widgets to the UI directly. Here is an example that creates a window with a title and a border, which has a padding of 2 (For the explanation of $cui->add, see the Curses::UI::Container manual page).

my $win1 = $cui->add(
    'win1', 'Window',
    -border => 1,
    -title => 'My first Curses::UI window!',
    -pad => 2,
);

Well... that's fun! Let's add another window! And let's give it more padding, so that the window is smaller than the previous one.

my $win2 = $cui->add(
    'win2', 'Window',
    -border => 1,
    -title => 'My second Curses::UI window!',
    -pad => 6,
);

Add some widgets

Now that we have a couple of windows, we can add widgets to them. We'll add a popupmenu and some buttons to the first window.

my $popup = $win1->add(
    'popup', 'Popupmenu',
    -x => 2,
    -y => 2,
    -sbborder => 1, 
    -values => [ 1, 2, 3, 4, 5 ],
    -labels => {
        1 => 'One', 
        2 => 'Two', 
        3 => 'Three', 
        4 => 'Four', 
        5 => 'Five', 
    },
);

my $but1 = $win1->add(
    'buttons', 'Buttonbox',
    -x => 2,
    -y => 4,
    -buttons => [
        { -label => '< goto window 2 >', -value => 'goto2' },
        { -label => '< Quit >', -value => 'quit' },
    ],
);

We'll add a texteditor and some buttons to the second window. Look how we can use padding to do some basic layouting. We do not specifiy the with and height of the TextEditor widget, so the widget will stretch out itself as far as possible. But because of the -padbottom option, it will leave some space to put the buttons. By specifying a negative -y offset for the buttons, we have a scalable application. Resize the screen and the widgets will follow!

my $editor = $win2->add(
    'editor', 'TextEditor',
    -border => 1,
    -vscrollbar => 1,
    -wrapping => 1,
    -x => 2,
    -y => 1,
    -padright => 2,
    -padbottom => 3,
);

my $but2 = $win2->add(
    'buttons', 'Buttonbox',
    -x => 2,
    -y => -2,
    -buttons => [
        { -label => '< goto window 1 >', -value => 'goto1' },
        { -label => '< Quit >', -value => 'quit' },
    ],
);

Specify when the windows will loose their focus

We have a couple of buttons on each window. As soon as a button is pressed, it will have the window loose its focus (buttons will have any kind of Container object loose its focus). You will only have to do something if this is not the desired behaviour.

If you want the buttons themselves to loose focus if pressed, then change its routine for the "return" binding from "LEAVE_CONTAINER" to "LOOSE_FOCUS". Example:

$but1->set_routine('loose-focus', 'LOOSE_FOCUS');

To make things a bit more snappy, we want to add some shortcut keys to the appliction:

CTRL+Q : Quit the application
CTRL+N : Go to the next window

This can be done by assigning "returnkeys" to a window. Each widget in the window will get extra keybindings to have the window loose its focus if one of the returnkeys is pressed. For our application we can set the desired shortcut keys like this:

$win1->returnkeys("\cN", "\cQ");
$win2->returnkeys("\cN", "\cQ");

From now on both windows will loose focus if either CTRL+Q or CTRL+N is pressed. Important: make sure that returnkeys are assigned to a window _after_ all windgets have been added.

The main loop

Now that we have constructed the windows and some widgets on them, we will have to make things work like they should.

MAINLOOP: for(;;) {
    WINDOW: foreach my $win_id ('win1','win2') {
        # Bring the current window on top
        $cui->ontop($win_id);

        # Get the window object.
        my $win = $cui->getobj($win_id);

        # Bring the focus to this window. Focus routines
        # will return a returnvalue (which is always
        # "LEAVE_CONTAINER" for a Container object) and
        # the last key that was pressed.
        my ($returnvalue, $lastkey) = $win->focus;

        # First check if the $lastkey is one of the
        # shortcut keys we created using returnkeys().
        if ($lastkey eq "\cN") {
            next WINDOW;
    } elsif ($lastkey eq "\cQ") {
            last MAINLOOP;
        }

        # Nope. Then we can assume that a button
        # was pressed. Check which button it was.

        # First get the button object of the focused window.
        my $btn = $win->getobj('buttons');

        # Get the index of the pressed button.
        my $button_value = $btn->get;

        # If the $button_value is 'quit', the Quit button 
        # was pressed.
        last MAINLOOP if $button_value eq 'quit';
    }
}

Add a good-bye dialog

Curses::UI has a couple of methods that are easy for showing dialogs (see the METHODS section below). We'll use a dialogbox to say goodbye to the user of our program. After the mainloop we add:

$cui->dialog("Bye bye!");

You're done!

We have built a genuine Curses::UI application! Not that it is a very useful one, but who cares? Now try out if it works like you think it should. The complete source code of this application can be found in the examples directory of the distribution (examples/demo-Curses::UI).

AUTHOR

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

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.