Castle Game Engine: CastleInputs: Class TInputShortcut

# 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: 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. "Character" is something that can be expressed as Char value. They are keys like "control key" (K_Ctrl) or "shift key" (K_Shift) that cannot be expressed (on their own) as characters. Characters are both more and less specific: 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 [castle-engine.sourceforge.net/castle_script.php#function_shortcut] . Any valid Pascal identifier will be Ok for these purposes. ## Hierarchy TComponent TInputShortcut ## Overview ### Methods
| `procedure Changed; virtual;`
| `constructor Create(AOwner: TComponent); override;`
| `constructor Create(const AOwner: TComponent; const ACaption: string; const AName: string; const AGroup: TInputGroup);`
| `procedure MakeDefault;`
| `procedure AssignFromDefault(Source: TInputShortcut);`
| `procedure Assign(Source: TInputShortcut; CopyDefaults: boolean); reintroduce;`
| `procedure Assign( const AKey1: TKey; const AKey2: TKey = K_None; const ACharacter: Char = #0; const AMouseButtonUse: boolean = false; const AMouseButton: TMouseButton = mbLeft; const AMouseWheel: TMouseWheelDirection = mwNone);`
| `procedure MakeClear(const ClearAlsoDefaultState: boolean = false);`
| `function IsPressed(Pressed: TKeysPressed; const MousePressed: TMouseButtons): boolean;`
| `function IsPressed(Container: TUIContainer): boolean;`
| `function IsKey(Key: TKey; ACharacter: Char): boolean;`
| `function IsMouseButton(AMouseButton: TMouseButton): boolean;`
| `function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;`
| `function IsEvent(AKey: TKey; ACharacter: Char; AMousePress: boolean; AMouseButton: TMouseButton; AMouseWheel: TMouseWheelDirection): boolean;`
| `function IsEvent(const Event: TInputPressRelease): boolean;`
| `function Description(const NoneString: string): string;`
| `function Description: string;`
| `function Modifiers: TModifierKeys;`
| `procedure Add(const NewEvent: TInputPressRelease);`
### Properties
| `property Caption: string read FCaption;`
| `property Group: TInputGroup read FGroup;`
| `property GroupOrder: Integer read FGroupOrder write FGroupOrder;`
| `property Key1: TKey read FKey1 write SetKey1;`
| `property Key2: TKey read FKey2 write SetKey2;`
| `property Character: Char read FCharacter write SetCharacter;`
| `property MouseButtonUse: boolean read FMouseButtonUse write SetMouseButtonUse;`
| `property MouseButton: TMouseButton read FMouseButton write SetMouseButton;`
| `property MouseWheel: TMouseWheelDirection read FMouseWheel write SetMouseWheel;`
| `property DefaultKey1: TKey read FDefaultKey1 write FDefaultKey1;`
| `property DefaultKey2: TKey read FDefaultKey2 write FDefaultKey2;`
| `property DefaultCharacter: Char read FDefaultCharacter write FDefaultCharacter;`
| `property DefaultMouseButtonUse: boolean read FDefaultMouseButtonUse write FDefaultMouseButtonUse;`
| `property DefaultMouseButton: TMouseButton read FDefaultMouseButton write FDefaultMouseButton;`
| `property DefaultMouseWheel: TMouseWheelDirection read FDefaultMouseWheel write FDefaultMouseWheel;`
## Description ### Methods
| `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, Character, MouseButtonUse, MouseButton, MouseWheel) changed, and it's not called when just the DefaultXxx values changed.
| `constructor Create(AOwner: TComponent); 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).
| `constructor Create(const AOwner: TComponent; const ACaption: string; const AName: string; const AGroup: TInputGroup);`
Flexible constructor that allows to set Group and choose global or local shortcut.
| `procedure MakeDefault;`
| `procedure AssignFromDefault(Source: TInputShortcut);`
Assigns to this object the default values from Source.
| `procedure Assign(Source: TInputShortcut; CopyDefaults: boolean); reintroduce;`
Copy Source properties to this object. It always copies "current" properties (Key1, Key2, Character, MouseButtonUse, MouseButton, MouseWheel), and optionally (if CopyDefaults) also copies the DefaultXxx properties.
| `procedure Assign( const AKey1: TKey; const AKey2: TKey = K_None; const ACharacter: Char = #0; const AMouseButtonUse: boolean = false; const AMouseButton: TMouseButton = mbLeft; const AMouseWheel: TMouseWheelDirection = mwNone);`
Set keys/mouse buttons of this shortcut. Sets both current and default properties.
| `procedure MakeClear(const ClearAlsoDefaultState: boolean = false);`
Make this input impossible to activate by the user. This sets both keys to K_None, Character to #0, MouseButtonUse to `False`, and MouseWheel to mwNone.
| `function IsPressed(Pressed: TKeysPressed; const MousePressed: TMouseButtons): boolean;`
Given a set of currently pressed keys and mouse buttons, decide whether this input is currently pressed.
| `function IsPressed(Container: TUIContainer): boolean;`
Looking at Container's currently pressed keys and mouse buttons, decide whether this input is currently pressed.
| `function IsKey(Key: TKey; ACharacter: Char): boolean;`
Check does given Key or ACharacter correspond to this input shortcut. If Key = K_None and ACharacter = #0, result is always `False`.
| `function IsMouseButton(AMouseButton: TMouseButton): boolean;`
Check does given mouse button correspond to this input shortcut. In practice, just checks MouseButtonUse and if `True`, compares AMouseButton with MouseButton.
| `function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;`
| `function IsEvent(AKey: TKey; ACharacter: Char; AMousePress: boolean; AMouseButton: TMouseButton; AMouseWheel: TMouseWheelDirection): boolean;`
Check does given key or mouse button or mouse wheel use activates this shortcut. For key/character press, set AKey <> K_None or ACharacter <> #0. 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 = K_None and ACharacter = #0 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.
| `function IsEvent(const Event: TInputPressRelease): boolean;`
| `function Description(const NoneString: string): string;`
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.
| `function Description: string;`
| `function Modifiers: TModifierKeys;`
Modifier keys that are relevant to recognize this shortcut.
| `procedure Add(const NewEvent: TInputPressRelease);`
Add to shortcut new key or mouse button or mouse wheel.
### Properties
| `property Caption: string read FCaption;`
Nice name to show user. With spaces, localized characters etc.
| `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.
| `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.
| `property Key1: TKey read FKey1 write SetKey1;`
Key shortcuts for given command. You can set any of them to K_None to indicate that no key is assigned.
| `property Key2: TKey read FKey2 write SetKey2;`
| `property Character: Char read FCharacter write SetCharacter;`
Character shortcut for given command. You can set this to #0 to indicate that no character shortcut is assigned.
| `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.
| `property MouseButton: TMouseButton read FMouseButton write SetMouseButton;`
| `property MouseWheel: TMouseWheelDirection read FMouseWheel write SetMouseWheel;`
Mouse wheel to activate this command. Note that mouse wheels cannot be continously pressed (our method IsPressed doesn't look at it), so this is only suitable for commands that work in steps (not continously).
| `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` := K_Space;` 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.
| `property DefaultKey2: TKey read FDefaultKey2 write FDefaultKey2;`
| `property DefaultCharacter: Char read FDefaultCharacter write FDefaultCharacter;`
| `property DefaultMouseButtonUse: boolean read FDefaultMouseButtonUse write FDefaultMouseButtonUse;`
| `property DefaultMouseButton: TMouseButton read FDefaultMouseButton write FDefaultMouseButton;`
| `property DefaultMouseWheel: TMouseWheelDirection read FDefaultMouseWheel write FDefaultMouseWheel;`
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:10