Gorilla.Controller.Input Unit Reference
Main input controller component for keyboard, mouse, and gamepad handling.
Unit: Gorilla.Controller.Input
TGorillaInputController
High-performance, asynchronous input polling controller.
Inheritance: TGorillaController → TGorillaInputController
Platforms: All Gorilla platforms
Overview
TGorillaInputController provides a centralized, thread-safe input handling system. It continuously monitors input devices and triggers HotKeys and Sequences based on input combinations.
Architecture:
TGorillaInputController
├── Input Handlers (threads)
│ ├── Keyboard Handler
│ ├── Mouse Handler
│ └── GamePad Handler
├── Input Thread (HotKey/Sequence detection)
└── Main Thread (Event callbacks)
Constructor/Destructor
Create
constructor Create(AOwner: TComponent); override;
Creates input controller with default settings:
- All devices enabled
- High-performance hooks enabled (Windows)
- Handler sensitivity: 10ms
- Empty HotKey and Sequence collections
Destroy
destructor Destroy; override;
Stops all handler threads, clears collections, and frees resources.
Properties
Enabled
property Enabled: Boolean read GetEnabled write SetEnabled;
Enables or disables input polling.
Default: False
Behavior:
- When enabled: Starts handler threads and input detection
- When disabled: Stops all handlers, no input processing
Supported
property Supported: TGorillaInputDeviceTypes read FSupported write SetSupported;
Defines which input devices are monitored.
Type: Set of (Keyboard, Mouse, GamePad)
Default: [Keyboard, Mouse, GamePad]
Example:
// Desktop game - keyboard and mouse only
GorillaInputController1.Supported := [Keyboard, Mouse];
// Console game - gamepad only
GorillaInputController1.Supported := [GamePad];
// All devices
GorillaInputController1.Supported := [Keyboard, Mouse, GamePad];
HighPerformanceHooks
property HighPerformanceHooks: Boolean read FHighPerformanceHooks
write SetHighPerformanceHooks default True;
Enables low-level hooks for keyboard and mouse (Windows only).
Default: True
Platform: Windows only (ignored on other platforms)
Trade-offs:
| Enabled (True) | Disabled (False) |
|---|---|
| Better input response | Slower input response |
| Global input capture | Window-focused only |
| Slower debugging | Normal debugging |
Recommendation: Disable during development, enable for release builds.
{$IFDEF DEBUG}
GorillaInputController1.HighPerformanceHooks := False;
{$ENDIF}
HotKeys
property HotKeys: TGorillaHotKeyCollection read FHotKeys write SetHotKeys;
Collection of input combination HotKeys.
Sequences
property Sequences: TGorillaInputSequenceCollection read FSequences write SetSequences;
Collection of ordered HotKey Sequences.
See: TGorillaInputSequenceCollection
Handlers
property Handlers: TGorillaInputHandlerList read FHandlers;
List of active input handlers (read-only).
Usage: Access individual handlers to configure sensitivity.
var
LHandler: TGorillaInputHandler;
begin
LHandler := GorillaInputController1.GetHandler(Keyboard);
if Assigned(LHandler) then
LHandler.Sensitivity := 5; // Poll every 5ms
end;
Methods
AddHotKey
function AddHotKey(const AName: String): TGorillaHotKeyItem; virtual;
Creates and adds a new HotKey to the collection.
Parameters:
AName- Unique HotKey name
Returns: New TGorillaHotKeyItem instance
Example:
var
LHotKey: TGorillaHotKeyItem;
begin
LHotKey := GorillaInputController1.AddHotKey('Jump');
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_SPACE);
LHotKey.TriggerOnActivate := True;
LHotKey.OnTriggered := OnJumpTriggered;
end;
FindHotKey
function FindHotKey(const AName: String): TGorillaHotKeyItem; virtual;
Searches for a HotKey by name.
Parameters:
AName- HotKey name to find
Returns: TGorillaHotKeyItem if found, nil otherwise
GetOrAddHotKey
function GetOrAddHotKey(const AName: String): TGorillaHotKeyItem; virtual;
Gets existing HotKey or creates new one if it doesn't exist.
Parameters:
AName- HotKey name
Returns: Existing or new TGorillaHotKeyItem
Usage: Safely ensures HotKey exists without checking.
IndexOfHotKey
function IndexOfHotKey(const AName: String): Integer; overload; virtual;
function IndexOfHotKey(const AKey: TGorillaHotKeyItem): Integer; overload; virtual;
Returns collection index of HotKey.
Returns: Index (0-based) or -1 if not found
HotKeyExists
function HotKeyExists(const AName: String): Boolean; virtual;
Checks if HotKey with specified name exists.
RemoveHotKey
procedure RemoveHotKey(const AName: String); overload; virtual;
procedure RemoveHotKey(const AKey: TGorillaHotKeyItem); overload; virtual;
Removes HotKey from collection by name or instance.
AddSequence
function AddSequence(const AName: String;
const AHotKeys: TArray<TGorillaHotKeyItem>): TGorillaInputSequenceItem; virtual;
Creates and adds a new Sequence to the collection.
Parameters:
AName- Unique Sequence nameAHotKeys- Array of HotKeys to chain
Returns: New TGorillaInputSequenceItem or nil if AHotKeys is empty
Example:
var
LHK1, LHK2, LHK3: TGorillaHotKeyItem;
LSeq: TGorillaInputSequenceItem;
begin
LHK1 := GorillaInputController1.AddHotKey('Up');
LHK1.AddInput(Keyboard, GORILLA_INPUT_KEY_ARROW_UP);
LHK2 := GorillaInputController1.AddHotKey('Down');
LHK2.AddInput(Keyboard, GORILLA_INPUT_KEY_ARROW_DOWN);
LHK3 := GorillaInputController1.AddHotKey('A');
LHK3.AddInput(Keyboard, GORILLA_INPUT_KEY_A);
// Create Up-Down-A sequence
LSeq := GorillaInputController1.AddSequence('Combo1', [LHK1, LHK2, LHK3]);
LSeq.Sensitivity := 500;
LSeq.OnTriggered := OnCombo1Triggered;
end;
GetHandler
function GetHandler(const ADevice: TGorillaInputDeviceType): TGorillaInputHandler; virtual;
Retrieves handler for specified device type.
Parameters:
ADevice- Device type (Keyboard, Mouse, GamePad)
Returns: Handler instance or nil if not found
Example:
var
LKbdHandler: TGorillaInputHandler;
begin
LKbdHandler := GorillaInputController1.GetHandler(Keyboard);
if Assigned(LKbdHandler) then
begin
LKbdHandler.Enabled := True;
LKbdHandler.Sensitivity := 10;
end;
end;
GetPersistentMessage
function GetPersistentMessage(const ADevice: TGorillaInputDeviceType;
const ACode: TGorillaInputCode; out AMessage: TGorillaInputMessage): Boolean; virtual;
Retrieves persistent message (mouse position, gamepad triggers/thumbsticks).
Parameters:
ADevice- Device typeACode- Input codeAMessage- Output message structure
Returns: True if message available
Persistent Codes:
GORILLA_INPUT_MOUSE_POSITIONGORILLA_INPUT_GAMEPAD_TRIGGER_LEFTGORILLA_INPUT_GAMEPAD_TRIGGER_RIGHTGORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_LEFTGORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_RIGHT
Example:
var
LMsg: TGorillaInputMessage;
LPos: TPoint;
begin
if GorillaInputController1.GetPersistentMessage(Mouse,
GORILLA_INPUT_MOUSE_POSITION, LMsg) then
begin
LPos := LMsg.Data.AsType<TPoint>;
// Use LPos.X, LPos.Y
end;
end;
GetLastMousePosition
function GetLastMousePosition(out APos: TPoint): Boolean;
Convenience method to get last mouse position.
Parameters:
APos- Output screen coordinates
Returns: True if position available
GetLastGamePadTriggers
function GetLastGamePadTriggers(out APos: TPoint): Boolean;
Convenience method to get gamepad trigger values.
Parameters:
APos- Output (X=Left trigger, Y=Right trigger, 0-255 each)
Returns: True if values available
GetLastGamePadThumbstickPosLeft
function GetLastGamePadThumbstickPosLeft(out APos: TPointF): Boolean;
Convenience method to get left thumbstick position.
Parameters:
APos- Output normalized coordinates (-1.0 to +1.0)
Returns: True if position available
GetLastGamePadThumbstickPosRight
function GetLastGamePadThumbstickPosRight(out APos: TPointF): Boolean;
Convenience method to get right thumbstick position.
Parameters:
APos- Output normalized coordinates (-1.0 to +1.0)
Returns: True if position available
SetCursorPos
procedure SetCursorPos(APoint: TPoint);
Sets mouse cursor position asynchronously (thread-safe).
Parameters:
APoint- Screen coordinates
Events
OnMouseDown
property OnMouseDown: TGorillaInputMouseEvent read FOnMouseDown write FOnMouseDown;
Fired when mouse button is pressed.
Signature:
TGorillaInputMouseEvent = procedure(ASender: TObject;
AStates: TGorillaMouseStates; APos: TPointF) of object;
Parameters:
AStates- Mouse button states (set)APos- Mouse position
OnMouseUp
property OnMouseUp: TGorillaInputMouseEvent read FOnMouseUp write FOnMouseUp;
Fired when mouse button is released.
OnMouseDblClick
property OnMouseDblClick: TGorillaInputMouseEvent read FOnMouseDblClick write FOnMouseDblClick;
Fired on mouse button double-click.
OnMouseMove
property OnMouseMove: TGorillaInputMouseMoveEvent read FOnMouseMove write FOnMouseMove;
Fired when mouse moves.
Signature:
TGorillaInputMouseMoveEvent = procedure(ASender: TObject;
AStates: TGorillaMouseStates; APos: TPointF) of object;
OnMouseWheel
property OnMouseWheel: TGorillaInputMouseWheelEvent read FOnMouseWheel write FOnMouseWheel;
Fired when mouse wheel scrolls.
Signature:
TGorillaInputMouseWheelEvent = procedure(ASender: TObject; APos: TPointF;
const AWheelDelta: Integer) of object;
OnKeyDown
property OnKeyDown: TGorillaInputKeyEvent read FOnKeyDown write FOnKeyDown;
Fired when keyboard key is pressed.
Signature:
TGorillaInputKeyEvent = procedure(ASender: TObject;
AKeyCode: Integer) of object;
OnKeyUp
property OnKeyUp: TGorillaInputKeyEvent read FOnKeyUp write FOnKeyUp;
Fired when keyboard key is released.
OnGamePadConnect
property OnGamePadConnect: TGorillaInputGamePadEvent read FOnGamePadConnect
write FOnGamePadConnect;
Fired when gamepad is connected.
Signature:
TGorillaInputGamePadEvent = procedure(ASender: TObject;
AState: TGorillaInputCode; AUser: Integer) of object;
Parameters:
AState-GORILLA_INPUT_GAMEPAD_CONNECTEDAUser- Gamepad user index (0-3)
OnGamePadDisconnect
property OnGamePadDisconnect: TGorillaInputGamePadEvent read FOnGamePadDisconnect
write FOnGamePadDisconnect;
Fired when gamepad is disconnected.
OnGamePadButtonDown
property OnGamePadButtonDown: TGorillaInputGamePadButtonEvent
read FOnGamePadButtonDown write FOnGamePadButtonDown;
Fired when gamepad button is pressed.
Signature:
TGorillaInputGamePadButtonEvent = procedure(ASender: TObject;
AState: TGorillaInputCode; AButtons: TGorillaGamePadButtons) of object;
OnGamePadButtonUp
property OnGamePadButtonUp: TGorillaInputGamePadButtonEvent
read FOnGamePadButtonUp write FOnGamePadButtonUp;
Fired when gamepad button is released.
OnGamePadTrigger
property OnGamePadTrigger: TGorillaInputGamePadTriggerEvent
read FOnGamePadTrigger write FOnGamePadTrigger;
Fired when gamepad trigger value changes.
Signature:
TGorillaInputGamePadTriggerEvent = procedure(ASender: TObject;
AState: TGorillaInputCode; const AButtons: TGorillaGamePadButtons;
AValue: Byte; AFlags: UInt64) of object;
Parameters:
AValue- Trigger pressure (0-255)
OnGamePadFeedback
property OnGamePadFeedback: TGorillaInputGamePadFeedbackEvent
read FOnGamePadFeedback write FOnGamePadFeedback;
Fired when gamepad thumbstick position changes.
Signature:
TGorillaInputGamePadFeedbackEvent = procedure(ASender: TObject;
AState: TGorillaInputCode; const AButtons: TGorillaGamePadButtons;
APos: TPointF; AFlags: UInt64) of object;
Parameters:
APos- Thumbstick position (normalized -1.0 to +1.0)
TGorillaHotKeyItem
Individual HotKey item representing an input combination.
Properties
Name
property Name: String read FName write FName;
Unique HotKey identifier.
Enabled
property Enabled: Boolean read FEnabled write SetEnabled default true;
Enables or disables HotKey detection.
Default: True
TriggerOnActivate
property TriggerOnActivate: Boolean read FTriggerOnActivate
write SetTriggerOnActivate;
Triggers event when all inputs are pressed.
Default: False
TriggerOnDeactivate
property TriggerOnDeactivate: Boolean read FTriggerOnDeactivate
write SetTriggerOnDeactivate;
Triggers event when all inputs are released.
Default: False
Combinations
property Combinations: TGorillaHotKeyCombinations read FCombinations
write SetCombinations;
Collection of input codes forming the HotKey combination.
LockTime
property LockTime: UInt32 read FLockTime write FLockTime;
Milliseconds before HotKey can trigger again after activation.
Default: 0 (no lock)
Use Cases:
- Attack cooldowns
- Prevent double-triggers
- Animation timing
Action
property Action: TAction read FAction write FAction;
Optional FMX TAction to execute on trigger.
OnTriggered
property OnTriggered: TGorillaOnHotKeyTriggered read FOnTriggered write FOnTriggered;
Event callback on HotKey trigger.
Signature:
TGorillaOnHotKeyTriggered = procedure(const AItem: TGorillaHotKeyItem;
const ACurrentInput: TGorillaHotKeyRaw; const AMode: TGorillaInputMode) of object;
Parameters:
AItem- The triggered HotKeyACurrentInput- Raw input stateAMode-ActivatedorDeactivated
Tag
property Tag: NativeInt read FTag write FTag;
Application-specific data storage.
Methods
AddInput
function AddInput(const AKind: TGorillaInputDeviceType;
const ACode: TGorillaInputCode): TGorillaHotKeyInputItem;
Adds an input to the HotKey combination.
Parameters:
AKind- Device type (Keyboard, Mouse, GamePad)ACode- Input code constant
Returns: New combination item
Example:
LHotKey := GorillaInputController1.AddHotKey('SpecialMove');
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_CTRL_LEFT);
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_SPACE);
LHotKey.AddInput(Mouse, GORILLA_INPUT_MOUSE_LBUTTON);
GetOrAddInput
function GetOrAddInput(const AKind: TGorillaInputDeviceType;
const ACode: TGorillaInputCode): TGorillaHotKeyInputItem;
Gets existing input or adds new one if it doesn't exist.
IndexOfInput
function IndexOfInput(const AKind: TGorillaInputDeviceType;
const ACode: TGorillaInputCode): Integer;
Returns index of input in combinations.
Returns: Index or -1 if not found
ClearInputs
procedure ClearInputs();
Removes all inputs from combination.
Update
procedure Update();
Rebuilds internal raw key map after changing inputs.
Usage: Call after modifying combinations to ensure changes take effect.
Trigger
procedure Trigger(const ACurrentInput: TGorillaHotKeyRaw;
const AMode: TGorillaInputMode); virtual;
Manually triggers HotKey (simulation/testing).
TriggerSync
function TriggerSync(const ACurrentInput: TGorillaHotKeyRaw;
const AMode: TGorillaInputMode): Boolean; virtual;
Manually triggers HotKey synchronized with main thread.
TGorillaHotKeyCollection
Collection of HotKey items.
Methods
SetUpdateRawMap
procedure SetUpdateRawMap();
Flags collection for raw map update on next detection cycle.
UpdateRawMap
procedure UpdateRawMap();
Rebuilds internal hash map for HotKey detection. Called automatically by input thread.
TGorillaInputSequenceItem
Sequence item representing ordered HotKey chain.
Properties
Name
property DisplayName: String read GetDisplayName write SetDisplayName;
Unique Sequence identifier.
Enabled
property Enabled: Boolean read FEnabled write FEnabled default true;
Enables or disables Sequence detection.
Default: True
Sensitivity
property Sensitivity: Integer read FSensitivity write FSensitivity;
Maximum milliseconds between HotKey activations.
Default: 500ms (GORILLA_INPUT_SEQUENCE_SENSITIVITY)
HotKeys
property HotKeys: TGorillaInputSequenceHotKeyCollection read FHotKeys write SetHotKeys;
Ordered collection of HotKey links (max 16).
Action
property Action: TAction read FAction write FAction;
Optional FMX TAction to execute on trigger.
OnTriggered
property OnTriggered: TOnGorillaInputSequenceTriggered read FOnTriggered write FOnTriggered;
Event callback on Sequence trigger.
Signature:
TOnGorillaInputSequenceTriggered = procedure(
const ASequence: TGorillaInputSequenceItem) of object;
Methods
AddHotKeyItem
function AddHotKeyItem(AHotKey: TGorillaHotKeyItem): TGorillaInputSequenceHotKeyItem;
Adds HotKey to sequence.
Parameters:
AHotKey- HotKey instance to add
Returns: New sequence link item
GetHotKeyItem
function GetHotKeyItem(AHotKey: TGorillaHotKeyItem): TGorillaInputSequenceHotKeyItem;
Retrieves sequence link for HotKey.
HotKeyItemExists
function HotKeyItemExists(AHotKey: TGorillaHotKeyItem): Boolean;
Checks if HotKey exists in sequence.
IndexOfHotKeyItem
function IndexOfHotKeyItem(AHotKey: TGorillaHotKeyItem): Integer;
Returns index of HotKey in sequence.
Returns: Index or -1 if not found
RemoveHotKeyItem
procedure RemoveHotKeyItem(AHotKey: TGorillaHotKeyItem);
Removes HotKey from sequence.
Trigger
procedure Trigger(); virtual;
Manually triggers Sequence (simulation/testing).
TriggerSync
procedure TriggerSync(); virtual;
Manually triggers Sequence synchronized with main thread.
TGorillaInputSequenceCollection
Collection of Sequence items.
Methods
GetSequence
function GetSequence(const AIndex: Integer): TGorillaInputSequenceItem;
Gets Sequence by index.
Returns: Sequence item or nil if invalid index
FindSequence
function FindSequence(const AName: String): TGorillaInputSequenceItem;
Searches for Sequence by name.
Returns: First matching Sequence or nil
SequenceExists
function SequenceExists(const AName: String): Boolean;
Checks if Sequence with name exists.
IndexOfSequence
function IndexOfSequence(const AName: String): Integer;
Returns index of Sequence.
Returns: Index or -1 if not found
RemoveSequence
procedure RemoveSequence(const AName: String);
Removes Sequence by name.
Constants
Input Limits
// Maximum inputs per device in HotKey
GORILLA_HOTKEY_INPUTS_MAX = 4;
// Maximum HotKeys in Sequence
GORILLA_INPUT_SEQUENCE_HOTKEY_MAX = 16;
// Maximum simultaneous gamepads
GORILLA_GAMEPAD_USER_MAX = 4; // Windows (XInput)
GORILLA_GAMEPAD_USER_MAX = 1; // Android, iOS
Timing
// Handler polling interval (ms)
GORILLA_INPUT_HANDLER_SENSITIVITY = 10;
// Default sequence sensitivity (ms)
GORILLA_INPUT_SEQUENCE_SENSITIVITY = 500;
// GamePad availability check interval (ms)
GORILLA_GAMEPAD_AVAILIBILITY_CHECK = 3000;
See Also
- Input Controller User Guide
- Gorilla.Controller.Input.Types - Type definitions
- Gorilla.Controller.Input.Consts - Input code constants