Class TInputShortcut

DescriptionHierarchyFieldsMethodsProperties

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

Protected procedure Changed; virtual;
Public constructor Create(AOwner: TComponent); override;
Public constructor Create(const AOwner: TComponent; const ACaption: string; const AName: string; const AGroup: TInputGroup);
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 = K_None; const ACharacter: Char = #0; const AMouseButtonUse: boolean = false; const AMouseButton: TMouseButton = mbLeft; const AMouseWheel: TMouseWheelDirection = mwNone);
Public procedure MakeClear(const ClearAlsoDefaultState: boolean = false);
Public function IsPressed(Pressed: TKeysPressed; const MousePressed: TMouseButtons): boolean;
Public function IsPressed(Container: TUIContainer): boolean;
Public function IsKey(Key: TKey; ACharacter: Char): boolean;
Public function IsMouseButton(AMouseButton: TMouseButton): boolean;
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
Public function IsEvent(AKey: TKey; ACharacter: Char; AMousePress: boolean; AMouseButton: TMouseButton; AMouseWheel: TMouseWheelDirection): boolean;
Public function IsEvent(const Event: TInputPressRelease): boolean;
Public function Description(const NoneString: string): string;
Public function Description: string;
Public function Modifiers: TModifierKeys;
Public procedure Add(const NewEvent: TInputPressRelease);

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 Character: Char read FCharacter write SetCharacter;
Published property MouseButtonUse: boolean read FMouseButtonUse write SetMouseButtonUse;
Published property MouseButton: TMouseButton read FMouseButton write SetMouseButton;
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 DefaultCharacter: Char read FDefaultCharacter write FDefaultCharacter;
Published property DefaultMouseButtonUse: boolean read FDefaultMouseButtonUse write FDefaultMouseButtonUse;
Published property DefaultMouseButton: TMouseButton read FDefaultMouseButton write FDefaultMouseButton;
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, Character, MouseButtonUse, MouseButton, MouseWheel) changed, and it's not called when just the DefaultXxx values changed.

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

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

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, Character, MouseButtonUse, MouseButton, MouseWheel), and optionally (if CopyDefaults) also copies the DefaultXxx properties.

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

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

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

Public function IsPressed(Container: TUIContainer): boolean;

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

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

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

Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
 
Public 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.

Public function IsEvent(const Event: TInputPressRelease): boolean;
 
Public 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.

Public function Description: string;
 
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.

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 K_None to indicate that no key is assigned.

Published property Key2: TKey read FKey2 write SetKey2;
 
Published 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.

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: TMouseButton read FMouseButton write SetMouseButton;
 
Published 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).

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 := 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.

Published property DefaultKey2: TKey read FDefaultKey2 write FDefaultKey2;
 
Published property DefaultCharacter: Char read FDefaultCharacter write FDefaultCharacter;
 
Published property DefaultMouseButtonUse: boolean read FDefaultMouseButtonUse write FDefaultMouseButtonUse;
 
Published property DefaultMouseButton: TMouseButton read FDefaultMouseButton write FDefaultMouseButton;
 
Published property DefaultMouseWheel: TMouseWheelDirection read FDefaultMouseWheel write FDefaultMouseWheel;
 

Generated by PasDoc 0.13.0 on 2014-04-30 22:06:43