libcaca-tutorial.3caca man page

libcaca-tutorial — A libcaca tutorial First, a very simple working program, to check for basic libcaca functionalities.

#include <caca.h>

int main(void)
    caca_canvas_t *cv; caca_display_t *dp; caca_event_t ev;

    dp = caca_create_display(NULL);
    if(!dp) return 1;
    cv = caca_get_canvas(dp);

    caca_set_display_title(dp, "Hello!");
    caca_set_color_ansi(cv, CACA_BLACK, CACA_WHITE);
    caca_put_str(cv, 0, 0, "This is a message");
    caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1);

    return 0;

What does it do?

Create a display. Physically, the display is either a window or a context in a terminal (ncurses, slang) or even the whole screen (VGA).
Get the display's associated canvas. A canvas is the surface where everything happens: writing characters, sprites, strings, images... It is unavoidable. Here the size of the canvas is set by the display.
Set the display's window name (only available in windowed displays, does nothing otherwise).
Set the current canvas colours to black background and white foreground.
Write the string 'This is a message' onto the canvas, using the current colour pair.
Refresh the display, causing the text to be effectively displayed.
Wait for an event of type CACA_EVENT_KEY_PRESS.
Free the display (release memory). Since it was created together with the display, the canvas will be automatically freed as well.

You can then compile this code on an UNIX-like system using the following commans (requiring pkg-config and gcc):

gcc `pkg-config --libs --cflags caca` example.c -o example


libcaca Version 0.99.beta19 Tue Jul 19 2016