1// Copyright 2016 The TCell Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use file except in compliance with the License.
5// You may obtain a copy of the license at
6//
7//    http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15package tcell
16
17import (
18	"fmt"
19	"strings"
20	"time"
21)
22
23// EventKey represents a key press.  Usually this is a key press followed
24// by a key release, but since terminal programs don't have a way to report
25// key release events, we usually get just one event.  If a key is held down
26// then the terminal may synthesize repeated key presses at some predefined
27// rate.  We have no control over that, nor visibility into it.
28//
29// In some cases, we can have a modifier key, such as ModAlt, that can be
30// generated with a key press.  (This usually is represented by having the
31// high bit set, or in some cases, by sending an ESC prior to the rune.)
32//
33// If the value of Key() is KeyRune, then the actual key value will be
34// available with the Rune() method.  This will be the case for most keys.
35// In most situations, the modifiers will not be set.  For example, if the
36// rune is 'A', this will be reported without the ModShift bit set, since
37// really can't tell if the Shift key was pressed (it might have been CAPSLOCK,
38// or a terminal that only can send capitals, or keyboard with separate
39// capital letters from lower case letters).
40//
41// Generally, terminal applications have far less visibility into keyboard
42// activity than graphical applications.  Hence, they should avoid depending
43// overly much on availability of modifiers, or the availability of any
44// specific keys.
45type EventKey struct {
46	t   time.Time
47	mod ModMask
48	key Key
49	ch  rune
50}
51
52// When returns the time when this Event was created, which should closely
53// match the time when the key was pressed.
54func (ev *EventKey) When() time.Time {
55	return ev.t
56}
57
58// Rune returns the rune corresponding to the key press, if it makes sense.
59// The result is only defined if the value of Key() is KeyRune.
60func (ev *EventKey) Rune() rune {
61	return ev.ch
62}
63
64// Key returns a virtual key code.  We use this to identify specific key
65// codes, such as KeyEnter, etc.  Most control and function keys are reported
66// with unique Key values.  Normal alphanumeric and punctuation keys will
67// generally return KeyRune here; the specific key can be further decoded
68// using the Rune() function.
69func (ev *EventKey) Key() Key {
70	return ev.key
71}
72
73// Modifiers returns the modifiers that were present with the key press.  Note
74// that not all platforms and terminals support this equally well, and some
75// cases we will not not know for sure.  Hence, applications should avoid
76// using this in most circumstances.
77func (ev *EventKey) Modifiers() ModMask {
78	return ev.mod
79}
80
81// KeyNames holds the written names of special keys. Useful to echo back a key
82// name, or to look up a key from a string value.
83var KeyNames = map[Key]string{
84	KeyEnter:          "Enter",
85	KeyBackspace:      "Backspace",
86	KeyTab:            "Tab",
87	KeyBacktab:        "Backtab",
88	KeyEsc:            "Esc",
89	KeyBackspace2:     "Backspace2",
90	KeyDelete:         "Delete",
91	KeyInsert:         "Insert",
92	KeyUp:             "Up",
93	KeyDown:           "Down",
94	KeyLeft:           "Left",
95	KeyRight:          "Right",
96	KeyHome:           "Home",
97	KeyEnd:            "End",
98	KeyUpLeft:         "UpLeft",
99	KeyUpRight:        "UpRight",
100	KeyDownLeft:       "DownLeft",
101	KeyDownRight:      "DownRight",
102	KeyCenter:         "Center",
103	KeyPgDn:           "PgDn",
104	KeyPgUp:           "PgUp",
105	KeyClear:          "Clear",
106	KeyExit:           "Exit",
107	KeyCancel:         "Cancel",
108	KeyPause:          "Pause",
109	KeyPrint:          "Print",
110	KeyF1:             "F1",
111	KeyF2:             "F2",
112	KeyF3:             "F3",
113	KeyF4:             "F4",
114	KeyF5:             "F5",
115	KeyF6:             "F6",
116	KeyF7:             "F7",
117	KeyF8:             "F8",
118	KeyF9:             "F9",
119	KeyF10:            "F10",
120	KeyF11:            "F11",
121	KeyF12:            "F12",
122	KeyF13:            "F13",
123	KeyF14:            "F14",
124	KeyF15:            "F15",
125	KeyF16:            "F16",
126	KeyF17:            "F17",
127	KeyF18:            "F18",
128	KeyF19:            "F19",
129	KeyF20:            "F20",
130	KeyF21:            "F21",
131	KeyF22:            "F22",
132	KeyF23:            "F23",
133	KeyF24:            "F24",
134	KeyF25:            "F25",
135	KeyF26:            "F26",
136	KeyF27:            "F27",
137	KeyF28:            "F28",
138	KeyF29:            "F29",
139	KeyF30:            "F30",
140	KeyF31:            "F31",
141	KeyF32:            "F32",
142	KeyF33:            "F33",
143	KeyF34:            "F34",
144	KeyF35:            "F35",
145	KeyF36:            "F36",
146	KeyF37:            "F37",
147	KeyF38:            "F38",
148	KeyF39:            "F39",
149	KeyF40:            "F40",
150	KeyF41:            "F41",
151	KeyF42:            "F42",
152	KeyF43:            "F43",
153	KeyF44:            "F44",
154	KeyF45:            "F45",
155	KeyF46:            "F46",
156	KeyF47:            "F47",
157	KeyF48:            "F48",
158	KeyF49:            "F49",
159	KeyF50:            "F50",
160	KeyF51:            "F51",
161	KeyF52:            "F52",
162	KeyF53:            "F53",
163	KeyF54:            "F54",
164	KeyF55:            "F55",
165	KeyF56:            "F56",
166	KeyF57:            "F57",
167	KeyF58:            "F58",
168	KeyF59:            "F59",
169	KeyF60:            "F60",
170	KeyF61:            "F61",
171	KeyF62:            "F62",
172	KeyF63:            "F63",
173	KeyF64:            "F64",
174	KeyCtrlA:          "Ctrl-A",
175	KeyCtrlB:          "Ctrl-B",
176	KeyCtrlC:          "Ctrl-C",
177	KeyCtrlD:          "Ctrl-D",
178	KeyCtrlE:          "Ctrl-E",
179	KeyCtrlF:          "Ctrl-F",
180	KeyCtrlG:          "Ctrl-G",
181	KeyCtrlJ:          "Ctrl-J",
182	KeyCtrlK:          "Ctrl-K",
183	KeyCtrlL:          "Ctrl-L",
184	KeyCtrlN:          "Ctrl-N",
185	KeyCtrlO:          "Ctrl-O",
186	KeyCtrlP:          "Ctrl-P",
187	KeyCtrlQ:          "Ctrl-Q",
188	KeyCtrlR:          "Ctrl-R",
189	KeyCtrlS:          "Ctrl-S",
190	KeyCtrlT:          "Ctrl-T",
191	KeyCtrlU:          "Ctrl-U",
192	KeyCtrlV:          "Ctrl-V",
193	KeyCtrlW:          "Ctrl-W",
194	KeyCtrlX:          "Ctrl-X",
195	KeyCtrlY:          "Ctrl-Y",
196	KeyCtrlZ:          "Ctrl-Z",
197	KeyCtrlSpace:      "Ctrl-Space",
198	KeyCtrlUnderscore: "Ctrl-_",
199	KeyCtrlRightSq:    "Ctrl-]",
200	KeyCtrlBackslash:  "Ctrl-\\",
201	KeyCtrlCarat:      "Ctrl-^",
202}
203
204// Name returns a printable value or the key stroke.  This can be used
205// when printing the event, for example.
206func (ev *EventKey) Name() string {
207	s := ""
208	m := []string{}
209	if ev.mod&ModShift != 0 {
210		m = append(m, "Shift")
211	}
212	if ev.mod&ModAlt != 0 {
213		m = append(m, "Alt")
214	}
215	if ev.mod&ModMeta != 0 {
216		m = append(m, "Meta")
217	}
218	if ev.mod&ModCtrl != 0 {
219		m = append(m, "Ctrl")
220	}
221
222	ok := false
223	if s, ok = KeyNames[ev.key]; !ok {
224		if ev.key == KeyRune {
225			s = "Rune[" + string(ev.ch) + "]"
226		} else {
227			s = fmt.Sprintf("Key[%d,%d]", ev.key, int(ev.ch))
228		}
229	}
230	if len(m) != 0 {
231		if ev.mod&ModCtrl != 0 && strings.HasPrefix(s, "Ctrl-") {
232			s = s[5:]
233		}
234		return fmt.Sprintf("%s+%s", strings.Join(m, "+"), s)
235	}
236	return s
237}
238
239// NewEventKey attempts to create a suitable event.  It parses the various
240// ASCII control sequences if KeyRune is passed for Key, but if the caller
241// has more precise information it should set that specifically.  Callers
242// that aren't sure about modifier state (most) should just pass ModNone.
243func NewEventKey(k Key, ch rune, mod ModMask) *EventKey {
244	if k == KeyRune && (ch < ' ' || ch == 0x7f) {
245		// Turn specials into proper key codes.  This is for
246		// control characters and the DEL.
247		k = Key(ch)
248		if mod == ModNone && ch < ' ' {
249			switch Key(ch) {
250			case KeyBackspace, KeyTab, KeyEsc, KeyEnter:
251				// these keys are directly typeable without CTRL
252			default:
253				// most likely entered with a CTRL keypress
254				mod = ModCtrl
255			}
256		}
257	}
258	return &EventKey{t: time.Now(), key: k, ch: ch, mod: mod}
259}
260
261// ModMask is a mask of modifier keys.  Note that it will not always be
262// possible to report modifier keys.
263type ModMask int16
264
265// These are the modifiers keys that can be sent either with a key press,
266// or a mouse event.  Note that as of now, due to the confusion associated
267// with Meta, and the lack of support for it on many/most platforms, the
268// current implementations never use it.  Instead, they use ModAlt, even for
269// events that could possibly have been distinguished from ModAlt.
270const (
271	ModShift ModMask = 1 << iota
272	ModCtrl
273	ModAlt
274	ModMeta
275	ModNone ModMask = 0
276)
277
278// Key is a generic value for representing keys, and especially special
279// keys (function keys, cursor movement keys, etc.)  For normal keys, like
280// ASCII letters, we use KeyRune, and then expect the application to
281// inspect the Rune() member of the EventKey.
282type Key int16
283
284// This is the list of named keys.  KeyRune is special however, in that it is
285// a place holder key indicating that a printable character was sent.  The
286// actual value of the rune will be transported in the Rune of the associated
287// EventKey.
288const (
289	KeyRune Key = iota + 256
290	KeyUp
291	KeyDown
292	KeyRight
293	KeyLeft
294	KeyUpLeft
295	KeyUpRight
296	KeyDownLeft
297	KeyDownRight
298	KeyCenter
299	KeyPgUp
300	KeyPgDn
301	KeyHome
302	KeyEnd
303	KeyInsert
304	KeyDelete
305	KeyHelp
306	KeyExit
307	KeyClear
308	KeyCancel
309	KeyPrint
310	KeyPause
311	KeyBacktab
312	KeyF1
313	KeyF2
314	KeyF3
315	KeyF4
316	KeyF5
317	KeyF6
318	KeyF7
319	KeyF8
320	KeyF9
321	KeyF10
322	KeyF11
323	KeyF12
324	KeyF13
325	KeyF14
326	KeyF15
327	KeyF16
328	KeyF17
329	KeyF18
330	KeyF19
331	KeyF20
332	KeyF21
333	KeyF22
334	KeyF23
335	KeyF24
336	KeyF25
337	KeyF26
338	KeyF27
339	KeyF28
340	KeyF29
341	KeyF30
342	KeyF31
343	KeyF32
344	KeyF33
345	KeyF34
346	KeyF35
347	KeyF36
348	KeyF37
349	KeyF38
350	KeyF39
351	KeyF40
352	KeyF41
353	KeyF42
354	KeyF43
355	KeyF44
356	KeyF45
357	KeyF46
358	KeyF47
359	KeyF48
360	KeyF49
361	KeyF50
362	KeyF51
363	KeyF52
364	KeyF53
365	KeyF54
366	KeyF55
367	KeyF56
368	KeyF57
369	KeyF58
370	KeyF59
371	KeyF60
372	KeyF61
373	KeyF62
374	KeyF63
375	KeyF64
376)
377
378const (
379	// These key codes are used internally, and will never appear to applications.
380	keyPasteStart Key = iota + 16384
381	keyPasteEnd
382)
383
384// These are the control keys.  Note that they overlap with other keys,
385// perhaps.  For example, KeyCtrlH is the same as KeyBackspace.
386const (
387	KeyCtrlSpace Key = iota
388	KeyCtrlA
389	KeyCtrlB
390	KeyCtrlC
391	KeyCtrlD
392	KeyCtrlE
393	KeyCtrlF
394	KeyCtrlG
395	KeyCtrlH
396	KeyCtrlI
397	KeyCtrlJ
398	KeyCtrlK
399	KeyCtrlL
400	KeyCtrlM
401	KeyCtrlN
402	KeyCtrlO
403	KeyCtrlP
404	KeyCtrlQ
405	KeyCtrlR
406	KeyCtrlS
407	KeyCtrlT
408	KeyCtrlU
409	KeyCtrlV
410	KeyCtrlW
411	KeyCtrlX
412	KeyCtrlY
413	KeyCtrlZ
414	KeyCtrlLeftSq // Escape
415	KeyCtrlBackslash
416	KeyCtrlRightSq
417	KeyCtrlCarat
418	KeyCtrlUnderscore
419)
420
421// Special values - these are fixed in an attempt to make it more likely
422// that aliases will encode the same way.
423
424// These are the defined ASCII values for key codes.  They generally match
425// with KeyCtrl values.
426const (
427	KeyNUL Key = iota
428	KeySOH
429	KeySTX
430	KeyETX
431	KeyEOT
432	KeyENQ
433	KeyACK
434	KeyBEL
435	KeyBS
436	KeyTAB
437	KeyLF
438	KeyVT
439	KeyFF
440	KeyCR
441	KeySO
442	KeySI
443	KeyDLE
444	KeyDC1
445	KeyDC2
446	KeyDC3
447	KeyDC4
448	KeyNAK
449	KeySYN
450	KeyETB
451	KeyCAN
452	KeyEM
453	KeySUB
454	KeyESC
455	KeyFS
456	KeyGS
457	KeyRS
458	KeyUS
459	KeyDEL Key = 0x7F
460)
461
462// These keys are aliases for other names.
463const (
464	KeyBackspace  = KeyBS
465	KeyTab        = KeyTAB
466	KeyEsc        = KeyESC
467	KeyEscape     = KeyESC
468	KeyEnter      = KeyCR
469	KeyBackspace2 = KeyDEL
470)
471