Unit CastleKeysMouse

Description

Uses

Classes, Interfaces, Objects and Records

Functions and Procedures

Types

Constants

Description

Types and constants to handle keys and mouse. They are used throughout our engine, both by CastleControl (Lazarus component) and by non-Lazarus CastleWindow.

Source: ui/castlekeysmouse.pas (line 19).

Uses

Overview

Classes, Interfaces, Objects and Records

Name	Description
Class `TKeysPressed`	Tracking the "pressed" state of keys.
Record `TGameControllerPressRelease`	Used when input indicates press / release of a game controller button.
Record `TInputPressRelease`	Input press or release event.
Record `TInputMotion`	Motion (movement) of mouse or a finger on a touch device.
Class `TCastleConfigKeysMouseHelper`

Functions and Procedures

function KeyToStr(const Key: TKey; const Modifiers: TModifierKeys = []; const CtrlIsCommand: boolean = false): string;

function ModifiersDown(const KeysDown: TKeysBooleans): TModifierKeys; overload;

function ModifiersDown(const Pressed: TKeysPressed): TModifierKeys; overload;

function ModifierKeysToNiceStr(const MK: TModifierKeys): string;

function CharToNiceStr(const C: char; const Modifiers: TModifierKeys = []; const BackSpaceTabEnterString: boolean = true; const CtrlIsCommand: boolean = false): string;

function KeyStringToNiceStr(const KeyString: String; const Modifiers: TModifierKeys = []; const BackSpaceTabEnterString: boolean = true; const CtrlIsCommand: boolean = false): string;

function StrToKey(const S: string; const DefaultKey: TKey): TKey;

function InputKey(const Position: TVector2; const Key: TKey; const KeyString: string; const ModifiersDown: TModifierKeys): TInputPressRelease;

function InputMouseButton(const Position: TVector2; const MouseButton: TCastleMouseButton; const FingerIndex: TFingerIndex; const ModifiersDown: TModifierKeys): TInputPressRelease;

function InputMouseWheel(const Position: TVector2; const Scroll: Single; const Vertical: Boolean; const ModifiersDown: TModifierKeys): TInputPressRelease;

function InputMotion(const OldPosition, Position: TVector2; const Pressed: TCastleMouseButtons; const FingerIndex: TFingerIndex): TInputMotion;

Types

TKey = (...);

TKeysBooleans = array [TKey] of Boolean;

PKeysBooleans = ˆTKeysBooleans;

TKeysBytes = array [Byte] of TKey;

PKeysBytes = ˆTKeysBytes;

TCharactersBooleans = array [Char] of Boolean;

PCharactersBooleans = ˆTCharactersBooleans;

TCastleMouseButton = (...);

TCastleMouseButtons = set of TCastleMouseButton;

TMouseCursor = (...);

TModifierKey = (...);

TModifierKeys = set of TModifierKey;

TMouseWheelDirection = (...);

TInputPressReleaseType = (...);

TGameControllerButton = (...);

TGameControllerButtonMeaning = (...);

TFingerIndex = Cardinal;

Constants

K_None = keyNone deprecated;

K_PrintScreen = keyPrintScreen deprecated;

K_CapsLock = keyCapsLock deprecated;

K_ScrollLock = keyScrollLock deprecated;

K_NumLock = keyNumLock deprecated;

K_Pause = keyPause deprecated;

K_Apostrophe = keyApostrophe deprecated;

K_Semicolon = keySemicolon deprecated;

K_BackSpace = keyBackSpace deprecated;

K_Tab = keyTab deprecated;

K_Slash = keySlash deprecated;

K_BackQuote = keyBackQuote deprecated;

K_Minus = keyMinus deprecated;

K_Enter = keyEnter deprecated;

K_Equal = keyEqual deprecated;

K_BackSlash = keyBackSlash deprecated;

K_Shift = keyShift deprecated;

K_Ctrl = keyCtrl deprecated;

K_Alt = keyAlt deprecated;

K_Plus = keyPlus deprecated;

K_Escape = keyEscape deprecated;

K_Space = keySpace deprecated;

K_PageUp = keyPageUp deprecated;

K_PageDown = keyPageDown deprecated;

K_End = keyEnd deprecated;

K_Home = keyHome deprecated;

K_Left = keyArrowLeft deprecated;

K_Up = keyArrowUp deprecated;

K_Right = keyArrowRight deprecated;

K_Down = keyArrowDown deprecated;

K_Insert = keyInsert deprecated;

K_Delete = keyDelete deprecated;

K_0 = key0 deprecated;

K_1 = key1 deprecated;

K_2 = key2 deprecated;

K_3 = key3 deprecated;

K_4 = key4 deprecated;

K_5 = key5 deprecated;

K_6 = key6 deprecated;

K_7 = key7 deprecated;

K_8 = key8 deprecated;

K_9 = key9 deprecated;

K_A = keyA deprecated;

K_B = keyB deprecated;

K_C = keyC deprecated;

K_D = keyD deprecated;

K_E = keyE deprecated;

K_F = keyF deprecated;

K_G = keyG deprecated;

K_H = keyH deprecated;

K_I = keyI deprecated;

K_J = keyJ deprecated;

K_K = keyK deprecated;

K_L = keyL deprecated;

K_M = keyM deprecated;

K_N = keyN deprecated;

K_O = keyO deprecated;

K_P = keyP deprecated;

K_Q = keyQ deprecated;

K_R = keyR deprecated;

K_S = keyS deprecated;

K_T = keyT deprecated;

K_U = keyU deprecated;

K_V = keyV deprecated;

K_W = keyW deprecated;

K_X = keyX deprecated;

K_Y = keyY deprecated;

K_Z = keyZ deprecated;

K_LeftBracket = keyLeftBracket deprecated;

K_RightBracket = keyRightBracket deprecated;

K_Numpad_Plus = keyNumpadPlus deprecated;

K_Numpad_Minus = keyNumpadMinus deprecated;

K_F1 = keyF1 deprecated;

K_F2 = keyF2 deprecated;

K_F3 = keyF3 deprecated;

K_F4 = keyF4 deprecated;

K_F5 = keyF5 deprecated;

K_F6 = keyF6 deprecated;

K_F7 = keyF7 deprecated;

K_F8 = keyF8 deprecated;

K_F9 = keyF9 deprecated;

K_F10 = keyF10 deprecated;

K_F11 = keyF11 deprecated;

K_F12 = keyF12 deprecated;

K_Numpad_0 = keyNumpad0 deprecated;

K_Numpad_1 = keyNumpad1 deprecated;

K_Numpad_2 = keyNumpad2 deprecated;

K_Numpad_3 = keyNumpad3 deprecated;

K_Numpad_4 = keyNumpad4 deprecated;

K_Numpad_5 = keyNumpad5 deprecated;

K_Numpad_6 = keyNumpad6 deprecated;

K_Numpad_7 = keyNumpad7 deprecated;

K_Numpad_8 = keyNumpad8 deprecated;

K_Numpad_9 = keyNumpad9 deprecated;

K_Numpad_End = keyNumpadEnd deprecated;

K_Numpad_Down = keyNumpadDown deprecated;

K_Numpad_PageDown = keyNumpadPageDown deprecated;

K_Numpad_Left = keyNumpadLeft deprecated;

K_Numpad_Begin = keyNumpadBegin deprecated;

K_Numpad_Right = keyNumpadRight deprecated;

K_Numpad_Home = keyNumpadHome deprecated;

K_Numpad_Up = keyNumpadUp deprecated;

K_Numpad_PageUp = keyNumpadPageUp deprecated;

K_Numpad_Insert = keyNumpadInsert deprecated;

K_Numpad_Delete = keyNumpadDelete deprecated;

K_Numpad_Enter = keyNumpadEnter deprecated;

K_Numpad_Multiply = keyNumpadMultiply deprecated;

K_Numpad_Divide = keyNumpadDivide deprecated;

K_Comma = keyComma deprecated;

K_Period = keyPeriod deprecated;

keyLeft = keyArrowLeft deprecated 'Use keyArrowLeft';

keyUp = keyArrowUp deprecated 'Use keyArrowUp';

