.TH "libcaca-tutorial" 3caca "Sat Apr 6 2019" "Version 0.99.beta19" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libcaca-tutorialA libcaca tutorial 
 \- First, a very simple working program, to check for basic libcaca functionalities\&.
.PP
.PP
.nf
#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_refresh_display(dp);
    caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1);
    caca_free_display(dp);

    return 0;
}
.fi
.PP
.PP
What does it do?
.IP "\(bu" 2
Create a display\&. Physically, the display is either a window or a context in a terminal (ncurses, slang) or even the whole screen (VGA)\&.
.IP "\(bu" 2
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\&.
.IP "\(bu" 2
Set the display's window name (only available in windowed displays, does nothing otherwise)\&.
.IP "\(bu" 2
Set the current canvas colours to black background and white foreground\&.
.IP "\(bu" 2
Write the string \fC'This is a message'\fP onto the canvas, using the current colour pair\&.
.IP "\(bu" 2
Refresh the display, causing the text to be effectively displayed\&.
.IP "\(bu" 2
Wait for an event of type \fCCACA_EVENT_KEY_PRESS\fP\&.
.IP "\(bu" 2
Free the display (release memory)\&. Since it was created together with the display, the canvas will be automatically freed as well\&.
.PP
.PP
You can then compile this code on an UNIX-like system using the following commans (requiring \fCpkg-config\fP and \fCgcc\fP): 
.PP
.nf
gcc `pkg-config --libs --cflags caca` example\&.c -o example

.fi
.PP