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.

	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