1Reading key presses(3) BrlAPI Reading key presses(3)
2
6 Reading key presses - How to read key presses from the braille
7 terminal.
8 Data Structures
11 struct brlapi_expandedKeyCode_t
12 struct brlapi_describedKeyCode_t
13 struct brlapi_range_t
14 Defines
16 #define brlapi_ignoreAllKeys()
17 brlapi_ignoreKeys(brlapi_rangeType_all, NULL, 0)
18 #define brlapi_acceptAllKeys()
19 brlapi_acceptKeys(brlapi_rangeType_all, NULL, 0)
20 #define BRLAPI_UC_ROW 0x2800UL
21 #define brlapi__ignoreAllKeys(handle) brlapi__ignoreKeys(handle,
22 brlapi_rangeType_all, NULL, 0)
23 #define brlapi__acceptAllKeys(handle) brlapi__acceptKeys(handle,
24 brlapi_rangeType_all, NULL, 0)
25 Enumerations
27 enum brlapi_rangeType_t { brlapi_rangeType_all, brlapi_rangeType_type,
28 brlapi_rangeType_command, brlapi_rangeType_key,
29 brlapi_rangeType_code }
30 Functions
32 int BRLAPI_STDCALL brlapi_expandKeyCode (brlapi_keyCode_t code,
33 brlapi_expandedKeyCode_t *expansion)
34 int BRLAPI_STDCALL brlapi_describeKeyCode (brlapi_keyCode_t code,
35 brlapi_describedKeyCode_t *description)
36 int BRLAPI_STDCALL brlapi_readKey (int wait, brlapi_keyCode_t *code)
37 int BRLAPI_STDCALL brlapi__readKey (brlapi_handle_t *handle, int wait,
38 brlapi_keyCode_t *code)
39 int BRLAPI_STDCALL brlapi_ignoreKeys (brlapi_rangeType_t type, const
40 brlapi_keyCode_t keys[], unsigned int count)
41 int BRLAPI_STDCALL brlapi__ignoreKeys (brlapi_handle_t *handle,
42 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned
43 int count)
44 int BRLAPI_STDCALL brlapi_acceptKeys (brlapi_rangeType_t type, const
45 brlapi_keyCode_t keys[], unsigned int count)
46 int BRLAPI_STDCALL brlapi__acceptKeys (brlapi_handle_t *handle,
47 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned
48 int count)
49 int BRLAPI_STDCALL brlapi__ignoreAllKeys (brlapi_handle_t *handle)
50 int BRLAPI_STDCALL brlapi__acceptAllKeys (brlapi_handle_t *handle)
51 int BRLAPI_STDCALL brlapi_ignoreKeyRanges (brlapi_range_t ranges[],
52 unsigned int count)
53 int BRLAPI_STDCALL brlapi__ignoreKeyRanges (brlapi_handle_t *handle,
54 brlapi_range_t ranges[], unsigned int count)
55 int BRLAPI_STDCALL brlapi_acceptKeyRanges (brlapi_range_t ranges[],
56 unsigned int count)
57 int BRLAPI_STDCALL brlapi__acceptKeyRanges (brlapi_handle_t *handle,
58 brlapi_range_t ranges[], unsigned int count)
59
61 Once brlapi_enterTtyMode() has been called, the application can call
62 brlapi_readKey() to read key presses. Either key codes (see Types and
63 Defines fore BrlAPI Key Codes) or commands will be returned, depending
64 on parameters given to brlapi_enterTtyMode().
65 Key presses are buffered, so that calling brlapi_readKey() in non-
67 blocking mode from time to time should suffice.
68
70 #define brlapi__acceptAllKeys(handle) brlapi__acceptKeys(handle,
71 brlapi_rangeType_all, NULL, 0)
72 #define brlapi__ignoreAllKeys(handle) brlapi__ignoreKeys(handle,
73 brlapi_rangeType_all, NULL, 0)
74 int BRLAPI_STDCALL brlapi_acceptAllKeys(void)
75 brlapi_acceptKeys(brlapi_rangeType_all, NULL, 0)
76 Accept all key presses from the braille keyboard
77 This function asks the server to give all keys to the application, and
79 not give them to brltty.
80 Warning: after calling this function, make sure to call
82 brlapi_ignoreKeys() for ignoring important keys like
83 BRL_CMD_SWITCHVT_PREV/NEXT and such.
84 int BRLAPI_STDCALL brlapi_ignoreAllKeys(void)
86 brlapi_ignoreKeys(brlapi_rangeType_all, NULL, 0)
87 Ignore all key presses from the braille keyboard
88 This function asks the server to give all keys to brltty, rather than
90 returning them to the application via brlapi_readKey().
91 #define BRLAPI_UC_ROW 0x2800UL
93 Unicode braille row
94
96 enum brlapi_rangeType_t
97 types of key ranges
98 Enumerator:
100 brlapi_rangeType_all
102 all keys, code must be 0
103 brlapi_rangeType_type
105 all keys of a given type
106 brlapi_rangeType_command
108 all keys of a given command block, i.e. matching the key type
109 and command parts
110 brlapi_rangeType_key
112 a given key with any flags
113 brlapi_rangeType_code
115 a given key code
116
118 int BRLAPI_STDCALL brlapi__acceptAllKeys (brlapi_handle_t * handle)
119 int BRLAPI_STDCALL brlapi__acceptKeyRanges (brlapi_handle_t * handle,
120 brlapi_range_t ranges[], unsigned int count)
121 int BRLAPI_STDCALL brlapi__acceptKeys (brlapi_handle_t * handle,
122 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned int
123 count)
124 int BRLAPI_STDCALL brlapi__ignoreAllKeys (brlapi_handle_t * handle)
125 int BRLAPI_STDCALL brlapi__ignoreKeyRanges (brlapi_handle_t * handle,
126 brlapi_range_t ranges[], unsigned int count)
127 int BRLAPI_STDCALL brlapi__ignoreKeys (brlapi_handle_t * handle,
128 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned int
129 count)
130 int BRLAPI_STDCALL brlapi__readKey (brlapi_handle_t * handle, int wait,
131 brlapi_keyCode_t * code)
132 int BRLAPI_STDCALL brlapi_acceptKeyRanges (brlapi_range_t ranges[],
133 unsigned int count)
134 Accept some key presses from the braille keyboard
135 This function asks the server to return the provided key ranges
137 (inclusive) to the application, and not give them to brltty.
138 Parameters:
140 ranges key ranges, which are inclusive
141 count number of ranges
142 Note:
144 The given codes should be raw keycodes (i.e. some driver name was
145 given to brlapi_enterTtyMode())
146 int BRLAPI_STDCALL brlapi_acceptKeys (brlapi_rangeType_t type, const
148 brlapi_keyCode_t keys[], unsigned int count)
149 Accept some key presses from the braille keyboard
150 This function asks the server to give the provided keys to the
152 application, and not give them to brltty.
153 Parameters:
155 type type of keys to be ignored
156 keys array of keys to be ignored
157 count number of keys
158 Note:
160 The given codes should be brltty commands (NULL or '' was given to
161 brlapi_enterTtyMode())
162 int BRLAPI_STDCALL brlapi_describeKeyCode (brlapi_keyCode_t code,
164 brlapi_describedKeyCode_t * description)
165 Describe the components of a key code.
166 Parameters:
168 code the keycode to be described
169 description pointer to the structure that receives the description
170 Returns:
172 0 on success, -1 on error
173 int BRLAPI_STDCALL brlapi_expandKeyCode (brlapi_keyCode_t code,
175 brlapi_expandedKeyCode_t * expansion)
176 Expand the components of a key code
177 Parameters:
179 code the key code to be expanded
180 expansion pointer to the structure that receives the components
181 Returns:
183 0 on success, -1 on error
184 int BRLAPI_STDCALL brlapi_ignoreKeyRanges (brlapi_range_t ranges[],
186 unsigned int count)
187 Ignore some key presses from the braille keyboard
188 This function asks the server to give the provided key ranges to
190 brltty, rather than returning them to the application via
191 brlapi_readKey().
192 Parameters:
194 ranges key ranges, which are inclusive
195 count number of ranges
196 Note:
198 The given codes should be raw keycodes (i.e. some driver name was
199 given to brlapi_enterTtyMode())
200 int BRLAPI_STDCALL brlapi_ignoreKeys (brlapi_rangeType_t type, const
202 brlapi_keyCode_t keys[], unsigned int count)
203 Ignore some key presses from the braille keyboard
204 This function asks the server to give the provided keys to brltty,
206 rather than returning them to the application via brlapi_readKey().
207 Parameters:
209 type type of keys to be ignored
210 keys array of keys to be ignored
211 count number of keys
212 Note:
214 The given codes should be brltty commands (NULL or '' was given to
215 brlapi_enterTtyMode())
216 int BRLAPI_STDCALL brlapi_readKey (int wait, brlapi_keyCode_t * code)
218 Read a key from the braille keyboard
219 This function returns one key press's code.
221 If NULL or '' was given to brlapi_enterTtyMode(), a brltty command is
223 returned, as described in <brltty/brldefs.h> . It is hence pretty
224 driver-independent, and should be used by default when no other option
225 is possible.
226 By default, all commands but those which restart drivers and switch
228 virtual terminals are returned to the application and not to brltty. If
229 the application doesn't want to see some command events, it should call
230 brlapi_ignoreKeys()
231 If some driver name was given to brlapi_enterTtyMode(), a raw keycode
233 is returned, as specified by the terminal driver, usually in
234 <brltty/brldefs-xy> where xy is the driver's code. It generally
235 corresponds to the very code that the terminal tells to the driver.
236 This should only be used by applications which are dedicated to a
237 particular braille terminal. Hence, checking the terminal type thanks
238 to a call to brlapi_getDriverName() before getting tty control is a
239 pretty good idea.
240 By default, all the keypresses will be passed to the client, none will
242 go through brltty, so the application will have to handle console
243 switching itself for instance.
244 Parameters:
246 wait tells whether the call should block until a key is pressed (1)
247 or should only probe key presses (0);
248 code holds the key code if a key press is indeed read.
249 Returns:
251 -1 on error or signal interrupt and *code is then undefined, 0 if
252 block was 0 and no key was pressed so far, or 1 and *code holds the
253 key code.
254 Programming hints:
256 If your application is only driven by braille command keypresses, you
258 can just call brlapi_readKey(1, &code) so that it keeps blocking,
259 waiting for keypresses.
260 Else, you'll probably want to use the file descriptor returned by
262 brlapi_openConnection() in your 'big polling loop'. For instance:
263 · in a select() loop, just add it to the readfds and exceptfds file
265 descriptor sets;
266 · in a gtk or atspi application, use g_io_add_watch(fileDescriptor,
268 G_IO_IN|G_IO_ERR|G_IO_HUP, f, data) for adding a callback called f;
269 · in an Xt/Xaw/motif-based application, use XtAppAddInput(app_context,
271 fileDescriptor, XtInputReadMask|XtInputExceptMask, f, data)
272 · etc.
274 and then, when you detect inbound trafic on the file descriptor, do
276 something like this:
277 while (brlapi_readKey(0, &code) { // process keycode code // ... }
279 The while loop is needed for processing all pending key presses, else
281 some of them may be left in libbrlapi's internal key buffer and you
282 wouldn't get them immediately.
283 Note:
285 If the read is interrupted by a signal, brlapi_readKey() will
286 return -1, brlapi_errno will be BRLAPI_ERROR_LIBCERR and errno will
287 be EINTR.
288Version 1.0 7 Oct 2009 Reading key presses(3)