NAME Term::Caca - perl interface for libcaca (Colour AsCii Art library) VERSION version 1.2.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 - Term::Kaka AUTHORS * John Beppu * Yanick Champoux 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