Object TInputPressRelease

Unit

Declaration

type TInputPressRelease = object(TObject)

Description

Input press or release event. Either key press/release or mouse button press/release or mouse wheel action. This is nicely matching with TInputShortcut processing in CastleInputs, so it allows to easily store and check for user actions.

Hierarchy

  • TObject
  • TInputPressRelease

Overview

Fields

Public EventType: TInputPressReleaseType;
Public Key: TKey;
Public KeyCharacter: char;
Public MouseButton: TMouseButton;
Public FingerIndex: TFingerIndex;
Public Position: TVector2Single;
Public MouseWheelScroll: Single;
Public MouseWheelVertical: boolean;

Methods

Public function MouseWheel: TMouseWheelDirection;
Public function IsKey(const AKey: TKey): boolean;
Public function IsKey(const AKeyCharacter: char): boolean;
Public function IsMouseButton(const AMouseButton: TMouseButton): boolean;
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
Public function ToString: string;
Public function Description: string; deprecated;

Description

Fields

Public EventType: TInputPressReleaseType;
 
Public Key: TKey;

When EventType is itKey, this is the key pressed or released. Either Key <> K_None or KeyCharacter <> #0 in this case. When EventType <> itKey, then Key = K_None and KeyCharacter = #0.

Both Key and KeyCharacter represent the same action. Sometimes one, sometimes the other is useful.

Not all key presses can be represented as TKey value. For example, pressing '(' (opening parenthesis), which is done on most keyboards by pressing shift + zero, does not have any TKey value. So it will generate event with Key = K_None, but KeyCharacter = '('.

Likewise, not all key presses can be represented as char value. For example "up arrow" (Key = K_Up) doesn't have a char code (it will have KeyCharacter = #0).

KeyCharacter is influenced by some other keys state, like Shift or Ctrl or CapsLock or some key to input localized characters (all dependent on your system settings, we don't deal with it in our engine, we merely take what system gives us). For example, you can get "a" or "A" depending of Shift and CapsLock state, or CtrlA if you hold Ctrl.

When the user holds the key pressed, we will get consecutive key down events. Under some OSes, you will also get consecutive key up events, but it's not guaranteed (on some OSes, you may simply get only consecutive key down). So the more precise definition when key down occurs is: it's a notification that the key is (still) pressed down.

Public KeyCharacter: char;
 
Public MouseButton: TMouseButton;

When EventType is itMouseButton, this is the mouse button pressed or released. Always mbLeft for touch device press/release events.

CastleWindow notes (but relevant also to other interfaces, like Lazarus component, although in that case it's beyond our control): When user presses the mouse over our control, mouse is automatically captured, so all further OnMotion following mouse release will be passed to this control (even if user moves mouse outside of this control), until user releases all mouse buttons. Note that this means that mouse positions may be outside of [0..Width - 1, 0..Height - 1] range.

Public FingerIndex: TFingerIndex;

When EventType is itMouseButton, this is the finger index pressed or released on a touch device. Always 0 for normal mouse events.

Public Position: TVector2Single;

The position of the current mouse/finger on the window, for EventType = itMouseButton (in case of mouse press/release).

For normal backends that simply support a single mouse device, this is just equivalent to TCastleWindow.MousePosition and TCastleControl.MousePosition, so it's not really interesting.

For multi-touch devices, this is very useful, as it describes the position of the current finger (corresponding to FingerIndex).

For other EventType values (not itMouseButton), this is the position of main mouse/finger. See TCastleWindow.MousePosition documentation for what it means, in particular what happens on touch devices.

Public MouseWheelScroll: Single;

When EventType is itMouseWheel, this is the mouse wheel action. MouseWheel is mwNone if and only if EventType <> itMouseWheel.

Positive value of Scroll means user scrolled up or left, negative means user scrolled down or right. It is never zero (as long as EventType = itMouseWheel of course).

Scroll units are such that 1.0 should be treated like a "one operation", like a one click. On most normal mouses only an integer scroll will be possible to make. On the other hand, on touchpads it's common to be able to scroll by flexible amounts.

CastleWindow backends notes: GTK and Xlib cannot generate Scroll values different than 1 or -1.

Public MouseWheelVertical: boolean;
 

Methods

Public function MouseWheel: TMouseWheelDirection;
 
Public function IsKey(const AKey: TKey): boolean;

Check is event type correct, and then check if event Key or KeyCharacter matches. Always false for AKey = K_None or AKeyCharacter = #0.

Public function IsKey(const AKeyCharacter: char): boolean;
 
Public function IsMouseButton(const AMouseButton: TMouseButton): boolean;
 
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
 
Public function ToString: string;

Textual description of this event.

Public function Description: string; deprecated;

Warning: this symbol is deprecated.

Deprecated name for ToString.


Generated by PasDoc 0.14.0.