# NAME

Term::Caca - perl interface for libcaca (Colour AsCii Art library)

# VERSION

version 1.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.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

# METHODS

## Constructor

### new

Instantiates a Term::Caca object. 

## 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 <beppu@cpan.org>
- Yanick Champoux <yanick@cpan.org>

# 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