Unit CastleKeysMouse

Classes, Interfaces, Objects and Records

Variables

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.

Uses

Overview

Classes, Interfaces, Objects and Records

Name	Description
Class `TKeysPressed`	Tracking the "pressed" state of keys.
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 MouseWheelDirection(const Scroll: Single; const Vertical: boolean): TMouseWheelDirection;

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;

TMouseButton = TCastleMouseButton deprecated 'use TCastleMouseButton';

TMouseButtons = TCastleMouseButtons deprecated 'use TCastleMouseButtons';

TMouseCursor = (...);

TModifierKey = (...);

TModifierKeys = set of TModifierKey;

TMouseWheelDirection = (...);

TInputPressReleaseType = (...);

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';

mbLeft = buttonLeft deprecated 'Use buttonLeft';

mbMiddle = buttonMiddle deprecated 'Use buttonMiddle';

mbRight = buttonRight deprecated 'Use buttonRight';

mbExtra1 = buttonExtra1 deprecated 'Use buttonExtra1';

mbExtra2 = buttonExtra2 deprecated 'Use buttonExtra2';

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;

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.

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;

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).

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".

function MouseWheelDirection(const Scroll: Single; const Vertical: boolean): TMouseWheelDirection;

Determine simple mouse wheel direction from a Scroll and Vertical parameters received from TCastleWindow.OnMouseWheel. Assumes that Scroll <> 0, like TCastleWindow.OnMouseWheel guarantees.

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.

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

Construct TInputPressRelease corresponding to given event.

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;

Construct TInputMotion.

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
keyPadA: Keys on Nintendo Switch pad.
keyPadB
keyPadX
keyPadY
keyPadL
keyPadR
keyPadZL
keyPadZR
keyPadPlus
keyPadMinus
keyPadLeft
keyPadUp
keyPadRight
keyPadDown
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

TKeysBooleans = array [TKey] of Boolean;

PKeysBooleans = ˆTKeysBooleans;

TKeysBytes = array [Byte] of TKey;

PKeysBytes = ˆTKeysBytes;

TCharactersBooleans = array [Char] of Boolean;

PCharactersBooleans = ˆTCharactersBooleans;

TCastleMouseButton = (...);

Values

buttonLeft
buttonMiddle
buttonRight
buttonExtra1
buttonExtra2

TCastleMouseButtons = set of TCastleMouseButton;

TMouseButton = TCastleMouseButton deprecated 'use TCastleMouseButton';

Warning: this symbol is deprecated: use TCastleMouseButton

TMouseButtons = TCastleMouseButtons deprecated 'use TCastleMouseButtons';

Warning: this symbol is deprecated: use TCastleMouseButtons

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

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

TModifierKeys = set of TModifierKey;

TMouseWheelDirection = (...);

Values

mwNone
mwUp
mwDown
mwLeft
mwRight

TInputPressReleaseType = (...);

Values

itKey
itMouseButton
itMouseWheel

TFingerIndex = Cardinal;