Castle Game Engine: CastleUIControls: Class TInputListener

# Class TInputListener
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleUIControls ## Declaration `type TInputListener = class(TComponent)` ## Description Base class for things that listen to user input: cameras and 2D controls. ## Hierarchy TComponent TInputListener ## Overview ### Methods
| `function ContainerWidth: Cardinal;`
| `function ContainerHeight: Cardinal;`
| `function ContainerRect: TRectangle;`
| `function ContainerSizeKnown: boolean;`
| `procedure SetContainer(const Value: TUIContainer); virtual;`
| `procedure DoCursorChange; virtual;`
| `constructor Create(AOwner: TComponent); override;`
| `function Press(const Event: TInputPressRelease): boolean; virtual;`
| `function Release(const Event: TInputPressRelease): boolean; virtual;`
| `function Motion(const Event: TInputMotion): boolean; virtual;`
| `function SensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; virtual;`
| `function SensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; virtual;`
| `procedure Update(const SecondsPassed: Single; var HandleInput: boolean); virtual;`
| `procedure VisibleChange; virtual;`
| `function AllowSuspendForInput: boolean; virtual;`
| `procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); virtual;`
### Properties
| `property OnVisibleChange: TNotifyEvent read FOnVisibleChange write FOnVisibleChange;`
| `property Container: TUIContainer read FContainer write SetContainer;`
| `property Cursor: TMouseCursor read FCursor write SetCursor default mcDefault;`
| `property OnCursorChange: TNotifyEvent read FOnCursorChange write FOnCursorChange;`
| `property ExclusiveEvents: boolean read FExclusiveEvents write FExclusiveEvents default true;`
## Description ### Methods
| `function ContainerWidth: Cardinal;`
Container sizes.
| `function ContainerHeight: Cardinal;`
| `function ContainerRect: TRectangle;`
| `function ContainerSizeKnown: boolean;`
| `procedure SetContainer(const Value: TUIContainer); virtual;`
| `procedure DoCursorChange; virtual;`
Called when Cursor changed. In TUIControl class, just calls OnCursorChange.
| `constructor Create(AOwner: TComponent); override;`
| `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 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.
| `function Release(const Event: TInputPressRelease): boolean; virtual;`
| `function Motion(const Event: TInputMotion): boolean; virtual;`
`Motion` of mouse or touch.
| `function SensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; virtual;`
Rotation detected by sensor. Used for example by 3Dconnexion devices or touch controls. ###### Parameters X X axis (tilt forward/backwards) Y Y axis (rotate) Z Z axis (tilt sidewards) Angle Angle of rotation SecondsPassed The time passed since last `SensorRotation` call. This is necessary because some sensors, e.g. 3Dconnexion, may *not* reported as often as normal Update calls.
| `function SensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; virtual;`
Translation detected by sensor. Used for example by 3Dconnexion devices or touch controls. ###### 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 SecondsPassed The time passed since last SensorRotation call. This is necessary because some sensors, e.g. 3Dconnexion, may *not* reported as often as normal Update calls.
| `procedure Update(const SecondsPassed: Single; var HandleInput: boolean); virtual;`
Control may do here anything that must be continously repeated. E.g. camera handles here falling down due to gravity, rotating model in Examine mode, and many more. This method may be used, among many other things, to continously react to the fact that user pressed some key (or mouse button). For example, if holding some key should move some 3D object, you should do something like:
    if HandleInput then
    begin
      if Container.Pressed[K_Right] then
        Transform.Position += Vector3Single(SecondsPassed * 10, 0, 0);
      HandleInput := not ExclusiveEvents;
    end;
Instead of directly using a key code, consider also using TInputShortcut that makes the input key nicely configurable. See engine tutorial about handling inputs. Multiplying movement by SecondsPassed makes your operation frame-rate independent. Object will move by 10 units in a second, regardless of how many FPS your game has. The code related to HandleInput is important if you write a generally-useful control that should nicely cooperate with all other controls, even when placed on top of them or under them. The correct approach is to only look at pressed keys/mouse buttons if HandleInput is `True`. Moreover, if you did check that HandleInput is `True`, and you did actually handle some keys, then you have to set `HandleInput := not ExclusiveEvents`. As ExclusiveEvents is `True` in normal circumstances, this will prevent the other controls (behind the current control) from handling the keys (they will get HandleInput = `False`). And this is important to avoid doubly-processing the same key press, e.g. if two controls react to the same key, only the one on top should process it. Note that to handle a single press / release (like "switch light on when pressing a key") you should rather use Press and Release methods. Use this method only for continous handling (like "holding this key makes the light brighter and brighter"). To understand why such HandleInput approach is needed, realize that the "Update" events are called differently than simple mouse and key events like "Press" and "Release". "Press" and "Release" 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 Update events. Some controls need to do the Update job all the time, regardless of whether the control is under the mouse and regardless of what other controls already did. So all controls (well, all controls that exist, in case of TUIControl, see TUIControl.GetExists) receive Update calls. So the "handled" status is passed through HandleInput. If a control is not under the mouse, it will receive HandleInput = `False`. If a control is under the mouse, it will receive HandleInput = `True` as long as no other control on top of it didn't already change it to `False`. ###### Parameters SecondsPassed Should be calculated like TFramesPerSecond.UpdateSecondsPassed, and usually it's in fact just taken from TCastleWindowCustom.Fps.UpdateSecondsPassed.
| `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).
| `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 Update method. In this class, this simply returns always `True`. ###### See also TCastleWindowCustom.AllowSuspendForInput Is it allowed to suspend (for an indefinite amount of time) waiting for user input.
| `procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); virtual;`
Called always when the container (component or window with OpenGL context) size changes. Called only when the OpenGL context of the container is initialized, so you can be sure that this is called only between GLContextOpen and GLContextClose. We also make sure to call this once when inserting into the container controls list (like TCastleWindowCustom.Controls or TCastleControlCustom.Controls), if inserting into the container with already initialized OpenGL context. If inserting into the container without OpenGL context initialized, it will be called later, when OpenGL context will get initialized, right after GLContextOpen. In other words, this is always called to let the control know the size of the container, if and only if the OpenGL context is initialized.
### Properties
| `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.
| `property Container: TUIContainer 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, and when removing from container this will be changed back to `Nil`. May be `Nil` if this control is not yet inserted into any container.
| `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.
| `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.
| `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.13.0 on 2015-06-15 04:43:12