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

Last change on this file since 1105 was 1104, checked in by Sam Hocevar, 14 years ago
  • Fix enumeration layout in the manpage documentation.
  • 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 1104 2006-09-25 16:00:10Z 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 1104 2006-09-25 16:00:10Z 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 *  - \b CACA_EVENT_NONE: no other field is valid.
47 *  - \b CACA_EVENT_KEY_PRESS, \b CACA_EVENT_KEY_RELEASE: the \e data.key.ch
48 *      field is valid and contains either the ASCII value for the key, or
49 *      an \e enum \e caca_key value. If the value is a printable ASCII
50 *      character, the \e data.key.utf32 and \e data.key.utf8 fields are
51 *      also filled and contain respectively the UTF-32/UCS-4 and the UTF-8
52 *      representations of the character. Otherwise, their content is
53 *      undefined.
54 *  - \b CACA_EVENT_MOUSE_PRESS, \b CACA_EVENT_MOUSE_RELEASE: the
55 *      \e data.mouse.button field is valid and contains the index of the
56 *      mouse button that was pressed.
57 *  - \b CACA_EVENT_MOUSE_MOTION: the \e data.mouse.x and \e data.mouse.y
58 *      fields are valid and contain the mouse coordinates in character
59 *      cells.
60 *  - \b CACA_EVENT_RESIZE: the \e data.resize.w and \e data.resize.h
61 *      fields are valid and contain the new width and height values of
62 *      the \e libcucul canvas attached to \e libcaca.
63 *  - \b CACA_EVENT_QUIT: no other field is valid.
64 *
65 *  The result of accessing data members outside the above conditions is
66 *  undefined.
67 */
68struct caca_event
69{
70    enum caca_event_type
71    {
72        CACA_EVENT_NONE =          0x0000, /**< No event. */
73
74        CACA_EVENT_KEY_PRESS =     0x0001, /**< A key was pressed. */
75        CACA_EVENT_KEY_RELEASE =   0x0002, /**< A key was released. */
76        CACA_EVENT_MOUSE_PRESS =   0x0004, /**< A mouse button was pressed. */
77        CACA_EVENT_MOUSE_RELEASE = 0x0008, /**< A mouse button was released. */
78        CACA_EVENT_MOUSE_MOTION =  0x0010, /**< The mouse was moved. */
79        CACA_EVENT_RESIZE =        0x0020, /**< The window was resized. */
80        CACA_EVENT_QUIT =          0x0040, /**< The user requested to quit. */
81
82        CACA_EVENT_ANY =           0xffff  /**< Bitmask for any event. */
83    } type;
84
85    union
86    {
87        struct { unsigned int x, y, button; } mouse;
88        struct { unsigned int w, h; } resize;
89        struct { unsigned int ch; unsigned long int utf32; char utf8[8]; } key;
90    } data;
91};
92
93/** \brief Special key values.
94 *
95 *  Special key values returned by caca_get_event() for which there is no
96 *  printable ASCII equivalent.
97 */
98enum caca_key
99{
100    CACA_KEY_UNKNOWN = 0x00, /**< Unknown key. */
101
102    /* The following keys have ASCII equivalents */
103    CACA_KEY_BACKSPACE = 0x08, /**< The backspace key. */
104    CACA_KEY_TAB =       0x09, /**< The tabulation key. */
105    CACA_KEY_RETURN =    0x0d, /**< The return key. */
106    CACA_KEY_PAUSE =     0x13, /**< The pause key. */
107    CACA_KEY_ESCAPE =    0x1b, /**< The escape key. */
108    CACA_KEY_DELETE =    0x7f, /**< The delete key. */
109
110    /* The following keys do not have ASCII equivalents but have been
111     * chosen to match the SDL equivalents */
112    CACA_KEY_UP =    0x111, /**< The up arrow key. */
113    CACA_KEY_DOWN =  0x112, /**< The down arrow key. */
114    CACA_KEY_LEFT =  0x113, /**< The left arrow key. */
115    CACA_KEY_RIGHT = 0x114, /**< The right arrow key. */
116
117    CACA_KEY_INSERT =   0x115, /**< The insert key. */
118    CACA_KEY_HOME =     0x116, /**< The home key. */
119    CACA_KEY_END =      0x117, /**< The end key. */
120    CACA_KEY_PAGEUP =   0x118, /**< The page up key. */
121    CACA_KEY_PAGEDOWN = 0x119, /**< The page down key. */
122
123    CACA_KEY_F1 =  0x11a, /**< The F1 key. */
124    CACA_KEY_F2 =  0x11b, /**< The F2 key. */
125    CACA_KEY_F3 =  0x11c, /**< The F3 key. */
126    CACA_KEY_F4 =  0x11d, /**< The F4 key. */
127    CACA_KEY_F5 =  0x11e, /**< The F5 key. */
128    CACA_KEY_F6 =  0x11f, /**< The F6 key. */
129    CACA_KEY_F7 =  0x120, /**< The F7 key. */
130    CACA_KEY_F8 =  0x121, /**< The F8 key. */
131    CACA_KEY_F9 =  0x122, /**< The F9 key. */
132    CACA_KEY_F10 = 0x123, /**< The F10 key. */
133    CACA_KEY_F11 = 0x124, /**< The F11 key. */
134    CACA_KEY_F12 = 0x125, /**< The F12 key. */
135    CACA_KEY_F13 = 0x126, /**< The F13 key. */
136    CACA_KEY_F14 = 0x127, /**< The F14 key. */
137    CACA_KEY_F15 = 0x128  /**< The F15 key. */
138};
139
140/** \defgroup caca libcaca basic functions
141 *
142 *  These functions provide the basic \e libcaca routines for driver
143 *  initialisation, system information retrieval and configuration.
144 *
145 *  @{ */
146caca_display_t * caca_create_display(cucul_canvas_t *);
147int caca_free_display(caca_display_t *);
148int caca_refresh_display(caca_display_t *);
149int caca_set_display_time(caca_display_t *, unsigned int);
150unsigned int caca_get_display_time(caca_display_t *);
151unsigned int caca_get_display_width(caca_display_t *);
152unsigned int caca_get_display_height(caca_display_t *);
153int caca_set_display_title(caca_display_t *, char const *);
154/*  @} */
155
156/** \defgroup event libcaca event handling
157 *
158 *  These functions handle user events such as keyboard input and mouse
159 *  clicks.
160 *
161 *  @{ */
162int caca_get_event(caca_display_t *, unsigned int, caca_event_t *, int);
163unsigned int caca_get_mouse_x(caca_display_t *);
164unsigned int caca_get_mouse_y(caca_display_t *);
165int caca_set_mouse(caca_display_t *, int);
166/*  @} */
167
168#ifdef __cplusplus
169}
170#endif
171
172#endif /* __CACA_H__ */
Note: See TracBrowser for help on using the repository browser.