Curses::Toolkit - a modern Curses toolkit
version 0.203
# 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();
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.
spawn
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
If you are new with Curses::Toolkit, I suggest you go through the tutorial. You can find it here:
Curses::Toolkit
Curses::Toolkit::Tutorial (not yet done!)
Curses::Toolkit is based on a widget model, inspired by Gtk. I suggest you read the POD of the following widgets :
Use this widget to create a window. It's the first thing to do once you have a root_window
Useful to read, it contains the common methods of all the widgets
To display simple text, with text colors and attributes
Simple text button widget to interact with the user
A button widget that can contain anything, not just a label
To input text from the user
To pack widgets vertically, thus building complex layouts
To pack widgets horizontally, thus building complex layouts
Add a simple border around any widget
To pack 2 widgets horizontally with a flexible gutter
To pack 2 widgets vertically with a flexible gutter
Not yet implemented
An horizontal progress bar widget
A vertical progress bar widget
For reference, here are the various hierarchy of the objects/concepts of the toolkit you might have to use :
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
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
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
This is the list of objects of the toolkit :
Curses::Toolkit::Object | +-- Curses::Toolkit::Object::Coordinates | +-- Curses::Toolkit::Object::MarkupString | +-- Curses::Toolkit::Object::Shape
For now there is only one role
Curses::Toolkit::Role::Focusable
For now there is only one types class :
Curses::Toolkit::Types
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 them 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 output : a Curses::Toolkit object
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'
$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
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
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
my $window = $root->get_focused_window();
Returns the window currently focused.
input : none output : a Curses::Toolkit::Widget::Window or void
my $window = $root->get_nexd_window();
Returns the next window.
$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
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
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
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
$root_window->bring_window_to_front($window)
Brings the window to front
input : a Curses::Toolkit::Widget::Window output : the root window
$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
my @windows = $root->get_windows();
Returns the list of windows loaded
input : none output : ARRAY of Curses::Toolkit::Widget::Window
Set a widget to be modal
input : a widget output : the root window
Unset the widget to be modal
returns the modal widget, or void
input : none output : the modal widget or void
$root->show_all();
Set visibility property to true for every element. Returns the root windows
$root->render();
Build everything in the buffer. You need to call 'display' after that to display it
$root->display();
Refresh the screen.
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
$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
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
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.
bug-curses-toolkit at rt.cpan.org
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
Damien "dams" Krotkine
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.
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.