Ignore:
Timestamp:
Oct 6, 2008, 9:33:15 PM (11 years ago)
Author:
Sam Hocevar
Message:

doc: rewrite the tutorial to reflect recent API updates.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • libcaca/trunk/doc/tutorial.dox

    r2824 r2879  
    33/** \page libcaca-tutorial A libcaca tutorial
    44
    5 First, a working program, very simple, to check you can compile and run it:
     5First, a very simple working program, to check for basic libcaca
     6functionalities.
    67
    78\code
    89
    910#include <caca.h>
    10 #include <caca.h>
    1111
    1212int main(void)
    1313{
    14     /* Initialise libcaca */
    1514    caca_canvas_t *cv; caca_display_t *dp; caca_event_t ev;
     15
    1616    dp = caca_create_display(NULL);
    1717    if(!dp) return 1;
    1818    cv = caca_get_canvas(dp);
    19     /* Set window title */
     19
    2020    caca_set_display_title(dp, "Hello!");
    21     /* Choose drawing colours */
    2221    caca_set_color_ansi(cv, CACA_BLACK, CACA_WHITE);
    23     /* Draw a string at coordinates (0, 0) */
    2422    caca_put_str(cv, 0, 0, "This is a message");
    25     /* Refresh display */
    2623    caca_refresh_display(dp);
    27     /* Wait for a key press event */
    2824    caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1);
    29     /* Clean up library */
    3025    caca_free_display(dp);
    3126
     
    3530\endcode
    3631
     32What does it do?
     33 - Create a display. Physically, the display is either a window or a context
     34   in a terminal (ncurses, slang) or even the whole screen (VGA).
     35 - Get the display's associated canvas. A canvas is the surface where
     36   everything happens: writing characters, sprites, strings, images... It is
     37   unavoidable. Here the size of the canvas is set by the display.
     38 - Set the display's window name (only available in windowed displays, does
     39   nothing otherwise).
     40 - Set the current canvas colours to black background and white foreground.
     41 - Write the string "This is a message" using the current colors onto the
     42   canvas.
     43 - Refresh the display.
     44 - Wait for an event of type "CACA_EVENT_KEY_PRESS".
     45 - Free the display (release memory). Since it was created together with the
     46   display, the canvas will be automatically freed as well.
    3747
    38 What does it do ? (we skip variable definitions, guessing you have a brain) :
    39 - Create a caca canvas. A canvas is where everything happens. Writing characters, sprites, strings, images, everything. It is mandatory and is the reason of libcacas' beeing. Size is there a width of 0 pixels, and a height of 0 pixels. It'll be resized according to contents you put in it.
    40 
    41 - Create a caca display. This is basically the window. Physically it can be a window (most of the displays), a console (ncurses, slang) or a real display (VGA).
    42 
    43 - Set the window name of our display (only available in windowed displays, does nothing otherwise). (so this is libcaca related)
    44  
    45 - Set current colors to black background, and white foreground of our canvas (so this is libcaca related)
    46 
    47 - Put a string "This is a message" with current colors in our libcaca canvas.
    48 
    49 - Refresh our caca display, whish was firstly attached to our canvas
    50 
    51 - Wait for an event of type "CACA_EVENT_KEY_PRESS", which seems obvious.
    52 
    53 - Free display (release memory)
    54 
    55 - Free canvas (release memory and close window if any)
    56 
    57 
    58 You can then compile this code under UNIX-like systems with following command : (you'll need pkg-config and gcc)
     48You can then compile this code on an UNIX-like system using the following
     49comman (requiring pkg-config and gcc):
    5950\code
    6051gcc `pkg-config --libs --cflags caca` example.c -o example
Note: See TracChangeset for help on using the changeset viewer.