Record TInputPressRelease

Hierarchy
Properties

Unit

Declaration

type TInputPressRelease = record

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.

Overview

Fields

Public EventType: TInputPressReleaseType;
Public Key: TKey;
Public KeyString: string;
Public ModifiersDown: TModifierKeys;
Public KeyRepeated: boolean;
Public MouseButton: TCastleMouseButton;
Public FingerIndex: TFingerIndex;
Public Position: TVector2;
Public MouseWheelScroll: Single;
Public MouseWheelVertical: boolean;

Methods

Public function MouseWheel: TMouseWheelDirection;
Public function IsKey(const AKey: TKey): boolean; overload;
Public function IsKey(AKeyString: String): boolean; overload;
Public function IsMouseButton(const AMouseButton: TCastleMouseButton): boolean;
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
Public function ToString: string;
Public function KeyCharacter: char;
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 <> keyNone or KeyString <> '' in this case. When EventType <> itKey, then Key = keyNone and KeyString = ''.

Both Key and KeyString 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 = keyNone, but KeyString = '('.

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

KeyString is a string (encoded using UTF-8, like all strings in Castle Game Engine) and 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 KeyString: string;
 
Public ModifiersDown: TModifierKeys;

ModifiersDown contains a set of modifier keys (i.e. Ctrl, Shift and Alt) which were pressed at the moment of this Event.

Public KeyRepeated: boolean;

Was this key already pressed before this event. May be True only for key events, and only on press (not on release). Alllows to recognize "key repeat" that occurs when you press a key for some time. The keyboard generates "key down" events then (with delay and frequency depending on keyboard settings). Sometimes they are useful, sometimes not – so you can recognize them using this field.

Public MouseButton: TCastleMouseButton;

When EventType is itMouseButton, this is the mouse button pressed or released. Always buttonLeft 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: TVector2;

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

The position is relative to the whole container (rendering area of TCastleWindow or TCastleControl). With left-bottom being (0,0) and X growing to the right and Y growing up. The position is in final device coordinates, i.e. it ignores TCastleContainer.UIScaling. Use e.g. TCastleUserInterface.ContainerToLocalPosition to easily convert this position into a position suitable for given UI control children.

For normal backends that simply support a single mouse device, this is just equivalent to TCastleWindow.MousePosition and TCastleControl.MousePosition.

For multi-touch devices, this 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; overload;

Check is event type correct, and then check if event Key or KeyString matches. Always false for AKey = keyNone or AKeyString = ''.

Public function IsKey(AKeyString: String): boolean; overload;
 
Public function IsMouseButton(const AMouseButton: TCastleMouseButton): boolean;
 
Public function IsMouseWheel(const AMouseWheel: TMouseWheelDirection): boolean;
 
Public function ToString: string;

Textual description of this event.

Public function KeyCharacter: char;

Character corresponding to EventType = itKey. Returns #0 if the event was not a keyboard event or it cannot be represented as a simple 8-bit character (e.g. it is a Cyrillic or Arabic character, or it is a special key like "up arrow").

Public function Description: string; deprecated;

Warning: this symbol is deprecated.

Deprecated name for ToString.


Generated by PasDoc 0.16.0.