Class TInputListener

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type TInputListener = class(TComponent)

Description

Base class for things that listen to user input: cameras and 2D controls.

Hierarchy

  • TComponent
  • TInputListener

Overview

Methods

Public constructor Create(AOwner: TComponent); override;
Public function Press(const Event: TInputPressRelease): boolean; virtual;
Public function Release(const Event: TInputPressRelease): boolean; virtual;
Public function MouseMove(const OldX, OldY, NewX, NewY: Integer): boolean; virtual;
Public function Mouse3dRotation(const X, Y, Z, Angle: Double; const CompSpeed: Single): boolean; virtual;
Public function Mouse3dTranslation(const X, Y, Z, Length: Double; const CompSpeed: Single): boolean; virtual;
Public procedure Idle(const CompSpeed: Single; const HandleMouseAndKeys: boolean; var LetOthersHandleMouseAndKeys: boolean); virtual;
Public procedure VisibleChange; virtual;
Public function AllowSuspendForInput: boolean; virtual;
Public procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); virtual;

Properties

Public property OnVisibleChange: TNotifyEvent read FOnVisibleChange write FOnVisibleChange;
Public property Container: IUIContainer read FContainer write SetContainer;
Public property Cursor: TMouseCursor read FCursor write SetCursor default mcDefault;
Public property OnCursorChange: TNotifyEvent read FOnCursorChange write FOnCursorChange;
Public property ExclusiveEvents: boolean read FExclusiveEvents write FExclusiveEvents default true;

Description

Methods

Public constructor Create(AOwner: TComponent); override;
 
Public function Press(const Event: TInputPressRelease): boolean; virtual;

Handle press or release of a key, mouse button or mouse wheel. Return True if the event was somehow handled.

In this class this always returns False, when implementing in descendants you should override it like

  Result := inherited;
  if Result or (not GetExists) then Exit;
  { ... And do the job here.
    In other words, the handling of events in inherited
    class should have a priority. }

Note that releasing of mouse wheel is not implemented for now, neither by CastleWindow or Lazarus CastleControl.

Public function Release(const Event: TInputPressRelease): boolean; virtual;
 
Public function MouseMove(const OldX, OldY, NewX, NewY: Integer): boolean; virtual;
 
Public function Mouse3dRotation(const X, Y, Z, Angle: Double; const CompSpeed: Single): boolean; virtual;

Rotation of 3Dconnexion devices.

Parameters
X
X axis (tilt forward/backwards)
Y
Y axis (rotate)
Z
Z axis (tilt sidewards)
Angle
Angle of rotation.
Public function Mouse3dTranslation(const X, Y, Z, Length: Double; const CompSpeed: Single): boolean; virtual;

Translation of 3Dconnexion devices.

Parameters
X
X axis (move left/right)
Y
Y axis (move up/down)
Z
Z axis (move forward/backwards)
Length
Length of the vector consisting of the above.
Public procedure Idle(const CompSpeed: Single; const HandleMouseAndKeys: boolean; var LetOthersHandleMouseAndKeys: boolean); virtual;

Control may do here anything that must be continously repeated. This is called often by the container. E.g. camera handles here falling down due to gravity in Walker mode, rotating model in Examine mode, and many more.

HandleMouseAndKeys says if this control can handle currently pressed keys and mouse buttons. Only if it is True, the control can look at Container.Pressed and Container.MousePressed. HandleMouseAndKeys will be passed as True only to the controls under the mouse, and only if previous controls under the mouse did not set LetOthersHandleMouseAndKeys = False.

Also (only when HandleMouseAndKeys = True) the control can set LetOthersHandleMouseAndKeys. In fact, it's by default set to not ExclusiveEvents, which (since ExclusiveEvents by default is True) usually means False. This reflects the fact that "normal" UI controls, that actually take screen space implied by PositionInside, want to block controls underneath from handling keys/mouse. For example, when pressing key "left" over TCastleOnScreenMenu, you do not want to let the scene manager to also capture this left key down.

More reasoning behind HandleMouseAndKeys:

Note that the "Idle" events are called differently that other mouse and key events.

Mouse and key events return whether the event was somehow "handled", and the container passes them only to the controls under the mouse (decided by PositionInside). And as soon as some control says it "handled" the event, other controls (even if under the mouse) will not receive the event.

This approach is not suitable for idle events. Some controls need to do the idle job all the time, regardless of whether the control is under the mouse and regardless of what other controls already did. So all controls receive Idle calls.

So the "handled" status is passed through HandleMouseAndKeys and controlled by LetOthersHandleMouseAndKeys. If a control is not under the mouse, it will receive HandleMouseAndKeys = False, and LetOthersHandleMouseAndKeys return value is ignored. If a control is under the mouse, it will receive HandleMouseAndKeys = True and has the power to disallow mouse/key handling for all other controls by LetOthersHandleMouseAndKeys.

Parameters
CompSpeed
Should be calculated like TFramesPerSecond.IdleSpeed, and usually it's in fact just taken from TCastleWindowBase.Fps.IdleSpeed.
Public procedure VisibleChange; virtual;

Called always when some visible part of this control changes. In the simplest case, this is used by the controls manager to know when we need to redraw the control.

In this class this simply calls OnVisibleChange (if assigned).

Public function AllowSuspendForInput: boolean; virtual;

Allow window containing this control to suspend waiting for user input. Typically you want to override this to return False when you do something in the overridden Idle method.

In this class, this simply returns always True.

See also
TCastleWindowBase.AllowSuspendForInput
Is it allowed to suspend (for an indefinite amount of time) waiting for user input.
Public procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); virtual;

Called always when containing window size changes. Also, when the control is first inserted into the window controls list (like TCastleWindowCustom.Controls), it will also receive initial ContainerResize event. So every member of of Controls list knows window width / height.

In this class, this sets values of ContainerWidth, ContainerHeight, ContainerSizeKnown properties.

Properties

Public property OnVisibleChange: TNotifyEvent read FOnVisibleChange write FOnVisibleChange;

Called always when some visible part of this control changes. In the simplest case, this is used by the controls manager to know when we need to redraw the control.

Be careful when handling this event, various changes may cause this, so be prepared to handle OnVisibleChange at every time.

See also
VisibleChange
Called always when some visible part of this control changes.
Public property Container: IUIContainer read FContainer write SetContainer;

Container of this control. When adding control to container's Controls list (like TCastleWindowCustom.Controls) container will automatically set itself here, an when removing from container this will be changed back to Nil.

May be Nil if this control is not yet inserted into any container. May also be Nil since not all containers have to implement right now IUIContainer interface, it's not crucial for most controls to work.

Public property Cursor: TMouseCursor read FCursor write SetCursor default mcDefault;

Mouse cursor over this control. When user moves mouse over the Container, the currently focused (topmost under the cursor) control determines the mouse cursor look.

Public property OnCursorChange: TNotifyEvent read FOnCursorChange write FOnCursorChange;

Event called when the Cursor property changes. This event is, in normal circumstances, used by the Container, so you should not use it in your own programs.

Public property ExclusiveEvents: boolean read FExclusiveEvents write FExclusiveEvents default true;

Should we disable further mouse / keys handling for events that we already handled in this control. If True, then our events will return True for mouse and key events handled.

This means that events will not be simultaneously handled by both this control and some other (or camera or normal window callbacks), which is usually more sensible, but sometimes somewhat limiting.


Generated by PasDoc 0.12.1 on 2013-02-04 20:26:52