NAME

Curses::Toolkit - a modern Curses toolkit

VERSION

version 0.100680

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

TUTORIAL

If you are new with Curses::Toolkit, I suggest you go through the tutorial. You can find it here:

Curses::Toolkit::Tutorial (not yet done!)

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, with text colors and attributes
Curses::Toolkit::Widget::Button: Simple text button widget to interact with the user
Curses::Toolkit::Widget::GenericButton: A button widget that can contain anything, not just a label
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
Curses::Toolkit::Widget::HProgressBar: An horizontal progress bar widget

For reference, here are the various hierarchy of the objects/concepts of the toolkit you might have to use :

WIDGETS HIERARCHY

This is the inheritance hierarchy of the widgets of the toolkit :

Curses::Toolkit::Widget
|
+-- Curses::Toolkit::Widget::Window
|   |
|   +-- Curses::Toolkit::Widget::Window::Dialog
|       |
|       + Curses::Toolkit::Widget::Window::Dialog::About
|
+-- Curses::Toolkit::Widget::Label
|
+-- Curses::Toolkit::Widget::Entry
|
+-- Curses::Toolkit::Widget::Scrollbar
|   |
|   +-- Curses::Toolkit::Widget::HScrollbar
|   |
|   +-- Curses::Toolkit::Widget::VScrollbar
|
+-- Curses::Toolkit::Widget::Container
    |
    +-- Curses::Toolkit::Widget::HBox
    |
    +-- Curses::Toolkit::Widget::VBox
    |
    +-- Curses::Toolkit::Widget::Paned
    |   |
    |   +-- Curses::Toolkit::Widget::HPaned
    |   |
    |   +-- Curses::Toolkit::Widget::VPaned
    |
    +-- Curses::Toolkit::Widget::Bin
        |
        +-- Curses::Toolkit::Widget::Border
            |
            +-- Curses::Toolkit::Widget::Button
            |
            +-- Curses::Toolkit::Widget::GenericButton
            |
            +-- Curses::Toolkit::Widget::ProgressBar
                |
                +-- Curses::Toolkit::Widget::HProgressBar
                |
                +-- Curses::Toolkit::Widget::VProgressBar

SIGNALS HIERARCHY

This is the inheritance hierarchy of the signals :

Curses::Toolkit::Signal
|
+-- Curses::Toolkit::Signal::Clicked
|
+-- Curses::Toolkit::Signal::Content
|   |
|   +-- Curses::Toolkit::Signal::Content::Changed
|
+-- Curses::Toolkit::Signal::Focused
    |
    +-- Curses::Toolkit::Signal::Focused::In
    |
    +-- Curses::Toolkit::Signal::Focused::Out

THEMES HIERARCHY

This is the inheritance hierarchy of the themes :

Curses::Toolkit::Theme
|
+-- Curses::Toolkit::Theme::Default
    |
    +-- Curses::Toolkit::Theme::Default::Color
    |
    +-- Curses::Toolkit::Theme::Default::Color::Pink
    |
    +-- Curses::Toolkit::Theme::Default::Color::Yellow

OBJECTS HIERARCHY

This is the list of objects of the toolkit :

Curses::Toolkit::Object
|
+-- Curses::Toolkit::Object::Coordinates
|
+-- Curses::Toolkit::Object::MarkupString
|
+-- Curses::Toolkit::Object::Shape

ROLES HIERARCHY

For now there is only one role

Curses::Toolkit::Role::Focusable

TYPES HIERARCHY

For now there is only one types class :

Curses::Toolkit::Types

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
         quit_key          : the key used to quit the whole application. Default to 'q'. If set to undef, it's disabled
         switch_key        : the key used to switch between windows. Default to 'r'. If set to undef, it's disabled
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

get_focused_window

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

Returns the next window.

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

bring_window_to_front()

$root_window->bring_window_to_front($window)

Brings the window to front

input : a Curses::Toolkit::Widget::Window
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. You probably don't want to use this method directly. Use Signals instead.

input  : a Curses::Toolkit::Event
         optional, a widget. if given, the event dispatching will start with this wisget (and not the focused one)
output : true if the event were handled, false if not

fire_event

$widget->fire_event($event, $widget);

Sends an event to the mainloop so it gets dispatched. You probably don't want to use this method.

input  : a Curses::Toolkit::Event
         optional, a widget. if given, the event dispatching will start with this wisget (and not the focused one)
output : the root_window

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:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Curses-Toolkit
CPAN Ratings

http://cpanratings.perl.org/d/Curses-Toolkit
RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Curses-Toolkit
Search CPAN

http://search.cpan.org/dist/Curses-Toolkit

AUTHOR

Damien "dams" Krotkine

COPYRIGHT AND LICENSE

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

To install Curses::Toolkit, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Curses::Toolkit

CPAN shell

perl -MCPAN -e shell
install Curses::Toolkit

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

TUTORIAL

WIDGETS

WIDGETS HIERARCHY

SIGNALS HIERARCHY

THEMES HIERARCHY

OBJECTS HIERARCHY

ROLES HIERARCHY

TYPES HIERARCHY

CLASS METHODS

init_root_window

METHODS

get_theme_name

add_event_listener

get_event_listeners

get_focused_widget

get_focused_window

get_focused_window

set_mainloop

get_mainloop

get_shape

add_window

bring_window_to_front()

needs_redraw

get_windows

set_modal_widget

unset_modal_widget

get_modal_widget

show_all

render

display

dispatch_event

fire_event

add_delay

BUGS

SUPPORT

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions