aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/src/handlekeys.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/handlekeys.h')
-rw-r--r--src/handlekeys.h76
1 files changed, 76 insertions, 0 deletions
diff --git a/src/handlekeys.h b/src/handlekeys.h
new file mode 100644
index 0000000..868183f
--- /dev/null
+++ b/src/handlekeys.h
@@ -0,0 +1,76 @@
1/* handlekeys.h - Generic terminal input handler.
2 *
3 * Copyright 2012 David Seikel <won_fang@yahoo.com.au>
4 */
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
21/* An input loop that handles keystrokes and terminal CSI commands.
22 *
23 * Reads stdin, trying to translate raw keystrokes into something more readable.
24 * See the keys[] array at the top of handlekeys.c for what byte sequences get
25 * translated into what key names. See dumbsh.c for an example of usage.
26 * A 0.1 second delay is used to detect the Esc key being pressed, and not Esc
27 * being part of a raw keystroke.
28 *
29 * handle_keys also tries to decode CSI commands that terminals can send.
30 * Some keystrokes are CSI commands, but those are translated as key sequences
31 * instead of CSI commands.
32 *
33 * handle_keys also sets up a SIGWINCH handler to catch terminal resizes,
34 * and sends a request to the terminal to report it's current size when it gets
35 * a SIGWINCH. This is the main reason for HK_CSI, as those reports are
36 * sent as CSI. It's still up to the user code to recognise and deal with the
37 * terminal resize response, but at least it's nicely decoded for you.
38 *
39 * Arguments -
40 * extra - arbitrary data that gets passed back to the callbacks.
41 * handle_event - a callback to handle sequences.
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 -
47 *
48 * HK_CSI
49 * sequence is the fully decoded CSI command, including the private and intermediate characters.
50 * isTranslated is 1, since the CSI command has been translated.
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.
55 *
56 * HK_KEYS
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
64 * translated keystroke sequences on the end, and try again later.
65 * 0 should really only be used if it's a partial match, and we need more
66 * keys in the sequence to make a full match.
67 *
68 * HK_MOUSE
69 * sequence is the raw bytes of the mouse report. The rest are not used.
70 *
71 */
72void handle_keys(long extra, int (*handle_event)(long extra, struct keyevent *event));
73
74
75/* Call this when you want handle_keys to return. */
76void handle_keys_quit();