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.

See: TGorillaHotKeyCollection

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 name
  • AHotKeys - 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 type
  • ACode - Input code
  • AMessage - Output message structure

Returns: True if message available

Persistent Codes:

  • GORILLA_INPUT_MOUSE_POSITION
  • GORILLA_INPUT_GAMEPAD_TRIGGER_LEFT
  • GORILLA_INPUT_GAMEPAD_TRIGGER_RIGHT
  • GORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_LEFT
  • GORILLA_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_CONNECTED
  • AUser - 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 HotKey
  • ACurrentInput - Raw input state
  • AMode - Activated or Deactivated

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