Class TInputShortcut

Unit

Declaration

type TInputShortcut = class(TComponent)

Description

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

Action may be activated by:

  • at most two key shortcuts,

  • and one mouse button shortcut,

  • and one character shortcut,

  • and one mouse wheel shortcut.

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

  • TObject
  • TPersistent
  • TComponent
  • TInputShortcut

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); overload;
Public procedure MakeDefault;
Public procedure AssignFromDefault(Source: TInputShortcut);
Public procedure Assign(Source: TInputShortcut; CopyDefaults: boolean); reintroduce;
Public procedure Assign( const AKey1: TKey; const AKey2: TKey = keyNone; AKeyString: String = ''; const AMouseButtonUse: boolean = false; const AMouseButton: TCastleMouseButton = buttonLeft; const AMouseWheel: TMouseWheelDirection = mwNone);
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(Pressed: TKeysPressed; const MousePressed: TCastleMouseButtons): boolean; overload;
Public function IsPressed(Container: TUIContainer): boolean; overload;
Public function IsKey(const Key: TKey; AKeyString: String): boolean;
Public function IsMouseButton(const AMouseButton: TCastleMouseButton): boolean;
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
Public function IsEvent(const AKey: TKey; AKeyString: String; const AMousePress: boolean; const AMouseButton: TCastleMouseButton; const AMouseWheel: TMouseWheelDirection): boolean; overload;
Public function IsEvent(const Event: TInputPressRelease): boolean; overload;
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 MouseButton2Use: boolean read FMouseButton2Use write SetMouseButton2Use;
Published property MouseButton2: TCastleMouseButton read FMouseButton2 write SetMouseButton2;
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 DefaultMouseButton2Use: boolean read FDefaultMouseButton2Use write FDefaultMouseButton2Use;
Published property DefaultMouseButton2: TCastleMouseButton read FDefaultMouseButton2 write FDefaultMouseButton2;
Published property DefaultMouseWheel: TMouseWheelDirection read FDefaultMouseWheel write FDefaultMouseWheel;

Description

Methods

Protected procedure Changed; virtual;

Called always right after the key/character/mouse shortcut value changed. Note that this is called only when the "current" values (Key1, Key2, KeyString, MouseButtonUse, MouseButton, MouseButton2Use, MouseButton2, MouseWheel) changed, and it's not called when just the DefaultXxx 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); 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;

Copy Source properties to this object. It always copies "current" properties (Key1, Key2, KeyString, MouseButtonUse, MouseButton, MouseButton2Use, MouseButton2, MouseWheel), and 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);

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 '', MouseButtonUse to False, and MouseWheel to mwNone.

Public function IsPressed(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(Container: TUIContainer): 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): boolean;

Check does given mouse button correspond to this input shortcut.

Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
 
Public function IsEvent(const AKey: TKey; AKeyString: String; const AMousePress: boolean; const AMouseButton: TCastleMouseButton; const AMouseWheel: TMouseWheelDirection): boolean; overload;

Check does given key or mouse button or mouse wheel use activates this shortcut.

For key/character press, set AKey <> keyNone or AKeyString <> ''. For mouse button press, set AMousePress to True and pass relevant AMouseButton. For mouse wheel, pass AMouseWheel <> mwNone. Pass only one of these three events here, for example if you AMousePress to True then pass AKey = keyNone and AKeyString = '' and AMouseWheel = mwNone.

Basically, this is a "dispatcher" that simply calls one of the IsKey or IsMouseButton or IsMouseWheel methods. It's sometimes more comfortable to use this instead of taking care of them separately.

Public function IsEvent(const Event: TInputPressRelease): boolean; overload;
 
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. You can set MouseButtonUse to False if you don't want to use this.

Published property MouseButton: TCastleMouseButton read FMouseButton write SetMouseButton;
 
Published property MouseButton2Use: boolean read FMouseButton2Use write SetMouseButton2Use;

Alternative mouse shortcut for given command. You can set MouseButton2Use to False if you don't want to use this.

Published property MouseButton2: TCastleMouseButton read FMouseButton2 write SetMouseButton2;
 
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 DefaultMouseButton2Use: boolean read FDefaultMouseButton2Use write FDefaultMouseButton2Use;
 
Published property DefaultMouseButton2: TCastleMouseButton read FDefaultMouseButton2 write FDefaultMouseButton2;
 
Published property DefaultMouseWheel: TMouseWheelDirection read FDefaultMouseWheel write FDefaultMouseWheel;
 

Generated by PasDoc 0.15.0.