NAME

Curses::Toolkit - a modern Curses toolkit

VERSION

version 0.211

SYNOPSIS

use POE::Component::Curses;
use Curses::Toolkit::Widget::Window;
use Curses::Toolkit::Widget::Button;

# 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 => '20%',   y1 => '20%',
                           x2 => '80%',   y2 => '80%', )
  );
  
  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.

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
Curses::Toolkit::Widget::HProgressBar: A vertical 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  : theme_name        : optional, the name of the theme to use as default display 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
         test_environment  : optional, a hashref, if set, Curses::Toolkit will be in test mode
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 that instead of hard-coding '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 widget (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