key.go

Documentation: github.com/gdamore/tcell/v2

     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  
    15  package tcell
    16  
    17  import (
    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.
    45  type 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.
    54  func (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.
    60  func (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.
    69  func (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.
    77  func (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.
    83  var 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.
   206  func (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.
   243  func 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.
   263  type 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.
   270  const (
   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.
   282  type 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.
   288  const (
   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  
   378  const (
   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.
   386  const (
   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.
   426  const (
   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.
   463  const (
   464  	KeyBackspace  = KeyBS
   465  	KeyTab        = KeyTAB
   466  	KeyEsc        = KeyESC
   467  	KeyEscape     = KeyESC
   468  	KeyEnter      = KeyCR
   469  	KeyBackspace2 = KeyDEL
   470  )
   471
View as plain text