keyRight = keyArrowRight deprecated 'Use keyArrowRight';

keyDown = keyArrowDown deprecated 'Use keyArrowDown';

MouseButtonStr: array [TCastleMouseButton] of string = (
    'left', 'middle', 'right', 'extra1', 'extra2');

ModifierKeyToKey: array[TModifierKey]of TKey = (keyCtrl, keyShift, keyAlt);

MouseWheelDirectionStr: array [TMouseWheelDirection] of string =
  ('none', 'up', 'down', 'left', 'right');

Description

Functions and Procedures

function KeyToStr(const Key: TKey; const Modifiers: TModifierKeys = []; const CtrlIsCommand: boolean = false): string;

This item has no description.

Source: ui/castlekeysmouse.pas (line 551).

function ModifiersDown(const KeysDown: TKeysBooleans): TModifierKeys; overload;

Determine pressed modifier keys (ctrl, shift and so on).

Overloaded version with TKeysPressed parameter allows the parameter to be Nil, and returns [] (empty set) then.

Source: ui/castlekeysmouse.pas (line 563).

function ModifiersDown(const Pressed: TKeysPressed): TModifierKeys; overload;

This item has no description.

Source: ui/castlekeysmouse.pas (line 564).

function ModifierKeysToNiceStr(const MK: TModifierKeys): string;

This item has no description.

Source: ui/castlekeysmouse.pas (line 567).

function CharToNiceStr(const C: char; const Modifiers: TModifierKeys = []; const BackSpaceTabEnterString: boolean = true; const CtrlIsCommand: boolean = false): string;

Nice short description of the character. When Modifiers is not empty, these are the additional modifiers required to be pressed (although some C values, like CtrlA ... CtrlZ, may already indicate some modifier).

For normal readable characters just returns them, for special characters returns short string like "Ctrl+C" or "Escape".

The returned string doesn't contain any quotes around, doesn't contain any word merely stating "character" (for example argument 'c' just generates 'c', not 'character "c"').

BackSpaceTabEnterString determines behavior on three special values: #8, #9, #13. These may be either described as Backspace/Tab/Enter (if BackSpaceTabEnterString = true) or as Ctrl+H, Ctrl+I, Ctrl+M (if BackSpaceTabEnterString = false).

Source: ui/castlekeysmouse.pas (line 585).

function KeyStringToNiceStr(const KeyString: String; const Modifiers: TModifierKeys = []; const BackSpaceTabEnterString: boolean = true; const CtrlIsCommand: boolean = false): string;

Like CharToNiceStr, but accepts UTF-8 characters expressed as String. KeyString = '' means "none".

Source: ui/castlekeysmouse.pas (line 591).

function StrToKey(const S: string; const DefaultKey: TKey): TKey;

Convert string value back to a key name, reversing KeyToStr. If string does not contain any recognized key name, return DefaultKey.

Source: ui/castlekeysmouse.pas (line 605).

function InputKey(const Position: TVector2; const Key: TKey; const KeyString: string; const ModifiersDown: TModifierKeys): TInputPressRelease;

Construct TInputPressRelease corresponding to given event.

Source: ui/castlekeysmouse.pas (line 974).

function InputMouseButton(const Position: TVector2; const MouseButton: TCastleMouseButton; const FingerIndex: TFingerIndex; const ModifiersDown: TModifierKeys): TInputPressRelease;

This item has no description.

Source: ui/castlekeysmouse.pas (line 977).

function InputMouseWheel(const Position: TVector2; const Scroll: Single; const Vertical: Boolean; const ModifiersDown: TModifierKeys): TInputPressRelease;

This item has no description.

Source: ui/castlekeysmouse.pas (line 980).

function InputMotion(const OldPosition, Position: TVector2; const Pressed: TCastleMouseButtons; const FingerIndex: TFingerIndex): TInputMotion;

Construct TInputMotion.

Source: ui/castlekeysmouse.pas (line 986).

Types

TKey = (...);

Keys on the keyboard.

Some properties of keyXxx constants that are guaranteed:

