Castle Game Engine

Class TInputShortcut

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleInputs

Declaration

type TInputShortcut = class(TComponent)

Description

A keyboard and/or mouse shortcut for activating some action.

Action may be activated by:

The difference between key shortcut and character shortcut: "Key" is something that can be expressed as TKey value. "KeyString" is an UTF-8 character that can be expressed as String value.

They are keys like "control key" (keyCtrl) or "shift key" (keyShift) that cannot be expressed (on their own) as KeyString. KeyString is sometimes more, sometimes less specific than Key: character "A" (upper letter "a") is activated by pressing "a", but only when Shift is pressed or CapsLock is on (window system / GUI toolkit may also allow other ways to input characters).

Name of this component is additionally used if this is a global input shortcut (with Group <> igLocal, see CastleInputs unit documentation): it is used for config file entries and for the CastleScript shortcut() function [https://castle-engine.io/castle_script.php#function_shortcut] . Any valid Pascal identifier will be Ok for these purposes.

Hierarchy

Overview

Methods

Protected procedure Changed; virtual;
Public constructor Create(AOwner: TComponent); overload; override;
Public constructor Create(const AOwner: TComponent; const ACaption: string; const AName: string; const AGroup: TInputGroup); reintroduce; overload;
Public procedure MakeDefault;
Public procedure AssignFromDefault(Source: TInputShortcut);
Public procedure Assign(Source: TInputShortcut; CopyDefaults: boolean); reintroduce; overload;
Public procedure Assign( const AKey1: TKey; const AKey2: TKey = keyNone; AKeyString: String = ''; const AMouseButtonUse: boolean = false; const AMouseButton: TCastleMouseButton = buttonLeft; const AMouseWheel: TMouseWheelDirection = mwNone); reintroduce; overload;
Public procedure AssignCurrent( const AKey1: TKey; const AKey2: TKey = keyNone; AKeyString: String = ''; const AMouseButtonUse: boolean = false; const AMouseButton: TCastleMouseButton = buttonLeft; const AMouseWheel: TMouseWheelDirection = mwNone);
Public procedure MakeClear(const ClearAlsoDefaultState: boolean = false);
Public function IsPressed(const Pressed: TKeysPressed; const MousePressed: TCastleMouseButtons): boolean; overload;
Public function IsPressed(const Container: TCastleContainer): boolean; overload;
Public function IsKey(const Key: TKey; AKeyString: String): boolean;
Public function IsMouseButton(const AMouseButton: TCastleMouseButton; const ModifiersDown: TModifierKeys): boolean; overload;
Public function IsMouseButton(const AMouseButton: TCastleMouseButton): boolean; overload; deprecated 'use overloaded version with additional ModifiersDown parameter';
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
Public function IsEvent(const Event: TInputPressRelease): boolean; overload;
Public function IsEvent(const AKey: TKey; AKeyString: String; const AMousePress: boolean; const AMouseButton: TCastleMouseButton; const AMouseWheel: TMouseWheelDirection; const ModifiersDown: TModifierKeys = []): boolean; overload; deprecated 'use IsEvent(TInputPressRelease)';
Public function Description(const NoneString: string): string; overload;
Public function Description: string; overload;
Public function Modifiers: TModifierKeys;
Public procedure Add(const NewEvent: TInputPressRelease);
Public procedure LoadFromConfig(const Config: TCastleConfig; ConfigPath: String);
Public procedure SaveToConfig(const Config: TCastleConfig; ConfigPath: String);

Properties

Public property Caption: string read FCaption;
Public property Group: TInputGroup read FGroup;
Public property GroupOrder: Integer read FGroupOrder write FGroupOrder;
Published property Key1: TKey read FKey1 write SetKey1;
Published property Key2: TKey read FKey2 write SetKey2;
Published property KeyString: String read FKeyString write SetKeyString;
Published property Character: Char read GetCharacter write SetCharacter; deprecated 'use KeyString';
Published property MouseButtonUse: boolean read FMouseButtonUse write SetMouseButtonUse;
Published property MouseButton: TCastleMouseButton read FMouseButton write SetMouseButton;
Published property MouseButtonCheckModifiers: TModifierKeys read FMouseButtonCheckModifiers write SetMouseButtonCheckModifiers;
Published property MouseButtonModifiers: TModifierKeys read FMouseButtonModifiers write SetMouseButtonModifiers;
Published property MouseButton2Use: boolean read FMouseButton2Use write SetMouseButton2Use;
Published property MouseButton2: TCastleMouseButton read FMouseButton2 write SetMouseButton2;
Published property MouseButton2CheckModifiers: TModifierKeys read FMouseButton2CheckModifiers write SetMouseButton2CheckModifiers;
Published property MouseButton2Modifiers: TModifierKeys read FMouseButton2Modifiers write SetMouseButton2Modifiers;
Published property MouseWheel: TMouseWheelDirection read FMouseWheel write SetMouseWheel;
Published property DefaultKey1: TKey read FDefaultKey1 write FDefaultKey1;
Published property DefaultKey2: TKey read FDefaultKey2 write FDefaultKey2;
Published property DefaultKeyString: String read FDefaultKeyString write FDefaultKeyString;
Published property DefaultMouseButtonUse: boolean read FDefaultMouseButtonUse write FDefaultMouseButtonUse;
Published property DefaultMouseButton: TCastleMouseButton read FDefaultMouseButton write FDefaultMouseButton;
Published property DefaultMouseButtonCheckModifiers: TModifierKeys read FDefaultMouseButtonCheckModifiers write FDefaultMouseButtonCheckModifiers;
Published property DefaultMouseButtonModifiers: TModifierKeys read FDefaultMouseButtonModifiers write FDefaultMouseButtonModifiers;
Published property DefaultMouseButton2Use: boolean read FDefaultMouseButton2Use write FDefaultMouseButton2Use;
Published property DefaultMouseButton2: TCastleMouseButton read FDefaultMouseButton2 write FDefaultMouseButton2;
Published property DefaultMouseButton2CheckModifiers: TModifierKeys read FDefaultMouseButton2CheckModifiers write FDefaultMouseButton2CheckModifiers;
Published property DefaultMouseButton2Modifiers: TModifierKeys read FDefaultMouseButton2Modifiers write FDefaultMouseButton2Modifiers;
Published property DefaultMouseWheel: TMouseWheelDirection read FDefaultMouseWheel write FDefaultMouseWheel;

Description

Methods

Protected procedure Changed; virtual;

Called always right after the shortcut value changed (like key or mouse buton). Called only when the current values changed, not called when just the default values changed.

Public constructor Create(AOwner: TComponent); overload; override;

Constructor that always creates local shortcuts (with Group = igLocal). Caption and Name are left empty (they do not have to be set for local shortcuts; although you may wish to later assign Name anyway, if you use this as sub-component in Lazarus).

Public constructor Create(const AOwner: TComponent; const ACaption: string; const AName: string; const AGroup: TInputGroup); reintroduce; overload;

Flexible constructor that allows to set Group and choose global or local shortcut.

Public procedure MakeDefault;
 
Public procedure AssignFromDefault(Source: TInputShortcut);

Assigns to this object the default values from Source.

Public procedure Assign(Source: TInputShortcut; CopyDefaults: boolean); reintroduce; overload;

Copy Source properties to this object. It always copies current properties (Key1, MouseButton etc.), and only optionally (if CopyDefaults) also copies the DefaultXxx properties.

Public procedure Assign( const AKey1: TKey; const AKey2: TKey = keyNone; AKeyString: String = ''; const AMouseButtonUse: boolean = false; const AMouseButton: TCastleMouseButton = buttonLeft; const AMouseWheel: TMouseWheelDirection = mwNone); reintroduce; overload;

Set keys/mouse buttons of this shortcut.

Sets both current and default properties (e.g. both Key1 and DefaultKey1 to the same value). Note that, right after using this method, saving the input to a config file (using TInputShortcutList.SaveToConfig) will actually just "clear" the input information from the config file (because we do not save the value when it is equal to the default). Use AssignCurrent to only assign the curent value, leaving default untouched.

Public procedure AssignCurrent( const AKey1: TKey; const AKey2: TKey = keyNone; AKeyString: String = ''; const AMouseButtonUse: boolean = false; const AMouseButton: TCastleMouseButton = buttonLeft; const AMouseWheel: TMouseWheelDirection = mwNone);

Set keys/mouse buttons of this shortcut. Sets only the "current" properties (e.g. it changes Key1, leaving DefaultKey1 unmodified).

Public procedure MakeClear(const ClearAlsoDefaultState: boolean = false);

Make this input impossible to activate by the user. This sets both keys to keyNone, KeyString to '', both MouseButtonUse and MouseButton2Use to False, and MouseWheel to mwNone.

Public function IsPressed(const Pressed: TKeysPressed; const MousePressed: TCastleMouseButtons): boolean; overload;

Given a set of currently pressed keys and mouse buttons, decide whether this input is currently pressed.

Public function IsPressed(const Container: TCastleContainer): boolean; overload;

Looking at Container's currently pressed keys and mouse buttons, decide whether this input is currently pressed.

Public function IsKey(const Key: TKey; AKeyString: String): boolean;

Check does given Key or AKeyString correspond to this input shortcut. If Key = keyNone and AString = '', result is always False.

Public function IsMouseButton(const AMouseButton: TCastleMouseButton; const ModifiersDown: TModifierKeys): boolean; overload;

Check does given mouse button correspond to this input shortcut.

Public function IsMouseButton(const AMouseButton: TCastleMouseButton): boolean; overload; deprecated 'use overloaded version with additional ModifiersDown parameter';

Warning: this symbol is deprecated: use overloaded version with additional ModifiersDown parameter

 
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
 
Public function IsEvent(const Event: TInputPressRelease): boolean; overload;

Check does given event (key press, mouse button press, mouse wheel) activates this shortcut.

Public function IsEvent(const AKey: TKey; AKeyString: String; const AMousePress: boolean; const AMouseButton: TCastleMouseButton; const AMouseWheel: TMouseWheelDirection; const ModifiersDown: TModifierKeys = []): boolean; overload; deprecated 'use IsEvent(TInputPressRelease)';

Warning: this symbol is deprecated: use IsEvent(TInputPressRelease)

 
Public function Description(const NoneString: string): string; overload;

Describe the current value (which key, mouse buttons and such) of this shortcut. If there is no way to press this shortcut (all properties like Key1 and such are empty, like after MakeClear), we will use NoneString.

The overloaded version without NoneString parameter will assume that NoneString should describe the shortcut Caption. This way, if user cleared (deleted all key/mouse buttons assigned) the shortcut in the game configuration, and we show him a message like: 

'Press ' + Input.Description + ' to do something'

then user will see it as 'Press "use" key to do something' and will know that (s)he should configure the "use" key.

Public function Description: string; overload;
 
Public function Modifiers: TModifierKeys;

Modifier keys that are relevant to recognize this shortcut.

Public procedure Add(const NewEvent: TInputPressRelease);

Add to shortcut new key or mouse button or mouse wheel.

Public procedure LoadFromConfig(const Config: TCastleConfig; ConfigPath: String);

Load a particular input from a config file. Use this to load what was previously saved with SaveToConfig.

Public procedure SaveToConfig(const Config: TCastleConfig; ConfigPath: String);

Save a particular input to a config file. This creates an XML element named Name under the indicated ConfigPath in the config file.

Note: It is often easier to group your controls in TInputShortcutList, and call TInputShortcutList.SaveToConfig to save everything.

Properties

Public property Caption: string read FCaption;

Nice name to show user. With spaces, localized characters etc.

Public property Group: TInputGroup read FGroup;

Group of the global shortcut, or igLocal indicating a local shortcut. Games may use this group to better show the keys configuration for user, presenting together keys from the same group.

Public property GroupOrder: Integer read FGroupOrder write FGroupOrder;

Order of the shortcut within it's Group. The order may be important, as menus may show InputsGroup to user in this order. This order is applied (the group is actually sorted by GroupOrder) when reading config file. For equal GroupOrder, the order of creation (equal to the order on InputsAll list) decides which is first.

Published property Key1: TKey read FKey1 write SetKey1;

Key shortcuts for given command. You can set any of them to keyNone to indicate that no key is assigned.

Published property Key2: TKey read FKey2 write SetKey2;
 
Published property KeyString: String read FKeyString write SetKeyString;

Character shortcut for given command, may be UTF-8 character (multi-byte). You can set this to '' to indicate that no character shortcut is assigned.

Published property Character: Char read GetCharacter write SetCharacter; deprecated 'use KeyString';

Warning: this symbol is deprecated: use KeyString

 
Published property MouseButtonUse: boolean read FMouseButtonUse write SetMouseButtonUse;

Mouse shortcut for given command. Only relevant if MouseButtonUse is True. Then we check for MouseButton being pressed.

MouseButtonCheckModifiers determines what subset of modifiers (Ctrl, Shift, Alt) to check, whether they match MouseButtonModifiers. For example, MouseButtonCheckModifiers = [mkShift, mkCtrl] and MouseButtonModifiers = [mkCtrl] means that you have to press Ctrl, and you cannot keep Shift pressed, to activate this shortcut.

By default MouseButtonCheckModifiers and MouseButtonModifiers are both empty sets, which means that any state of modifiers is OK.

Published property MouseButton: TCastleMouseButton read FMouseButton write SetMouseButton;
 
Published property MouseButtonCheckModifiers: TModifierKeys read FMouseButtonCheckModifiers write SetMouseButtonCheckModifiers;
 
Published property MouseButtonModifiers: TModifierKeys read FMouseButtonModifiers write SetMouseButtonModifiers;
 
Published property MouseButton2Use: boolean read FMouseButton2Use write SetMouseButton2Use;

Alternative mouse shortcut for given command. Only relevant if MouseButton2Use is True. All properties work analogously to MouseButtonUse, MouseButton, MouseButtonCheckModifiers, MouseButtonModifiers.

Published property MouseButton2: TCastleMouseButton read FMouseButton2 write SetMouseButton2;
 
Published property MouseButton2CheckModifiers: TModifierKeys read FMouseButton2CheckModifiers write SetMouseButton2CheckModifiers;
 
Published property MouseButton2Modifiers: TModifierKeys read FMouseButton2Modifiers write SetMouseButton2Modifiers;
 
Published property MouseWheel: TMouseWheelDirection read FMouseWheel write SetMouseWheel;

Mouse wheel to activate this command. Note that mouse wheels cannot be continuously pressed (our method IsPressed doesn't look at it), so this is only suitable for commands that work in steps (not continuously).

Published property DefaultKey1: TKey read FDefaultKey1 write FDefaultKey1;

Default values for properties key/mouse. You can change them — this will change what MakeDefault does.

Note that setting these properties doesn't automatically set corresponding "current" property. E.g. DefaultKey1 := keySpace; doesn't change the value of Key1 property — only DefaultKey1 changes. You can explicitly change Key1 property, or just call MakeDefault afterwards, if you want this to happen.

Published property DefaultKey2: TKey read FDefaultKey2 write FDefaultKey2;
 
Published property DefaultKeyString: String read FDefaultKeyString write FDefaultKeyString;
 
Published property DefaultMouseButtonUse: boolean read FDefaultMouseButtonUse write FDefaultMouseButtonUse;
 
Published property DefaultMouseButton: TCastleMouseButton read FDefaultMouseButton write FDefaultMouseButton;
 
Published property DefaultMouseButtonCheckModifiers: TModifierKeys read FDefaultMouseButtonCheckModifiers write FDefaultMouseButtonCheckModifiers;
 
Published property DefaultMouseButtonModifiers: TModifierKeys read FDefaultMouseButtonModifiers write FDefaultMouseButtonModifiers;
 
Published property DefaultMouseButton2Use: boolean read FDefaultMouseButton2Use write FDefaultMouseButton2Use;
 
Published property DefaultMouseButton2: TCastleMouseButton read FDefaultMouseButton2 write FDefaultMouseButton2;
 
Published property DefaultMouseButton2CheckModifiers: TModifierKeys read FDefaultMouseButton2CheckModifiers write FDefaultMouseButton2CheckModifiers;
 
Published property DefaultMouseButton2Modifiers: TModifierKeys read FDefaultMouseButton2Modifiers write FDefaultMouseButton2Modifiers;
 
Published property DefaultMouseWheel: TMouseWheelDirection read FDefaultMouseWheel write FDefaultMouseWheel;
 
Generated by PasDoc 0.16.0.