source: libcaca/trunk/caca/caca.h @ 906

Last change on this file since 906 was 824, checked in by Sam Hocevar, 17 years ago
  • Documentation improvements. Wrote a small migration guide and added the skeleton of a tutorial for Jylam.
  • Property svn:keywords set to Id
File size: 6.1 KB
Line 
1/*
2 *  libcaca       Colour ASCII-Art library
3 *  Copyright (c) 2002-2006 Sam Hocevar <sam@zoy.org>
4 *                All Rights Reserved
5 *
6 *  $Id: caca.h 824 2006-04-21 18:03:22Z sam $
7 *
8 *  This library is free software; you can redistribute it and/or
9 *  modify it under the terms of the Do What The Fuck You Want To
10 *  Public License, Version 2, as published by Sam Hocevar. See
11 *  http://sam.zoy.org/wtfpl/COPYING for more details.
12 */
13
14/** \file caca.h
15 *  \version \$Id: caca.h 824 2006-04-21 18:03:22Z sam $
16 *  \author Sam Hocevar <sam@zoy.org>
17 *  \brief The \e libcaca public header.
18 *
19 *  This header contains the public types and functions that applications
20 *  using \e libcaca may use.
21 */
22
23#ifndef __CACA_H__
24#define __CACA_H__
25
26/** libcaca API version */
27#define CACA_API_VERSION_1
28
29#include <cucul.h>
30
31#ifdef __cplusplus
32extern "C"
33{
34#endif
35
36/** \e libcaca context */
37typedef struct caca_display caca_display_t;
38/** event structure */
39typedef struct caca_event caca_event_t;
40
41/** \brief User events.
42 *
43 *  This structure is filled by caca_get_event() when an event is received.
44 *  The \e type field is always valid. The validity of the \e data union
45 *  depends on the value of the \e type field:
46 *
47 *  \li \b CACA_EVENT_NONE: no other field is valid.
48 *
49 *  \li \b CACA_EVENT_KEY_PRESS, \b CACA_EVENT_KEY_RELEASE: the \e data.key.ch
50 *      field is valid and contains either the ASCII value for the key, or
51 *      an \e enum \e caca_key value. If the value is a printable ASCII
52 *      character, the \e data.key.ucs4 and \e data.key.utf8 fields are
53 *      also filled and contain respectively the UCS-4/UTF-32 and the UTF-8
54 *      representations of the character. Otherwise, their content is
55 *      undefined.
56 *
57 *  \li \b CACA_EVENT_MOUSE_PRESS, \b CACA_EVENT_MOUSE_RELEASE: the
58 *      \e data.mouse.button field is valid and contains the index of the
59 *      mouse button that was pressed.
60 *
61 *  \li \b CACA_EVENT_MOUSE_MOTION: the \e data.mouse.x and \e data.mouse.y
62 *      fields are valid and contain the mouse coordinates in character
63 *      cells.
64 *
65 *  \li \b CACA_EVENT_RESIZE: the \e data.resize.w and \e data.resize.h
66 *      fields are valid and contain the new width and height values of
67 *      the \e libcucul canvas attached to \e libcaca.
68 *
69 *  \li \b CACA_EVENT_QUIT: no other field is valid.
70 *
71 *  The result of accessing data members outside the above conditions is
72 *  undefined.
73 */
74struct caca_event
75{
76    enum caca_event_type
77    {
78        CACA_EVENT_NONE =          0x0000, /**< No event. */
79
80        CACA_EVENT_KEY_PRESS =     0x0001, /**< A key was pressed. */
81        CACA_EVENT_KEY_RELEASE =   0x0002, /**< A key was released. */
82        CACA_EVENT_MOUSE_PRESS =   0x0004, /**< A mouse button was pressed. */
83        CACA_EVENT_MOUSE_RELEASE = 0x0008, /**< A mouse button was released. */
84        CACA_EVENT_MOUSE_MOTION =  0x0010, /**< The mouse was moved. */
85        CACA_EVENT_RESIZE =        0x0020, /**< The window was resized. */
86        CACA_EVENT_QUIT =          0x0040, /**< The user requested to quit. */
87
88        CACA_EVENT_ANY =           0xffff  /**< Bitmask for any event. */
89    } type;
90
91    union
92    {
93        struct { unsigned int x, y, button; } mouse;
94        struct { unsigned int w, h; } resize;
95        struct { unsigned int ch; unsigned long int ucs4; char utf8[8]; } key;
96    } data;
97};
98
99/** \brief Special key values.
100 *
101 *  Special key values returned by caca_get_event() for which there is no
102 *  ASCII equivalent.
103 */
104enum caca_key
105{
106    CACA_KEY_UNKNOWN = 0x00, /**< Unknown key. */
107
108    /* The following keys have ASCII equivalents */
109    CACA_KEY_BACKSPACE = 0x08, /**< The backspace key. */
110    CACA_KEY_TAB =       0x09, /**< The tabulation key. */
111    CACA_KEY_RETURN =    0x0d, /**< The return key. */
112    CACA_KEY_PAUSE =     0x13, /**< The pause key. */
113    CACA_KEY_ESCAPE =    0x1b, /**< The escape key. */
114    CACA_KEY_DELETE =    0x7f, /**< The delete key. */
115
116    /* The following keys do not have ASCII equivalents but have been
117     * chosen to match the SDL equivalents */
118    CACA_KEY_UP =    0x111, /**< The up arrow key. */
119    CACA_KEY_DOWN =  0x112, /**< The down arrow key. */
120    CACA_KEY_LEFT =  0x113, /**< The left arrow key. */
121    CACA_KEY_RIGHT = 0x114, /**< The right arrow key. */
122
123    CACA_KEY_INSERT =   0x115, /**< The insert key. */
124    CACA_KEY_HOME =     0x116, /**< The home key. */
125    CACA_KEY_END =      0x117, /**< The end key. */
126    CACA_KEY_PAGEUP =   0x118, /**< The page up key. */
127    CACA_KEY_PAGEDOWN = 0x119, /**< The page down key. */
128
129    CACA_KEY_F1 =  0x11a, /**< The F1 key. */
130    CACA_KEY_F2 =  0x11b, /**< The F2 key. */
131    CACA_KEY_F3 =  0x11c, /**< The F3 key. */
132    CACA_KEY_F4 =  0x11d, /**< The F4 key. */
133    CACA_KEY_F5 =  0x11e, /**< The F5 key. */
134    CACA_KEY_F6 =  0x11f, /**< The F6 key. */
135    CACA_KEY_F7 =  0x120, /**< The F7 key. */
136    CACA_KEY_F8 =  0x121, /**< The F8 key. */
137    CACA_KEY_F9 =  0x122, /**< The F9 key. */
138    CACA_KEY_F10 = 0x123, /**< The F10 key. */
139    CACA_KEY_F11 = 0x124, /**< The F11 key. */
140    CACA_KEY_F12 = 0x125, /**< The F12 key. */
141    CACA_KEY_F13 = 0x126, /**< The F13 key. */
142    CACA_KEY_F14 = 0x127, /**< The F14 key. */
143    CACA_KEY_F15 = 0x128  /**< The F15 key. */
144};
145
146/** \defgroup caca libcaca basic functions
147 *
148 *  These functions provide the basic \e libcaca routines for driver
149 *  initialisation, system information retrieval and configuration.
150 *
151 *  @{ */
152caca_display_t * caca_create_display(cucul_canvas_t *);
153void caca_free_display(caca_display_t *);
154void caca_set_delay(caca_display_t *, unsigned int);
155void caca_refresh_display(caca_display_t *);
156unsigned int caca_get_rendertime(caca_display_t *);
157unsigned int caca_get_display_width(caca_display_t *);
158unsigned int caca_get_display_height(caca_display_t *);
159int caca_set_display_title(caca_display_t *, char const *);
160/*  @} */
161
162/** \defgroup event libcaca event handling
163 *
164 *  These functions handle user events such as keyboard input and mouse
165 *  clicks.
166 *
167 *  @{ */
168int caca_get_event(caca_display_t *, unsigned int, caca_event_t *, int);
169unsigned int caca_get_mouse_x(caca_display_t *);
170unsigned int caca_get_mouse_y(caca_display_t *);
171void caca_set_mouse(caca_display_t *, int);
172/*  @} */
173
174#ifdef __cplusplus
175}
176#endif
177
178#endif /* __CACA_H__ */
Note: See TracBrowser for help on using the repository browser.