/ 
Curses-Toolkit-0.093020
/ Curses::Toolkit

NAME

Curses::Toolkit - a modern Curses toolkit

VERSION

version 0.093020

SYNOPSIS

# spawn a root window
my $root = POE::Component::Curses->spawn();
# adds some widget
$root->add_window(
    my $window = Curses::Toolkit::Widget::Window
      ->new()
      ->set_name('main_window')
      ->add_widget(
        my $button = Curses::Toolkit::Widget::Button
          ->new_with_label('Click Me to quit')
          ->set_name('my_button')
          ->signal_connect(clicked => sub { exit(0); })
      )
      ->set_coordinates(x1 => 0,   y1 => 0,
                        x2 => '100%',
                        y2 => '100%',
                       )
);

# start main loop
POE::Kernel->run();

DESCRIPTION

This module tries to be a modern curses toolkit, based on the Curses module, to build "semi-graphical" user interfaces easily.

WARNING : This is still in "beta" version, not all the features are implemented, and the API may change. However, most of the components are there, and things should not change that much in the future... Still, don't use it in production, and don't consider it stable.

Curses::Toolkit is meant to be used with a mainloop, which is not part of this module. I recommend you POE::Component::Curses, which is probably what you want. POE::Component::Curses uses Curses::Toolkit, but provides a mainloop and handles keyboard, mouse, timer and other events, whereas Curses::Toolkit is just the drawing library. See the example above. the spawn method returns a Curses::Toolkit object, which you can call methods on.

If you already have a mainloop or if you don't need it, you might want to use Curses::Toolkit directly. But again, it's probably not what you want to use. In this case you would do something like :

use Curses::Toolkit;

# using Curses::Toolkit without any event loop
my $root = Curses::Toolkit->init_root_window();
my $window = Curses::Toolkit::Widget::Window->new();
$root->add($window);
...
$root->render

WIDGETS

Curses::Toolkit is based on a widget model, inspired by Gtk. I suggest you read the pod of the following widgets :

Curses::Toolkit::Widget::Window

Use this widget to create a window. It's the first thing to do once you have a root_window

Curses::Toolkit::Widget

Useful to read, it contains the common methods of all the widgets

Curses::Toolkit::Widget::Label

To display simple text

Curses::Toolkit::Widget::Button

Simple interaction with the user

Curses::Toolkit::Widget::Entry

To input text from the user

Curses::Toolkit::Widget::VBox

To pack widgets vertically, thus building complex layouts

Curses::Toolkit::Widget::HBox

To pack widgets horizontally, thus building complex layouts

Curses::Toolkit::Widget::Border

Add a simple border around any widget

Curses::Toolkit::Widget::HPaned

To pack 2 widgets horizontally with a flexible gutter

Curses::Toolkit::Widget::VPaned

To pack 2 widgets vertically with a flexible gutter

Curses::Toolkit::Widget::HScrollBar

Not yet implemented

Curses::Toolkit::Widget::VScrollBar.pm

Not yet implemented

CLASS METHODS

init_root_window

my $root = Curses::Toolkit->init_root_window();

Initialize the Curses environment, and return an object representing it. This is not really a constructor, because you can't have more than one Curses::Toolkit object for one Curses environment. Think of it more like a service.

input  : clear_background  : optional, boolean, default 1 : if true, clears background
         theme_name        : optional, the name of them to use as default diosplay theme
         mainloop          : optional, the mainloop object that will be used for event handling
output : a Curses::Toolkit object

METHODS

get_theme_name

my $theme_name = $root_window->get_theme_name();

Return the theme associated with the root window. Typically used to get a usable default theme name. Use tha instead of hard-wiring 'Curses::Toolkit::Theme::Default'

add_event_listener

$root->add_event_listener($event_listener);

Adds an event listener to the root window. That allows the root window to respond to some events

input : a Curses::Toolkit::EventListener
output : the root window

get_event_listeners

my @listeners = $root->get_event_listener();

Returns the list of listeners connected to the root window.

input : none
output : an ARRAY of Curses::Toolkit::EventListener

get_focused_widget

my $widget = $root->get_focused_widget();

Returns the widget currently focused. Warning, the returned widget could well be a window.

input : none
output : a Curses::Toolkit::Widget or void

get_focused_window

my $window = $root->get_focused_window();

Returns the window currently focused.

input : none
output : a Curses::Toolkit::Widget::Window or void

set_mainloop

$root->set_mainloop($mainloop)

Sets the mainloop object to be used by the Curses::Toolkit root object. The mainloop object will be called when a new event has to be registered. The mainloop object is in charge to listen to the events and call $root->dispatch_event()

input  : a mainloop object
output : the Curses::Toolkit object

get_mainloop

my $mainloop = $root->get_mainloop()

Return the mainloop object associated to the root object. Might be undef if no mainloop were associated.

input : none
output : the mainloop object, or undef

get_shape

my $coordinate = $root->get_shape();

Returns a coordinate object that represents the size of the root window.

input  : none
output : a Curses::Toolkit::Object::Coordinates object

add_window

my $window = Curses::Toolkit::Widget::Window->new();
$root->add_window($window);

Adds a window on the root window. Returns the root window

input : a Curses::Toolkit::Widget::Window object
output : the root window

needs_redraw

$root->needs_redraw()

When called, signify to the root window that a redraw is needed. Has an effect only if a mainloop is active ( see POE::Component::Curses )

input : none
output : the root window

get_windows

my @windows = $root->get_windows();

Returns the list of windows loaded

input : none
output : ARRAY of Curses::Toolkit::Widget::Window

set_modal_widget

Set a widget to be modal

input  : a widget
output : the root window

unset_modal_widget

Unset the widget to be modal

input  : none
output : the root window

get_modal_widget

returns the modal widget, or void

input  : none
output : the modal widget or void

show_all

$root->show_all();

Set visibility property to true for every element. Returns the root windows

input : none
output : the root window

render

$root->render();

Build everything in the buffer. You need to call 'display' after that to display it

input : none
output : the root window

display

$root->display();

Refresh the screen.

input  : none
output : the root window

dispatch_event

my $event = Curses::Toolkit::Event::SomeEvent->new(...)
$root->dispatch_event($event);

Given an event, dispatch it to the appropriate widgets / windows, or to the root window.

input  : a Curses::Toolkit::Event
output : true if the event were handled, false if not

add_delay

Has an effect only if a mainloop is active ( see POE::Component::Curses )

$root_window->add_delay($seconds, \&code, @args)
$root_window->add_delay(5, sub { print "wow, 5 seconds wasted, dear $_[0]\n"; }, $name);

Add a timer that will execute the \&code once, in $seconds seconds. $seconds can be a fraction. @args will be passed to the code reference

input  : number of seconds
         a code reference
         an optional list of arguments to be passed to the code reference
output : a timer unique identifier or void

BUGS

Please report any bugs or feature requests to bug-curses-toolkit at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Curses-Toolkit. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Curses::Toolkit

You can also look for information at:

AUTHOR

Damien "dams" Krotkine

COPYRIGHT AND LICENSE

This software is copyright (c) 2008 by Damien "dams" Krotkine.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.