keyNone means "no key". It's guaranteed that it's always equal to zero.
Letters (constants keyA .. keyZ) are guaranteed to be always equal to TKey('A') .. TKey('Z') and digits (constants key0 .. key9) are guaranteed to be always equal to TKey('0') .. TKey('9'). That is, their ordinal values are equal to their ASCII codes, and they are always ordered.
Also keyF1 .. keyF12 (function keys) are guaranteed to be always nicely ordered (i.e. keyF2 = keyF1 + 1, keyF3 = keyF2 + 1 and so on).
Also keyEscape, keyBackSpace, keyTab, keyEnter are guaranteed to be always equal to CharEscape, CharBackSpace, CharTab, CharEnter (well, typecasted to TKey type).

Do not ever use keyReserved_Xxx for any purpose, they may be used for something in next CGE versions.

Values

keyNone
keyPrintScreen
keyCapsLock
keyScrollLock
keyNumLock
keyPause
keyApostrophe
keySemicolon
keyBackSpace: = Ord(CharBackSpace) = 8
keyTab: = Ord(CharTab) = 9
keySlash
keyBackQuote
keyMinus
keyEnter: = Ord(CharEnter) = 13
keyEqual
keyBackSlash
keyShift
keyCtrl
keyAlt
keyPlus
keyReserved_20
keyReserved_21
keyReserved_22
keyReserved_23
keyReserved_24
keyReserved_25
keyReserved_26
keyEscape: = Ord(CharEscape) = 27
keyReserved_28
keyReserved_29
keyReserved_30
keyReserved_31
keySpace: = Ord(' ') = 32
keyPageUp
keyPageDown
keyEnd
keyHome
keyArrowLeft
keyArrowUp
keyArrowRight
keyArrowDown
keyReserved_41
keyReserved_42
keyReserved_43
keyReserved_44
keyInsert
keyDelete
keyReserved_47
key0: = Ord('0') = 48
key1: = Ord('1')
key2: = Ord('2')
key3: = Ord('3')
key4: = Ord('4')
key5: = Ord('5')
key6: = Ord('6')
key7: = Ord('7')
key8: = Ord('8')
key9: = Ord('9') = 57
keyReserved_58
keyReserved_59
keyReserved_60
keyReserved_61
keyReserved_62
keyReserved_63
keyReserved_64
keyA: = Ord('A') = 65
keyB: = Ord('B')
keyC: = Ord('C')
keyD: = Ord('D')
keyE: = Ord('E')
keyF: = Ord('F')
keyG: = Ord('G')
keyH: = Ord('H')
keyI: = Ord('I')
keyJ: = Ord('J')
keyK: = Ord('K')
keyL: = Ord('L')
keyM: = Ord('M')
keyN: = Ord('N')
keyO: = Ord('O')
keyP: = Ord('P')
keyQ: = Ord('Q')
keyR: = Ord('R')
keyS: = Ord('S')
keyT: = Ord('T')
keyU: = Ord('U')
keyV: = Ord('V')
keyW: = Ord('W')
keyX: = Ord('X')
keyY: = Ord('Y')
keyZ: = Ord('Z') = 90
keyLeftBracket
keyReserved_92
keyRightBracket
keyReserved_94
keyReserved_95
keyReserved_96
keyReserved_97
keyReserved_98
keyReserved_99
keyReserved_100
keyReserved_101
keyReserved_102
keyReserved_103
keyReserved_104
keyReserved_105
keyReserved_106
keyNumpadPlus
keyReserved_108
keyNumpadMinus
keyReserved_110
keyReserved_111
keyF1
keyF2
keyF3
keyF4
keyF5
keyF6
keyF7
keyF8
keyF9
keyF10
keyF11
keyF12
keyReserved_124
keyReserved_125
keyReserved_126
keyReserved_127
keyReserved_128
keyReserved_129
keyReserved_130
keyReserved_131
keyReserved_132
keyReserved_133
keyReserved_134
keyReserved_135
keyReserved_136
keyReserved_137
keyReserved_138
keyReserved_139
keyNumpad0
keyNumpad1
keyNumpad2
keyNumpad3
keyNumpad4
keyNumpad5
keyNumpad6
keyNumpad7
keyNumpad8
keyNumpad9
keyNumpadEnd
keyNumpadDown
keyNumpadPageDown
keyNumpadLeft
keyNumpadBegin
keyNumpadRight
keyNumpadHome
keyNumpadUp
keyNumpadPageUp
keyNumpadInsert
keyNumpadDelete
keyNumpadEnter
keyNumpadMultiply
keyNumpadDivide
keyReserved_164: Old: Buttons on Nintendo Switch pad were expressed as this enum. Now they are expressed as TGameControllerButton. // keyPadA, // new gbEast // keyPadB, // new gbSouth // keyPadX, // new gbNorth // keyPadY, // new gbWest // keyPadL, // new gbLeftBumper // keyPadR, // new gbRightBumper // keyPadZL, // new TGameConroller.AxisLeftTrigger (this is digital on Nintendo Switch pads, but analog on Xbox controllers) // keyPadZR, // new TGameConroller.AxisRightTrigger (this is digital on Nintendo Switch pads, but analog on Xbox controllers) // keyPadPlus, // new gbMenu // keyPadMinus, // new gbView // keyPadLeft, // new gbDPadLeft // keyPadUp, // new gbDPadUp // keyPadRight, // new gbDPadRight // keyPadDown, // new gbDPadDown home key on Nintendo Switch -> gbGuide, in cases we can handle it in API
keyReserved_165
keyReserved_166
keyReserved_167
keyReserved_168
keyReserved_169
keyReserved_170
keyReserved_171
keyReserved_172
keyReserved_173
keyReserved_174
keyReserved_175
keyReserved_176
keyReserved_177
keyReserved_178
keyReserved_179
keyReserved_180
keyReserved_181
keyReserved_182
keyReserved_183
keyReserved_184
keyReserved_185
keyReserved_186
keyReserved_187
keyComma
keyReserved_189
keyPeriod
keyReserved_191

