Damien Krotkine > Curses-Toolkit-0.211 > Curses::Toolkit

Download:
Curses-Toolkit-0.211.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  1
Open  2
View/Report Bugs
Module Version: 0.211   Source  

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:

AUTHOR ^

Damien "dams" Krotkine

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2011 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.

syntax highlighting: