org.gnome.gdk

## Class Keyval

- Object
- - org.freedesktop.bindings.Constant
  - - org.gnome.gdk.Keyval

- Direct Known Subclasses:
    KeypadKeyval

      public class Keyval
      extends org.freedesktop.bindings.Constant

  A key value as returned by a keyboard Event. Handling keystrokes is not as much fun as you might think. There is considerable complexity associated with dealing with language and country specific keyboard variants. Most of this complexity is, however, dealt with for you by the X server as proxied by GDK. This class, in turn, provides constants for the basic keyboard set. Various subclasses give you access to localized keyboards.

  It is important to note that lower case and upper case letters are considered different keys even though most keyboards present but a single physical button with an `A` showing. Think of that physical key as having both an `a` and an `A` printed on it, with the second being the key reached if the `Shift` modifier is held down. Have a look at the `ModifierType` class for a discussion of how to deal with the modifying keys and for a better understanding of the sequence in which key events occur.

  Looking for `1` through `9`? See `Num0` to `Num9`.

  The correlation between keys and Unicode characters is a complex one. For basic western ISO Latin letters the keys we press and the characters we get are, to all intents and purposes, one and the same. But there are many thousands of additional characters for which you probably don't have keys for, even if you have (or have mapped something to be) the `Compose` key for taking the composite of several keystrokes to generate special characters. Just remember that Keyvals are key constants, not constants for every unicode character and you'll keep things straight.

  GDK deals with keyvals exclusively as `int`s, and there are over 1700 of them. Most of these "keys" are ridiculous or apply to hardware that has long since ceased to exist. We've deliberately constrained this class to a narrow range; experience in 2.x showed that even mighty Eclipse chokes when asked to complete from a list that big. This leads us to two consequences. 1) Constants will be registered for keyvals encountered that haven't been explicitly created here, so you don't have to worry about some nasty RuntimeException kicking your ass. 2) You can extend this Keyval class as necessary to create your own constants if you need to. See `KeypadKeyval` for an example.

  Since:
    4.0.6
  Author:
    Andrew Cowie

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Keyval` | `a`
    `static Keyval` | `A`
    `static Keyval` | `AltLeft`
    `static Keyval` | `AltRight`
    `static Keyval` | `Ampersand`
    `static Keyval` | `Apostrophe`
    `static Keyval` | `Asterisk`
    `static Keyval` | `AtSign`
    `static Keyval` | `b`
    `static Keyval` | `B`
    `static Keyval` | `Backslash`
    `static Keyval` | `BackSpace`
    `static Keyval` | `BackTab` Reverse indentation key.
    `static Keyval` | `Bar` Also known as Pipe (from the fact that this is used in a Unix shell to "pipe" output from one command to another).
    `static Keyval` | `BraceLeft`
    `static Keyval` | `BraceRight`
    `static Keyval` | `BracketLeft`
    `static Keyval` | `BracketRight`
    `static Keyval` | `Break`
    `static Keyval` | `c`
    `static Keyval` | `C`
    `static Keyval` | `CapsLock`
    `static Keyval` | `Circumflex` Also known as Carrot or Hat.
    `static Keyval` | `Colon`
    `static Keyval` | `Comma`
    `static Keyval` | `Compose` The `Compose` used to create high order characters from pressing tis plus certain following key sequences.
    `static Keyval` | `ControlLeft`
    `static Keyval` | `ControlRight`
    `static Keyval` | `d`
    `static Keyval` | `D`
    `static Keyval` | `Delete`
    `static Keyval` | `Dollar`
    `static Keyval` | `Down`
    `static Keyval` | `e`
    `static Keyval` | `E`
    `static Keyval` | `End`
    `static Keyval` | `Equal`
    `static Keyval` | `Escape`
    `static Keyval` | `Exclaim`
    `static Keyval` | `f`
    `static Keyval` | `F`
    `static Keyval` | `F1`
    `static Keyval` | `F10`
    `static Keyval` | `F11`
    `static Keyval` | `F12`
    `static Keyval` | `F2`
    `static Keyval` | `F3`
    `static Keyval` | `F4`
    `static Keyval` | `F5`
    `static Keyval` | `F6`
    `static Keyval` | `F7`
    `static Keyval` | `F8`
    `static Keyval` | `F9`
    `static Keyval` | `g`
    `static Keyval` | `G`
    `static Keyval` | `Grave`
    `static Keyval` | `Greater`
    `static Keyval` | `h`
    `static Keyval` | `H`
    `static Keyval` | `Home`
    `static Keyval` | `i`
    `static Keyval` | `I`
    `static Keyval` | `Insert`
    `static Keyval` | `j`
    `static Keyval` | `J`
    `static Keyval` | `k`
    `static Keyval` | `K`
    `static Keyval` | `l`
    `static Keyval` | `L`
    `static Keyval` | `Left`
    `static Keyval` | `Less`
    `static Keyval` | `m`
    `static Keyval` | `M`
    `static Keyval` | `Menu`
    `static Keyval` | `Minus`
    `static Keyval` | `n`
    `static Keyval` | `N`
    `static Keyval` | `Num0`
    `static Keyval` | `Num1`
    `static Keyval` | `Num2`
    `static Keyval` | `Num3`
    `static Keyval` | `Num4`
    `static Keyval` | `Num5`
    `static Keyval` | `Num6`
    `static Keyval` | `Num7`
    `static Keyval` | `Num8`
    `static Keyval` | `Num9`
    `static Keyval` | `NumberSign`
    `static Keyval` | `NumLock`
    `static Keyval` | `o`
    `static Keyval` | `O`
    `static Keyval` | `p`
    `static Keyval` | `P`
    `static Keyval` | `PageDown`
    `static Keyval` | `PageUp`
    `static Keyval` | `ParenLeft`
    `static Keyval` | `ParenRight`
    `static Keyval` | `Pause`
    `static Keyval` | `Percent`
    `static Keyval` | `Period`
    `static Keyval` | `Plus`
    `static Keyval` | `Print`
    `static Keyval` | `q`
    `static Keyval` | `Q`
    `static Keyval` | `Question`
    `static Keyval` | `QuoteDouble`
    `static Keyval` | `QuoteSingle`
    `static Keyval` | `r`
    `static Keyval` | `R`
    `static Keyval` | `Return`
    `static Keyval` | `Right`
    `static Keyval` | `s`
    `static Keyval` | `S`
    `static Keyval` | `ScrollLock`
    `static Keyval` | `Semicolon`
    `static Keyval` | `ShiftLeft`
    `static Keyval` | `ShiftRight`
    `static Keyval` | `Slash`
    `static Keyval` | `Space`
    `static Keyval` | `SuperLeft`
    `static Keyval` | `SuperRight`
    `static Keyval` | `SysReq`
    `static Keyval` | `t`
    `static Keyval` | `T`
    `static Keyval` | `Tab` Normal indentation key.
    `static Keyval` | `Tilde`
    `static Keyval` | `u`
    `static Keyval` | `U`
    `static Keyval` | `Underscore`
    `static Keyval` | `Up`
    `static Keyval` | `v`
    `static Keyval` | `V`
    `static Keyval` | `w`
    `static Keyval` | `W`
    `static Keyval` | `x`
    `static Keyval` | `X`
    `static Keyval` | `y`
    `static Keyval` | `Y`
    `static Keyval` | `z`
    `static Keyval` | `Z`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `char` | `toUnicode()` Translate this Keyval to a unicode representation.

    - ### Methods inherited from class org.freedesktop.bindings.Constant

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### a

          public static final Keyval a

    - #### A

          public static final Keyval A

    - #### AltLeft

          public static final Keyval AltLeft

    - #### AltRight

          public static final Keyval AltRight

    - #### Ampersand

          public static final Keyval Ampersand

    - #### Apostrophe

          public static final Keyval Apostrophe

    - #### Asterisk

          public static final Keyval Asterisk

    - #### AtSign

          public static final Keyval AtSign

    - #### b

          public static final Keyval b

    - #### B

          public static final Keyval B

    - #### Backslash

          public static final Keyval Backslash

    - #### BackSpace

          public static final Keyval BackSpace

    - #### BackTab

          public static final Keyval BackTab

      Reverse indentation key.

      This occurs on when you type `Shift+Tab`. Normal (forward) indentation keystrokes are the `Tab` Keyval.

      Backwards movement by an indent is a legacy from the age of typewriters, and not used in text entry today. The `Shift+Tab` sequence is, however, used in GNOME to move the keyboard focus one Widget back.

      Since:
        4.0.14

    - #### Bar

          public static final Keyval Bar

      Also known as Pipe (from the fact that this is used in a Unix shell to "pipe" output from one command to another).

    - #### BraceLeft

          public static final Keyval BraceLeft

    - #### BraceRight

          public static final Keyval BraceRight

    - #### BracketLeft

          public static final Keyval BracketLeft

    - #### BracketRight

          public static final Keyval BracketRight

    - #### Break

          public static final Keyval Break

    - #### c

          public static final Keyval c

    - #### C

          public static final Keyval C

    - #### CapsLock

          public static final Keyval CapsLock

    - #### Circumflex

          public static final Keyval Circumflex

      Also known as Carrot or Hat.

    - #### Colon

          public static final Keyval Colon

    - #### Comma

          public static final Keyval Comma

    - #### Compose

          public static final Keyval Compose

      The `Compose` used to create high order characters from pressing tis plus certain following key sequences.
      Since:
        4.0.11

    - #### ControlLeft

          public static final Keyval ControlLeft

    - #### ControlRight

          public static final Keyval ControlRight

    - #### d

          public static final Keyval d

    - #### D

          public static final Keyval D

    - #### Delete

          public static final Keyval Delete

    - #### Dollar

          public static final Keyval Dollar

    - #### Down

          public static final Keyval Down

    - #### e

          public static final Keyval e

    - #### E

          public static final Keyval E

    - #### End

          public static final Keyval End

    - #### Equal

          public static final Keyval Equal

    - #### Escape

          public static final Keyval Escape

    - #### Exclaim

          public static final Keyval Exclaim

    - #### f

          public static final Keyval f

    - #### F

          public static final Keyval F

    - #### F1

          public static final Keyval F1

    - #### F10

          public static final Keyval F10

    - #### F11

          public static final Keyval F11

    - #### F12

          public static final Keyval F12

    - #### F2

          public static final Keyval F2

    - #### F3

          public static final Keyval F3

    - #### F4

          public static final Keyval F4

    - #### F5

          public static final Keyval F5

    - #### F6

          public static final Keyval F6

    - #### F7

          public static final Keyval F7

    - #### F8

          public static final Keyval F8

    - #### F9

          public static final Keyval F9

    - #### g

          public static final Keyval g

    - #### G

          public static final Keyval G

    - #### Grave

          public static final Keyval Grave

    - #### Greater

          public static final Keyval Greater

    - #### h

          public static final Keyval h

    - #### H

          public static final Keyval H

    - #### Home

          public static final Keyval Home

    - #### i

          public static final Keyval i

    - #### I

          public static final Keyval I

    - #### Insert

          public static final Keyval Insert

    - #### j

          public static final Keyval j

    - #### J

          public static final Keyval J

    - #### k

          public static final Keyval k

    - #### K

          public static final Keyval K

    - #### l

          public static final Keyval l

    - #### L

          public static final Keyval L

    - #### Left

          public static final Keyval Left

    - #### Less

          public static final Keyval Less

    - #### m

          public static final Keyval m

    - #### M

          public static final Keyval M

    - #### Menu

          public static final Keyval Menu

    - #### Minus

          public static final Keyval Minus

    - #### n

          public static final Keyval n

    - #### N

          public static final Keyval N

    - #### Num0

          public static final Keyval Num0

    - #### Num1

          public static final Keyval Num1

    - #### Num2

          public static final Keyval Num2

    - #### Num3

          public static final Keyval Num3

    - #### Num4

          public static final Keyval Num4

    - #### Num5

          public static final Keyval Num5

    - #### Num6

          public static final Keyval Num6

    - #### Num7

          public static final Keyval Num7

    - #### Num8

          public static final Keyval Num8

    - #### Num9

          public static final Keyval Num9

    - #### NumberSign

          public static final Keyval NumberSign

    - #### NumLock

          public static final Keyval NumLock

    - #### o

          public static final Keyval o

    - #### O

          public static final Keyval O

    - #### p

          public static final Keyval p

    - #### P

          public static final Keyval P

    - #### PageDown

          public static final Keyval PageDown

    - #### PageUp

          public static final Keyval PageUp

    - #### ParenLeft

          public static final Keyval ParenLeft

    - #### ParenRight

          public static final Keyval ParenRight

    - #### Pause

          public static final Keyval Pause

    - #### Percent

          public static final Keyval Percent

    - #### Period

          public static final Keyval Period

    - #### Plus

          public static final Keyval Plus

    - #### Print

          public static final Keyval Print

    - #### q

          public static final Keyval q

    - #### Q

          public static final Keyval Q

    - #### Question

          public static final Keyval Question

    - #### QuoteDouble

          public static final Keyval QuoteDouble

    - #### QuoteSingle

          public static final Keyval QuoteSingle

    - #### r

          public static final Keyval r

    - #### R

          public static final Keyval R

    - #### Return

          public static final Keyval Return

    - #### Right

          public static final Keyval Right

    - #### s

          public static final Keyval s

    - #### S

          public static final Keyval S

    - #### ScrollLock

          public static final Keyval ScrollLock

    - #### Semicolon

          public static final Keyval Semicolon

    - #### ShiftLeft

          public static final Keyval ShiftLeft

    - #### ShiftRight

          public static final Keyval ShiftRight

    - #### Slash

          public static final Keyval Slash

    - #### Space

          public static final Keyval Space

    - #### SuperLeft

          public static final Keyval SuperLeft

    - #### SuperRight

          public static final Keyval SuperRight

    - #### SysReq

          public static final Keyval SysReq

    - #### t

          public static final Keyval t

    - #### T

          public static final Keyval T

    - #### Tab

          public static final Keyval Tab

      Normal indentation key.

      In normal GNOME user interface usage, this is used to move the keyboard focus forwards from one Widget to the next. In text documents, however, `Tab` is typically used to insert a `'\t'` character.

      Be aware that on a standard GNOME desktop, `Alt+Tab` is captured by the window manager used to change between applications, so you likely won't receive it.

    - #### Tilde

          public static final Keyval Tilde

    - #### u

          public static final Keyval u

    - #### U

          public static final Keyval U

    - #### Underscore

          public static final Keyval Underscore

    - #### Up

          public static final Keyval Up

    - #### v

          public static final Keyval v

    - #### V

          public static final Keyval V

    - #### w

          public static final Keyval w

    - #### W

          public static final Keyval W

    - #### x

          public static final Keyval x

    - #### X

          public static final Keyval X

    - #### y

          public static final Keyval y

    - #### Y

          public static final Keyval Y

    - #### z

          public static final Keyval z

    - #### Z

          public static final Keyval Z

  - ### Method Detail

    - #### toUnicode

          public char toUnicode()

      Translate this Keyval to a unicode representation. This is useful when you've intercepted a keystroke and, having determined it is a "normal" character and not something more unusual, need to append it to a String.

      One way this might be used is:

           final Pattern regexAtoZ = Pattern.compile("[a-z]");
           final Keyval key;
           final String str, result;

           str = "" + key.toUnicode();

           if (key == Keyval.Return) {
               // execute
           } else if (key == Keyval.Escape) {
               // abort
           } else if (regexAtoZ.matcher(str).matches()) {
               entry.setText(str);
           } else {
               ...
           }

      which is a bit cumbersome, but illustrates one way of identifying "normal" letters being typed.

      Not all keys have translations; in such cases `0` will be returned. Testing for this can sometimes be an easier approach to figuring out if a "normal" key was hit, but your mileage will vary depending on the user's actual configuration. Note that that's `(char) 0`, not `'0'`!

      Be wary of appending this return value to a String!
      Although Java won't lose the character or subsequent ones, `\0` is the "`NULL` terminator" for `char*` strings in C and will prematurely terminate the printed output if you try to print the String (as, after all, in the final analysis the Java VM is nothing more than a C program and eventually a C library routine will be called to output the text)!

      Since:
        4.0.6