aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/handlekeys.h
diff options
context:
space:
mode:
Diffstat (limited to 'handlekeys.h')
-rw-r--r--handlekeys.h65
1 files changed, 41 insertions, 24 deletions
diff --git a/handlekeys.h b/handlekeys.h
index 9678131..868183f 100644
--- a/handlekeys.h
+++ b/handlekeys.h
@@ -3,6 +3,21 @@
3 * Copyright 2012 David Seikel <won_fang@yahoo.com.au> 3 * Copyright 2012 David Seikel <won_fang@yahoo.com.au>
4 */ 4 */
5 5
6enum keyeventtype{
7 HK_CSI,
8 HK_KEYS,
9 HK_MOUSE,
10 HK_RAW
11};
12
13struct keyevent {
14 enum keyeventtype type; // The type of this event.
15 char *sequence; // Either a translated sequence, or raw bytes.
16 int isTranslated; // Whether or not sequence is translated.
17 int count; // Number of entries in params.
18 int *params; // For CSI events, the decoded parameters.
19};
20
6/* An input loop that handles keystrokes and terminal CSI commands. 21/* An input loop that handles keystrokes and terminal CSI commands.
7 * 22 *
8 * Reads stdin, trying to translate raw keystrokes into something more readable. 23 * Reads stdin, trying to translate raw keystrokes into something more readable.
@@ -17,42 +32,44 @@
17 * 32 *
18 * handle_keys also sets up a SIGWINCH handler to catch terminal resizes, 33 * handle_keys also sets up a SIGWINCH handler to catch terminal resizes,
19 * and sends a request to the terminal to report it's current size when it gets 34 * and sends a request to the terminal to report it's current size when it gets
20 * a SIGWINCH. This is the main reason for handle_CSI, as those reports are 35 * a SIGWINCH. This is the main reason for HK_CSI, as those reports are
21 * sent as CSI. It's still up to the user code to recognise and deal with the 36 * sent as CSI. It's still up to the user code to recognise and deal with the
22 * terminal resize response, but at least it's nicely decoded for you. 37 * terminal resize response, but at least it's nicely decoded for you.
23 * 38 *
24 * Arguments - 39 * Arguments -
25 * extra - arbitrary data that gets passed back to the callbacks. 40 * extra - arbitrary data that gets passed back to the callbacks.
26 * handle_sequence - a callback to handle keystroke sequences. 41 * handle_event - a callback to handle sequences.
27 * handle_CSI - a callback to handle terminal CSI commands. 42 *
43 * handle_event is called when a complete sequence has been accumulated. It is
44 * passed a keyevent structure. The type member of that structure determines
45 * what sort of event this is. What's in the rest of the keyevent depends on
46 * the type -
28 * 47 *
29 * handle_sequence is called when a complete keystroke sequence has been 48 * HK_CSI
30 * accumulated. The sequence argument holds the accumulated keystrokes. 49 * sequence is the fully decoded CSI command, including the private and intermediate characters.
31 * The translated argument flags if any have been translated, otherwise you 50 * isTranslated is 1, since the CSI command has been translated.
32 * can assume it's all ordinary characters. 51 * count is the count of translated CSI parameters.
52 * params is an array of translateted CSI parameters.
53 * Empty parameters are set to -1, coz -1 parameters are not legal,
54 * and empty ones should default to something that is command dependant.
33 * 55 *
34 * handle_keys should return 1 if the sequence has been dealt with, or ignored. 56 * HK_KEYS
35 * It should return 0, if handle_keys should keep adding more 57 * sequence the keystrokes as ASCII, either translated or not.
58 * isTranslated if 0, then sequence is ordinary keys, otherwise
59 * sequence is the names of keys, from the keys[] array.
60 * count and params are not used.
61 *
62 * For HK_KEYS handle_event should return 1 if the sequence has been dealt with,
63 * or ignored. It should return 0, if handle_keys should keep adding more
36 * translated keystroke sequences on the end, and try again later. 64 * translated keystroke sequences on the end, and try again later.
37 * 0 should really only be used if it's a partial match, and we need more 65 * 0 should really only be used if it's a partial match, and we need more
38 * keys in the sequence to make a full match. 66 * keys in the sequence to make a full match.
39 * 67 *
40 * handle_CSI is called when a complete terminal CSI command has been 68 * HK_MOUSE
41 * detected. The command argument is the full CSI command code, including 69 * sequence is the raw bytes of the mouse report. The rest are not used.
42 * private and intermediate characters. The params argument is the decoded 70 *
43 * parameters from the command. The count argument is the number of decoded
44 * parameters. Empty parameters are set to -1, coz -1 parameters are not legal,
45 * and empty ones should default to something that is command dependant.
46 *
47 * NOTE - handle_CSI differs from handle_sequence in not having to
48 * return anything. CSI sequences include a definite terminating byte,
49 * so no need for this callback to tell handle_keys to keep accumulating.
50 * Some applications use a series of keystrokes for things, so they
51 * get accumulated until fully recognised by the user code.
52 */ 71 */
53void handle_keys(long extra, 72void handle_keys(long extra, int (*handle_event)(long extra, struct keyevent *event));
54 int (*handle_sequence)(long extra, char *sequence, int isTranslated),
55 void (*handle_CSI)(long extra, char *command, int *params, int count));
56 73
57 74
58/* Call this when you want handle_keys to return. */ 75/* Call this when you want handle_keys to return. */