Source: ui/castlekeysmouse.pas (line 54).

TKeysBooleans = array [TKey] of Boolean;

This item has no description.

Source: ui/castlekeysmouse.pas (line 387).

PKeysBooleans = ˆTKeysBooleans;

This item has no description.

Source: ui/castlekeysmouse.pas (line 388).

TKeysBytes = array [Byte] of TKey;

This item has no description.

Source: ui/castlekeysmouse.pas (line 389).

PKeysBytes = ˆTKeysBytes;

This item has no description.

Source: ui/castlekeysmouse.pas (line 390).

TCharactersBooleans = array [Char] of Boolean;

This item has no description.

Source: ui/castlekeysmouse.pas (line 392).

PCharactersBooleans = ˆTCharactersBooleans;

This item has no description.

Source: ui/castlekeysmouse.pas (line 393).

TCastleMouseButton = (...);

This item has no description.

Values

buttonLeft
buttonMiddle
buttonRight
buttonExtra1
buttonExtra2

Source: ui/castlekeysmouse.pas (line 395).

TCastleMouseButtons = set of TCastleMouseButton;

This item has no description.

Source: ui/castlekeysmouse.pas (line 396).

TMouseCursor = (...);

Look of the mouse cursor. Used for various properties: TCastleUserInterface.Cursor, TCastleTransform.Cursor, TCastleWindow.Cursor.

mcDefault, mcNone, mcForceNone have somewhat special meanings. The rest are some cursor images will well-defined meanings for the user, their exact look may depend on current window manager theme etc.

Values

mcDefault: Leave cursor as default, decided by a parent UI control, or by window manager.
mcNone: Make cursor invisible.
mcForceNone: Forcefully make cursor invisible.
If *any* UI control under the cursor says that the cursor is mcForceNone, it will be invisible. This is in contrast to mcNone, that only hides the cursor if the currently focused control (under the mouse cursor) sets it.
mcStandard: Standard arrow, indicates that user can point / click something.
mcWait: Indicates the program is busy and user should wait.
mcText: Text cursor, indicates that there's text under the cursor, which usually means that it can be selected, or that user can click to set focus to the text area.
mcHand: Indicates something active is under cursor, usually for links.
mcResizeVertical
mcResizeHorizontal
mcResizeTopLeft
mcResizeTop
mcResizeTopRight
mcResizeLeft
mcResizeRight
mcResizeBottomLeft
mcResizeBottom
mcResizeBottomRight

