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_MAXKEYSETSIZE (BRLAPI_MAXPACKETSIZE /
22 sizeof(brlapi_keyCode_t))
23 #define brlapi__ignoreAllKeys(handle) brlapi__ignoreKeys(handle,
24 brlapi_rangeType_all, NULL, 0)
25 #define brlapi__acceptAllKeys(handle) brlapi__acceptKeys(handle,
26 brlapi_rangeType_all, NULL, 0)
27 Enumerations
29 enum brlapi_rangeType_t { brlapi_rangeType_all, brlapi_rangeType_type,
30 brlapi_rangeType_command, brlapi_rangeType_key,
31 brlapi_rangeType_code }
32 Functions
34 int BRLAPI_STDCALL brlapi_expandKeyCode (brlapi_keyCode_t code,
35 brlapi_expandedKeyCode_t *expansion)
36 int BRLAPI_STDCALL brlapi_describeKeyCode (brlapi_keyCode_t code,
37 brlapi_describedKeyCode_t *description)
38 int BRLAPI_STDCALL brlapi_readKey (int wait, brlapi_keyCode_t *code)
39 int BRLAPI_STDCALL brlapi__readKey (brlapi_handle_t *handle, int wait,
40 brlapi_keyCode_t *code)
41 int BRLAPI_STDCALL brlapi_ignoreKeys (brlapi_rangeType_t type, const
42 brlapi_keyCode_t keys[], unsigned int count)
43 int BRLAPI_STDCALL brlapi__ignoreKeys (brlapi_handle_t *handle,
44 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned
45 int count)
46 int BRLAPI_STDCALL brlapi_acceptKeys (brlapi_rangeType_t type, const
47 brlapi_keyCode_t keys[], unsigned int count)
48 int BRLAPI_STDCALL brlapi__acceptKeys (brlapi_handle_t *handle,
49 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned
50 int count)
51 int BRLAPI_STDCALL brlapi__ignoreAllKeys (brlapi_handle_t *handle)
52 int BRLAPI_STDCALL brlapi__acceptAllKeys (brlapi_handle_t *handle)
53 int BRLAPI_STDCALL brlapi_ignoreKeyRanges (brlapi_range_t ranges[],
54 unsigned int count)
55 int BRLAPI_STDCALL brlapi__ignoreKeyRanges (brlapi_handle_t *handle,
56 brlapi_range_t ranges[], unsigned int count)
57 int BRLAPI_STDCALL brlapi_acceptKeyRanges (brlapi_range_t ranges[],
58 unsigned int count)
59 int BRLAPI_STDCALL brlapi__acceptKeyRanges (brlapi_handle_t *handle,
60 brlapi_range_t ranges[], unsigned int count)
61
63 Once brlapi_enterTtyMode() has been called, the application can call
64 brlapi_readKey() to read key presses. Either key codes (see Types and
65 Defines fore BrlAPI Key Codes) or commands will be returned, depending
66 on parameters given to brlapi_enterTtyMode().
67 Key presses are buffered, so that calling brlapi_readKey() in non-
69 blocking mode from time to time should suffice.
70
72 #define brlapi__acceptAllKeys(handle) brlapi__acceptKeys(handle,
73 brlapi_rangeType_all, NULL, 0)
74 #define brlapi__ignoreAllKeys(handle) brlapi__ignoreKeys(handle,
75 brlapi_rangeType_all, NULL, 0)
76 int BRLAPI_STDCALL brlapi_acceptAllKeys(void)
77 brlapi_acceptKeys(brlapi_rangeType_all, NULL, 0)
78 Accept all key presses from the braille keyboard
79 This function asks the server to give all keys to the application, and
81 not give them to brltty.
82 Warning: after calling this function, make sure to call
84 brlapi_ignoreKeys() for ignoring important keys like
85 BRL_CMD_SWITCHVT_PREV/NEXT and such.
86 int BRLAPI_STDCALL brlapi_ignoreAllKeys(void)
88 brlapi_ignoreKeys(brlapi_rangeType_all, NULL, 0)
89 Ignore all key presses from the braille keyboard
90 This function asks the server to give all keys to brltty, rather than
92 returning them to the application via brlapi_readKey().
93 #define BRLAPI_MAXKEYSETSIZE (BRLAPI_MAXPACKETSIZE /
95 sizeof(brlapi_keyCode_t))
96 Maximum keyset size, i.e. maximum number of keys allowed in a key set
97 #define BRLAPI_UC_ROW 0x2800UL
99 Unicode braille row
100
102 enum brlapi_rangeType_t
103 types of key ranges
104 Enumerator:
106 brlapi_rangeType_all
108 all keys, code must be 0
109 brlapi_rangeType_type
111 all keys of a given type
112 brlapi_rangeType_command
114 all keys of a given command block, i.e. matching the key type
115 and command parts
116 brlapi_rangeType_key
118 a given key with any flags
119 brlapi_rangeType_code
121 a given key code
122
124 int BRLAPI_STDCALL brlapi__acceptAllKeys (brlapi_handle_t * handle)
125 int BRLAPI_STDCALL brlapi__acceptKeyRanges (brlapi_handle_t * handle,
126 brlapi_range_t ranges[], unsigned int count)
127 int BRLAPI_STDCALL brlapi__acceptKeys (brlapi_handle_t * handle,
128 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned int
129 count)
130 int BRLAPI_STDCALL brlapi__ignoreAllKeys (brlapi_handle_t * handle)
131 int BRLAPI_STDCALL brlapi__ignoreKeyRanges (brlapi_handle_t * handle,
132 brlapi_range_t ranges[], unsigned int count)
133 int BRLAPI_STDCALL brlapi__ignoreKeys (brlapi_handle_t * handle,
134 brlapi_rangeType_t type, const brlapi_keyCode_t keys[], unsigned int
135 count)
136 int BRLAPI_STDCALL brlapi__readKey (brlapi_handle_t * handle, int wait,
137 brlapi_keyCode_t * code)
138 int BRLAPI_STDCALL brlapi_acceptKeyRanges (brlapi_range_t ranges[],
139 unsigned int count)
140 Accept some key presses from the braille keyboard
141 This function asks the server to return the provided key ranges
143 (inclusive) to the application, and not give them to brltty.
144 Parameters:
146 ranges key ranges, which are inclusive
147 count number of ranges
148 Note:
150 The given codes should be raw keycodes (i.e. some driver name was
151 given to brlapi_enterTtyMode())
152 int BRLAPI_STDCALL brlapi_acceptKeys (brlapi_rangeType_t type, const
154 brlapi_keyCode_t keys[], unsigned int count)
155 Accept some key presses from the braille keyboard
156 This function asks the server to give the provided keys to the
158 application, and not give them to brltty.
159 Parameters:
161 type type of keys to be ignored
162 keys array of keys to be ignored
163 count number of keys
164 Note:
166 The given codes should be brltty commands (NULL or '' was given to
167 brlapi_enterTtyMode())
168 int BRLAPI_STDCALL brlapi_describeKeyCode (brlapi_keyCode_t code,
170 brlapi_describedKeyCode_t * description)
171 Describe the components of a key code.
172 Parameters:
174 code the keycode to be described
175 description pointer to the structure that receives the description
176 Returns:
178 0 on success, -1 on error
179 int BRLAPI_STDCALL brlapi_expandKeyCode (brlapi_keyCode_t code,
181 brlapi_expandedKeyCode_t * expansion)
182 Expand the components of a key code
183 Parameters:
185 code the key code to be expanded
186 expansion pointer to the structure that receives the components
187 Returns:
189 0 on success, -1 on error
190 int BRLAPI_STDCALL brlapi_ignoreKeyRanges (brlapi_range_t ranges[],
192 unsigned int count)
193 Ignore some key presses from the braille keyboard
194 This function asks the server to give the provided key ranges to
196 brltty, rather than returning them to the application via
197 brlapi_readKey().
198 Parameters:
200 ranges key ranges, which are inclusive
201 count number of ranges
202 Note:
204 The given codes should be raw keycodes (i.e. some driver name was
205 given to brlapi_enterTtyMode())
206 int BRLAPI_STDCALL brlapi_ignoreKeys (brlapi_rangeType_t type, const
208 brlapi_keyCode_t keys[], unsigned int count)
209 Ignore some key presses from the braille keyboard
210 This function asks the server to give the provided keys to brltty,
212 rather than returning them to the application via brlapi_readKey().
213 Parameters:
215 type type of keys to be ignored
216 keys array of keys to be ignored
217 count number of keys
218 Note:
220 The given codes should be brltty commands (NULL or '' was given to
221 brlapi_enterTtyMode())
222 int BRLAPI_STDCALL brlapi_readKey (int wait, brlapi_keyCode_t * code)
224 Read a key from the braille keyboard
225 This function returns one key press's code.
227 If NULL or '' was given to brlapi_enterTtyMode(), a brltty command is
229 returned, as described in <brltty/brldefs.h> . It is hence pretty
230 driver-independent, and should be used by default when no other option
231 is possible.
232 By default, all commands but those which restart drivers and switch
234 virtual terminals are returned to the application and not to brltty. If
235 the application doesn't want to see some command events, it should call
236 brlapi_ignoreKeys()
237 If some driver name was given to brlapi_enterTtyMode(), a raw keycode
239 is returned, as specified by the terminal driver, usually in
240 <brltty/brldefs-xy> where xy is the driver's code. It generally
241 corresponds to the very code that the terminal tells to the driver.
242 This should only be used by applications which are dedicated to a
243 particular braille terminal. Hence, checking the terminal type thanks
244 to a call to brlapi_getDriverName() before getting tty control is a
245 pretty good idea.
246 By default, all the keypresses will be passed to the client, none will
248 go through brltty, so the application will have to handle console
249 switching itself for instance.
250 Parameters:
252 wait tells whether the call should block until a key is pressed (1)
253 or should only probe key presses (0);
254 code holds the key code if a key press is indeed read.
255 Returns:
257 -1 on error or signal interrupt and *code is then undefined, 0 if
258 block was 0 and no key was pressed so far, or 1 and *code holds the
259 key code.
260 Programming hints:
262 If your application is only driven by braille command keypresses, you
264 can just call brlapi_readKey(1, &code) so that it keeps blocking,
265 waiting for keypresses.
266 Else, you'll probably want to use the file descriptor returned by
268 brlapi_openConnection() in your 'big polling loop'. For instance:
269 · in a select() loop, just add it to the readfds and exceptfds file
271 descriptor sets;
272 · in a gtk or atspi application, use
274 g_io_add_watch(fileDescriptor,G_IO_IN|G_IO_ERR|G_IO_HUP,f,data) for
275 adding a callback called f;
276 · in an Xt/Xaw/motif-based application, use
278 XtAppAddInput(app_context,fileDescriptor,XtInputReadMask|XtInputExceptMask,f,data)
279 · etc.
281 and then, when you detect inbound trafic on the file descriptor, do
283 something like this:
284 while (brlapi_readKey(0, &code) { // process keycode code // ... }
286 The while loop is needed for processing all pending key presses, else
288 some of them may be left in libbrlapi's internal key buffer and you
289 wouldn't get them immediately.
290Version 1.0 4 Jun 2007 Reading key presses(3)