source: libcaca/trunk/doc/tutorial.dox @ 1279

Last change on this file since 1279 was 1279, checked in by Jean-Yves Lamoureux, 13 years ago
  • Started a real and complete tutorial
  • Property svn:keywords set to Id
File size: 2.7 KB
Line 
1/* $Id: tutorial.dox 1279 2006-11-05 18:14:26Z jylam $ */
2
3/** \page tutorial A libcucul and libcaca tutorial
4
5 Before writing your first libcaca application, you need to know the difference between libcucul and libcaca :
6- libcucul is the text rendering library. It will do all the work you actually need. From imports (text, ANSI, caca internal format, all of this supporting n-bytes unicode), to exports (sames formats, adding SVG, PostScript, TGA, HTML (both 3 and 4), IRC), it'll cover all your needs.
7- libcaca handle everything that can be hardware related. It includes display (RAW, X11, OpenGL, Windows (GDI), conio (DOS), ncurses, slang, text VGA (IMB-Compatible)), keyboard (same drivers but RAW), mouse (same drivers but RAW and VGA), time and resize events (on windowed drivers).
8
9So, you can write a libcucul only program, but you <b>can't</b> write a libcaca only program, it'll be nonsense. Period.
10
11
12First, a working program, very simple, to check you can compile and run it :
13
14\code
15
16#include <cucul.h>
17#include <caca.h>
18
19int main(void)
20{
21    /* Initialise libcaca */
22    cucul_canvas_t *cv; caca_display_t *dp; caca_event_t ev;
23    cv = cucul_create_canvas(0, 0);
24    dp = caca_create_display(cv);
25    /* Set window title */
26    caca_set_display_title(dp, "Hello!");
27    /* Choose drawing colours */
28    cucul_set_color(cv, CUCUL_COLOR_BLACK, CUCUL_COLOR_WHITE);
29    /* Draw a string at coordinates (0, 0) */
30    cucul_putstr(cv, 0, 0, "This is a message");
31    /* Refresh display */
32    caca_refresh_display(dp);
33    /* Wait for a key press event */
34    caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1);
35    /* Clean up library */
36    caca_free_display(dp);
37    cucul_free_canvas(cv);
38
39    return 0;
40}
41
42\endcode
43
44
45What does it do ? (we skip variable definitions, guessing you have a brain) :
46- Create a cucul canvas. A canvas is where everything happens. Writing characters, sprites, strings, images, everything. It is mandatory and is the reason for libcuculs' 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.
47
48- 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).
49
50- Set the window name of our display (only available in windowed displays, does nothing otherwise). (so this is libcaca related)
51 
52- Set current colors to black background, and white foreground of our canvas (so this is libcucul related)
53
54- Put a string "This is a message" with current colors in our libcucul canvas.
55
56- Refresh our caca display, whish was firstly attached to our canvas
57
58- Wait for an event of type "CACA_EVENT_KEY_PRESS", which seems obvious.
59
60- Free display (release memory)
61
62- Free canvas (release memory and close window if any)
63
64
65*/
Note: See TracBrowser for help on using the repository browser.