Source: ui/castlekeysmouse.pas (line 406).

TModifierKey = (...);

Modifier keys are keys that, when pressed, modify the meaning of other keys. Of course, this is actually just a convention. The actual interpretation is left up to the final program – there you have to decide when and how modifiers affect the meaning of other keys.

Values

mkCtrl
mkShift
mkAlt

Source: ui/castlekeysmouse.pas (line 450).

TModifierKeys = set of TModifierKey;

This item has no description.

Source: ui/castlekeysmouse.pas (line 451).

TMouseWheelDirection = (...);

This item has no description.

Values

mwNone
mwUp
mwDown
mwLeft
mwRight

Source: ui/castlekeysmouse.pas (line 597).

TInputPressReleaseType = (...);

This item has no description.

Values

itKey
itMouseButton
itMouseWheel
itGameController

Source: ui/castlekeysmouse.pas (line 608).

TGameControllerButton = (...);

Possible game controlers (gamepad, joystick) buttons.

Values

gbNorth: gbNorth, gbEast, gbSouth, gbWest are universal names for 4 "face buttons" on the "button pad". See Steam "button pad" description.
They can be labeled A B X Y (in a different order between e.g. Xbox and Nintendo Switch controllers), or square triangle circle cross (e.g. PlayStation controllers), or even 1 2 3 4 on some gamepads.
gbEast
gbSouth
gbWest
gbLeftBumper: Left bumper button. This is often used (together with gbRightBumper) to allow user to cycle left / right through some choice, like a car color, weapon, UI tab.
gbRightBumper: Right bumper button.
gbLeftStickClick: Pressing down on the left stick.
gbRightStickClick: Pressing down on the right stick.
gbDPadUp: Directional buttons on the D-Pad (digital pad). Remember that the D-pad generally has hardware mechanism that prevents the user from pressing opposite buttons at the same time. So it may not be physically possible to have e.g. both gbDPadUp and gbDPadDown pressed at the same time.
gbDPadRight
gbDPadDown
gbDPadLeft
gbView: Button in the middle-left of the gamepad.
- This is button with 2 rectangles called "View" on the Xbox Wireless Controller.
- This is called "Back" on the Xbox 360 controller.
- This is called "Minus" or "Select" on the Nintendo Switch controllers.
gbMenu: Button in the middle-right of the gamepad.
- This is button with 3 horizontal lines called "Menu" on the Xbox Wireless Controller.
- This is called "Start" on the Xbox 360 controller.
- This is called "Plus" or "Start" on the Nintendo Switch controllers.
gbGuide: Buton in the center of the gamepad. Intention is to invoke a menu with available games.
This button is sometimes not available to reliably handle in games, even if the device has it. The system, like Nintendo Switch or the Xbox console, has a hardcoded handling of it, with which you should not conflict (or you may not even get report about this being pressed). On Windows "game mode" is activated by this by default (user can disable it in Windows settings). Also on Windows, Steam "big picture" handles it.
- This button shows the Xbox logo on the Xbox Wireless Controller and Xbox 360 controller.
- This is called "Home" on the Nintendo Switch controllers.
gbShare: Share button with up arrow available on the 3rd revision of the Xbox Wireless Controller.
Note that on Windows, this automatically takes a screenshot of the current window. You should probably not try to handle this button in your games, to not conflict with what Windows is doing.

Source: ui/castlekeysmouse.pas (line 611).

TGameControllerButtonMeaning = (...);

Possible game controlers (gamepad, joystick) buttons meaning, that may be used in certain cases as easier way to express TGameControllerButton.

Values

gmNone: No meaning assigned to this button.
gmConfirm: Button that is used to confirm some action, like "OK" or "Yes".
gmCancel: Button that is used to cancel some action, like "Cancel" or "No" or "Back".

Source: ui/castlekeysmouse.pas (line 752).

TFingerIndex = Cardinal;

This item has no description.

Source: ui/castlekeysmouse.pas (line 787).