NAME
Term::Caca - perl interface for libcaca (Colour AsCii Art library)
VERSION
version 3.1.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.beta19 of the library).
EXPORTS
See Term::Caca::Constants for exportable constants.
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
title( $title )
Getter/setter for the window title.
The setter 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 an array ref.
canvas_width
Returns the canvas width.
canvas_height
Returns the canvas height.
mouse_position
Returns the position of the mouse 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 whe the mouse is clicked. Other drivers such as X11 work well.
Export
export( $format )
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.
- "irc": UTF-8 text with mIRC colour codes.
- "ps": a PostScript document.
- "svg": an SVG vector image.
- "tga": a TGA image.
If no format is provided, defaults to caca.
Colors
set_ansi_color( $foreground, $background )
Sets the foreground and background colors used by primitives, using colors as defined by the color constants.
$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
The drawing of all primitive is controlled by drawing_options. Unless specified otherwise, the possible options are:
If no option is given, or if the option thin = 1> is given, the primitive will be drawn using ascii art.
If a single character or the char = $x> pair is given, then this character it will be used to trace the primitive.
If fill = $y> is given, then that character will be used to fill the primitive.
fill and char or thin can be used in combination to produce a primitive drawn with one char and filled with the other.
line( \@point_a, \@point_b, @drawing_options )
Draws a line from @point_a to @point_b. In this instance @drawing_options only accept thin or char.
Returns the invocant object.
polyline( \@points, @drawing_options )
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 additional option close can be given as part of the drawing_options. If true, the end point of the polyline will be connected to the first point.
Returns the invocant Term::Caca object.
circle( \@center, $radius, @drawing_options )
Draws a circle centered at @center with a radius of $radius.
Returns the invocant object.
ellipse( \@center, $radius_x, $radius_y, @drawing_options )
Draws an ellipse centered at @center with an x-axis radius of $radius_x and a y-radius of $radius_y.
Returns the invocant object.
box( \@top_corner, $width, $height, @drawing_options )
Draws a rectangle of dimensions $width and $height with its upper-left corner at @top_corner.
Returns the invocant object.
triangle( \@point_a, \@point_b, \@point_c, @drawing_options )
Draws a triangle defined by the three given points.
Returns the invocant object.
Event Handling
wait_for_event( $mask, $timeout )
Waits and returns a Term::Caca::Event object matching the mask.
$timeout is in seconds. If set to 0 (the default), 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( KEY_PRESS | QUIT, 5 );
say "user is idle" unless defined $event;
exit if $event->isa( 'Term::Caca::Event::Quit' );
say "user typed ", $event->char;SEE ALSO
libcaca - https://github.com/cacalabs/libcaca and http://caca.zoy.org/
AUTHORS
John Beppu <beppu@cpan.org>
Yanick Champoux <yanick@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2019, 2018, 2013, 2011 by John Beppu.
This is free software, licensed under:
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE, Version 2, December 2004