diff options
Diffstat (limited to 'handlekeys.h')
-rw-r--r-- | handlekeys.h | 65 |
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 | ||
6 | enum keyeventtype{ | ||
7 | HK_CSI, | ||
8 | HK_KEYS, | ||
9 | HK_MOUSE, | ||
10 | HK_RAW | ||
11 | }; | ||
12 | |||
13 | struct 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 | */ |
53 | void handle_keys(long extra, | 72 | void 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. */ |