Unit CastleKeysMouse

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.
Object TInputPressRelease Input press or release event.
Object 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(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 MouseWheelDirection(const Scroll: Single; const Vertical: boolean): TMouseWheelDirection;
function StrToKey(const S: string; const DefaultKey: TKey): TKey;
function InputKey(const Position: TVector2Single; const Key: TKey; const KeyCharacter: Char): TInputPressRelease;
function InputMouseButton(const Position: TVector2Single; const MouseButton: TMouseButton; const FingerIndex: TFingerIndex): TInputPressRelease;
function InputMouseWheel(const Position: TVector2Single; const Scroll: Single; const Vertical: boolean): TInputPressRelease;
function InputMotion(const OldPosition, Position: TVector2Single; const Pressed: TMouseButtons; 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;
TMouseButton = (...);
TMouseButtons = set of TMouseButton;
TMouseCursor = (...);
TModifierKey = (...);
TModifierKeys = set of TModifierKey;
TMouseWheelDirection = (...);
TInputPressReleaseType = (...);
TFingerIndex = Cardinal;

Constants

MouseButtonStr: array [TMouseButton] of string = ('left', 'middle', 'right', 'extra1', 'extra2');
ModifierKeyToKey: array[TModifierKey]of TKey = (K_Ctrl, K_Shift, K_Alt);
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;

This "packs" values like KeysDown[K_Ctrl], KeysDown[K_Shift] etc. – KeysDown for all TModifierKey.

Version with TKeysPressed parameter returns [] (empty set) when argument is Nil. This may be useful sometimes.

function ModifiersDown(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;

Return a nice very 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 MouseWheelDirection(const Scroll: Single; const Vertical: boolean): TMouseWheelDirection;

Determine simple mouse wheel direction from a Scroll and Vertical parameters received from TCastleWindowCustom.OnMouseWheel. Assumes that Scroll <> 0, like TCastleWindowCustom.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: TVector2Single; const Key: TKey; const KeyCharacter: Char): TInputPressRelease;

Construct TInputPressRelease corresponding to given event.

function InputMouseButton(const Position: TVector2Single; const MouseButton: TMouseButton; const FingerIndex: TFingerIndex): TInputPressRelease;
 
function InputMouseWheel(const Position: TVector2Single; const Scroll: Single; const Vertical: boolean): TInputPressRelease;
 
function InputMotion(const OldPosition, Position: TVector2Single; const Pressed: TMouseButtons; const FingerIndex: TFingerIndex): TInputMotion;

Construct TInputMotion.

Types

TKey = (...);

Keys on keyboard. Do not ever use values K_Reserved_Xxx (they are declared here only to avoid using assignments, which would prevent FPC from allowing TKey to index arrays).

Some properties of K_Xxx constants that are guaranteed:

  • K_None means "no key". It's guaranteed that it's always equal to zero.

  • Letters (constants K_A .. K_Z) are guaranteed to be always equal to TKey('A') .. TKey('Z') and digits (constants K_0 .. K_9) 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 K_F1 .. K_F12 (function keys) are guaranteed to be always nicely ordered (i.e. K_F2 = K_F1 + 1, K_F3 = K_F2 + 1 and so on).

    Also K_Escape, K_BackSpace, K_Tab, K_Enter are guaranteed to be always equal to CharEscape, CharBackSpace, CharTab, CharEnter (well, typecasted to TKey type).

Values
  • K_None
  • K_PrintScreen
  • K_CapsLock
  • K_ScrollLock
  • K_NumLock
  • K_Pause
  • K_Apostrophe
  • K_Semicolon
  • K_BackSpace: = Ord(CharBackSpace) = 8
  • K_Tab: = Ord(CharTab) = 9
  • K_Slash
  • K_BackQuote
  • K_Minus
  • K_Enter: = Ord(CharEnter) = 13
  • K_Equal
  • K_BackSlash
  • K_Shift
  • K_Ctrl
  • K_Alt
  • K_Plus
  • K_Reserved_20
  • K_Reserved_21
  • K_Reserved_22
  • K_Reserved_23
  • K_Reserved_24
  • K_Reserved_25
  • K_Reserved_26
  • K_Escape: = Ord(CharEscape) = 27
  • K_Reserved_28
  • K_Reserved_29
  • K_Reserved_30
  • K_Reserved_31
  • K_Space: = Ord(' ') = 32
  • K_PageUp
  • K_PageDown
  • K_End
  • K_Home
  • K_Left
  • K_Up
  • K_Right
  • K_Down
  • K_Reserved_41
  • K_Reserved_42
  • K_Reserved_43
  • K_Reserved_44
  • K_Insert
  • K_Delete
  • K_Reserved_47
  • K_0: = Ord('0') = 48
  • K_1: = Ord('1')
  • K_2: = Ord('2')
  • K_3: = Ord('3')
  • K_4: = Ord('4')
  • K_5: = Ord('5')
  • K_6: = Ord('6')
  • K_7: = Ord('7')
  • K_8: = Ord('8')
  • K_9: = Ord('9') = 57
  • K_Reserved_58
  • K_Reserved_59
  • K_Reserved_60
  • K_Reserved_61
  • K_Reserved_62
  • K_Reserved_63
  • K_Reserved_64
  • K_A: = Ord('A') = 65
  • K_B: = Ord('B')
  • K_C: = Ord('C')
  • K_D: = Ord('D')
  • K_E: = Ord('E')
  • K_F: = Ord('F')
  • K_G: = Ord('G')
  • K_H: = Ord('H')
  • K_I: = Ord('I')
  • K_J: = Ord('J')
  • K_K: = Ord('K')
  • K_L: = Ord('L')
  • K_M: = Ord('M')
  • K_N: = Ord('N')
  • K_O: = Ord('O')
  • K_P: = Ord('P')
  • K_Q: = Ord('Q')
  • K_R: = Ord('R')
  • K_S: = Ord('S')
  • K_T: = Ord('T')
  • K_U: = Ord('U')
  • K_V: = Ord('V')
  • K_W: = Ord('W')
  • K_X: = Ord('X')
  • K_Y: = Ord('Y')
  • K_Z: = Ord('Z') = 90
  • K_LeftBracket
  • K_Reserved_92
  • K_RightBracket
  • K_Reserved_94
  • K_Reserved_95
  • K_Reserved_96
  • K_Reserved_97
  • K_Reserved_98
  • K_Reserved_99
  • K_Reserved_100
  • K_Reserved_101
  • K_Reserved_102
  • K_Reserved_103
  • K_Reserved_104
  • K_Reserved_105
  • K_Reserved_106
  • K_Numpad_Plus
  • K_Reserved_108
  • K_Numpad_Minus
  • K_Reserved_110
  • K_Reserved_111
  • K_F1
  • K_F2
  • K_F3
  • K_F4
  • K_F5
  • K_F6
  • K_F7
  • K_F8
  • K_F9
  • K_F10
  • K_F11
  • K_F12
  • K_Reserved_124
  • K_Reserved_125
  • K_Reserved_126
  • K_Reserved_127
  • K_Reserved_128
  • K_Reserved_129
  • K_Reserved_130
  • K_Reserved_131
  • K_Reserved_132
  • K_Reserved_133
  • K_Reserved_134
  • K_Reserved_135
  • K_Reserved_136
  • K_Reserved_137
  • K_Reserved_138
  • K_Reserved_139
  • K_Numpad_0
  • K_Numpad_1
  • K_Numpad_2
  • K_Numpad_3
  • K_Numpad_4
  • K_Numpad_5
  • K_Numpad_6
  • K_Numpad_7
  • K_Numpad_8
  • K_Numpad_9
  • K_Numpad_End
  • K_Numpad_Down
  • K_Numpad_PageDown
  • K_Numpad_Left
  • K_Numpad_Begin
  • K_Numpad_Right
  • K_Numpad_Home
  • K_Numpad_Up
  • K_Numpad_PageUp
  • K_Numpad_Insert
  • K_Numpad_Delete
  • K_Numpad_Enter
  • K_Numpad_Multiply
  • K_Numpad_Divide
  • K_Reserved_164
  • K_Reserved_165
  • K_Reserved_166
  • K_Reserved_167
  • K_Reserved_168
  • K_Reserved_169
  • K_Reserved_170
  • K_Reserved_171
  • K_Reserved_172
  • K_Reserved_173
  • K_Reserved_174
  • K_Reserved_175
  • K_Reserved_176
  • K_Reserved_177
  • K_Reserved_178
  • K_Reserved_179
  • K_Reserved_180
  • K_Reserved_181
  • K_Reserved_182
  • K_Reserved_183
  • K_Reserved_184
  • K_Reserved_185
  • K_Reserved_186
  • K_Reserved_187
  • K_Comma
  • K_Reserved_189
  • K_Period
  • K_Reserved_191
TKeysBooleans = array [TKey] of Boolean;
 
PKeysBooleans = ˆTKeysBooleans;
 
TKeysBytes = array [Byte] of TKey;
 
PKeysBytes = ˆTKeysBytes;
 
TCharactersBooleans = array [Char] of Boolean;
 
PCharactersBooleans = ˆTCharactersBooleans;
 
TMouseButton = (...);
 
Values
  • mbLeft
  • mbMiddle
  • mbRight
  • mbExtra1
  • mbExtra2
TMouseButtons = set of TMouseButton;
 
TMouseCursor = (...);

Look of the mouse cursor. Used for various properties: TUIControl.Cursor, T3D.Cursor, TCastleWindowCustom.Cursor.

mcDefault, mcNone, mcForceNone, mcCustom 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 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.

  • mcCustom: Use a custom cursor image in TCastleWindowCustom.CustomCursor.

    In normal circumstances, this should not be used for TUIControl.Cursor, T3D.Cursor and others, as they have no way to set TCastleWindowCustom.CustomCursor.

  • mcStandard: Standard arrow, indicates, well, 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.
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;
 

Constants

MouseButtonStr: array [TMouseButton] of string = ('left', 'middle', 'right', 'extra1', 'extra2');
 
ModifierKeyToKey: array[TModifierKey]of TKey = (K_Ctrl, K_Shift, K_Alt);
 
MouseWheelDirectionStr: array [TMouseWheelDirection] of string = ('none', 'up', 'down', 'left', 'right');
 

Generated by PasDoc 0.14.0.