-
-
10 Aug 2013 16:15:53 UTC
- Distribution: Curses-Toolkit
- Module version: 0.211
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (3)
- Testers (107 / 22 / 0)
- Kwalitee
- 22.26% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (87.89KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- TUTORIAL
- WIDGETS
- WIDGETS HIERARCHY
- SIGNALS HIERARCHY
- THEMES HIERARCHY
- OBJECTS HIERARCHY
- ROLES HIERARCHY
- TYPES HIERARCHY
- CLASS METHODS
- 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
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
CPAN Ratings
RT: CPAN's request tracker
Search CPAN
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.
Module Install Instructions
To install Curses::Toolkit, copy and paste the appropriate command in to your terminal.
cpanm Curses::Toolkit
perl -MCPAN -e shell install Curses::Toolkit
For more information on module installation, please visit the detailed CPAN module installation guide.