# NAME
Term::Caca - perl interface for libcaca (Colour AsCii Art library)
# VERSION
version 2.0\_0
# SYNOPSIS
use Term::Caca;
my $caca = Term::Caca->new;
$caca->text( [5, 5], "pwn3d");
$caca->refresh;
sleep 3;
# DESCRIPTION
`Term::Caca` is an API for the ASCII drawing library _libcaca_.
This version of `Term::Caca` is compatible with the _1.x_ version of
the libcaca library (development has been made against version
0.99.beta17 of the library).
\# exports
# EXPORTS
use Term::Caca qw/ :all /; # import all
# or
use Term::Caca qw/ :colors /; # import specific group
# or
use Term::Caca qw/ $LIGHTRED /; # import specific constant
## COLORS
use Term::Caca qw/ :colors /; # import all colors
# or
use Term::Caca qw/ $WHITE $LIGHTRED /; # import specific colors
# or
use Term::Caca qw/ %COLORS /; # import colors as a hash
# or
print $Term::Caca::COLORS{WHITE} # use original array directly
The color constants used by `set_ansi_color()`. The available colors are
BLACK BLUE GREEN CYAN RED
MAGENTA BROWN LIGHTGRAY DARKGRAY LIGHTBLUE
LIGHTGREEN LIGHTCYAN LIGHTRED LIGHTMAGENTA YELLOW
WHITE DEFAULT TRANSPARENT
## EVENTS
use Term::Caca qw/ :events /; # import all events
# or
use Term::Caca qw/ $NO_EVENT $KEY_RELEASE /; # import specific events
# or
use Term::Caca qw/ %EVENTS /; # import events as a hash
# or
print $Term::Caca::EVENTS{MOUSE_PRESS} # use original array directly
The event constants used by the mask of `wait_for_event()`. The available
events are
NO_EVENT ANY_EVENT
KEY_PRESS KEY_RELEASE
MOUSE_PRESS MOUSE_RELEASE MOUSE_MOTION
RESIZE QUIT
# CLASS METHODS
### driver\_list
Returns an hash which keys are the available display drivers
and the values their descriptions.
### drivers
Returns the list of available drivers.
# METHODS
## Constructor
### new
Instantiates a Term::Caca object.
The optional argument _driver_ can be passed to select a specific display
driver. If it's not given, the best available driver will be used.
## Display and Canvas
### set\_title( $title )
Sets the window title to _$title_.
Returns the invocant _Term::Caca_ object.
### refresh
Refreshes the display.
Returns the invocant _Term::Caca_ object.
### set\_refresh\_delay( $seconds )
Sets the refresh delay in seconds. The refresh delay is used by
`refresh` to achieve constant framerate.
If the time is zero, constant framerate is disabled. This is the
default behaviour.
Returns the invocant _Term::Caca_ object.
### rendering\_time()
Returns the average rendering time, which is measured as the time between
two `refresh()` calls, in seconds. If constant framerate is enabled via
`set_refresh_delay()`, the average rendering time will be close to the
requested delay even if the real rendering time was shorter.
### clear()
Clears the canvas using the current background color.
Returns the invocant object.
### canvas\_size
Returns the width and height of the canvas,
as a list in an array context, as a array ref
in a scalar context.
## canvas\_width
Returns the canvas width.
### canvas\_height
Returns the canvas height.
### mouse\_position
Returns the position of the mouse. In a list context, returns
the _x_, _y_ coordinates, in a scalar context returns them as an
array ref.
This function is not reliable if the ncurses or S-Lang
drivers are being used, because mouse position is only detected when
the mouse is clicked. Other drivers such as X11 work well.
## Import/Export
### import( $drawing, :$format => 'auto' )
Imports the drawing. The supported formats are
- "auto": try to guess the format.
- "caca": native libcaca files.
- "ansi": ANSI art (CP437 charset with ANSI colour codes).
- "text": ASCII text file.
- "utf8": UTF-8 text with ANSI color codes.
### export( :$format = 'caca' )
Returns the canvas in the given format.
Supported formats are
- "caca": native libcaca files.
- "ansi": ANSI art (CP437 charset with ANSI colour codes).
- "text": ASCII text file.
- "html": an HTML page with CSS information.
- "html3": an HTML table that should be compatible with most navigators, including textmode ones.
- "irc": UTF-8 text with mIRC colour codes.
- "ps": a PostScript document.
- "svg": an SVG vector image.
- "tga": a TGA image.
## Colors
### set\_ansi\_color( $foreground, $background )
Sets the foreground and background colors used by primitives,
using colors as defined by `%COLORS`.
$t->set_ansi_color( $LIGHTRED, $WHITE );
Returns the invocant object.
### set\_color( $foreground, $background )
Sets the foreground and background colors used by primitives.
Each color is an array ref to a ARGB (transparency + RGB) set of values,
all between 0 and 15. Alternatively, they can be given as a string of the direct
hexadecimal value.
# red on white
$t->set_color( [ 15, 15, 0, 0 ], 'ffff' );
Returns the invocant object.
## Text
### text( \\@coord, $text )
Prints _$text_ at the given coordinates.
Returns the invocant `Term::Caca` object.
### char( \\@coord, $char )
Prints the character _$char_ at the given coordinates.
If _$char_ is a string of more than one character, only
the first character is printed.
Returns the invocant `Term::Caca` object.
## Primitives Drawing
### line( \\@point\_a, \\@point\_b, :$char = undef )
Draws a line from _@point\_a_ to _@point\_b_
using the character _$char_ or, if undefined,
ascii art.
Returns the invocant object.
### polyline( \\@points, :$char = undef , :$close = 0 )
Draws the polyline defined by _@points_, where each point is an array ref
of the coordinates. E.g.
$t->polyline( [ [ 0,0 ], [ 10,15 ], [ 20, 15 ] ] );
The lines are drawn using _$char_ or, if not specified, using ascii art.
If _$close_ is true, the end point of the polyline will
be connected to the first point.
Returns the invocant _Term::Caca_ object.
### circle( \\@center, $radius, :$char = '\*', :$fill = undef )
Draws a circle centered at _@center_ with a radius
of _$radius_ using the character _$char_ or, if not defined,
ascii art. if _$fill_ is set to true, the circle is filled with _$char_
as well.
If _$fill_ is defined but _$char_ is not, _$fill_ will be taken as
the filling character. I.e.,
$c->circle( [10,10], 5, char => 'x', fill => 1 );
# equivalent to
$c->circle( [10,10], 5, fill => 'x' );
Returns the invocant object.
### ellipse( \\@center, $radius\_x, $radius\_y, :$char = undef, :$fill = undef)
Draws an ellipse centered at _@center_ with an x-axis
radius of _$radius\_x_ and a y-radius of _$radius\_y_
using the character _$char_ or, if not defined, ascii art.
If _$fill_ is defined but _$char_ is not, _$fill_ will be taken as
the filling character.
Returns the invocant object.
### box( \\@top\_corner, $width, $height, :$char => undef, :$fill => undef )
Draws a rectangle of dimensions _$width_ and
_$height_ with its upper-left corner at _@top\_corner_,
using the character _$char_ or, if not defined, ascii art.
If _$fill_ is defined but _$char_ is not, _$fill_ will be taken as
the filling character.
Returns the invocant object.
### triangle( \\@point\_a, \\@point\_b, \\@point\_c, :$char => undef, :$fill => undef )
Draws a triangle defined by the three given points
using the character _$char_ or, if not defined, ascii art.
If _$fill_ is defined but _$char_ is not, _$fill_ will be taken as
the filling character.
Returns the invocant object.
## Event Handling
### wait\_for\_event( :$mask = $ANY\_EVENT, :$timeout = 0 )
Waits and returns a `Term::Caca::Event` object matching the mask.
`$timeout` is in seconds. If set to 0, the method returns immediatly and,
if no event was found, returns nothing. If `$timeout` is negative,
the method waits forever for an event matching the mask.
# wait for 5 seconds for a key press or the closing of the window
my $event = $t->wait_for_event(
mask => $KEY_PRESS | $QUIT,
timeout => 5
);
say "user is idle" unless defined $event;
exit if $event->isa( 'Term::Caca::Event::Quit' );
say "user typed ", $event->char;
# SEE ALSO
libcaca - [http://caca.zoy.org/](http://caca.zoy.org/)
[Term::Kaka](http://search.cpan.org/perldoc?Term::Kaka)
# AUTHORS
- John Beppu
- Yanick Champoux [![endorse](http://api.coderwall.com/yanick/endorsecount.png)](http://coderwall.com/yanick)
# COPYRIGHT AND LICENSE
This software is Copyright (c) 2011 by John Beppu.
This is free software, licensed under:
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE, Version 2, December 2004