Class TCastleDesktopPointerLock

Description
Hierarchy
Methods
Properties

Unit

CastleUIControls

Declaration

type TCastleDesktopPointerLock = class(TCastleAbstractPointerLock)

Description

Pointer lock implementation on desktops. We hide the mouse cursor (using TCastleContainer internal mechanism, so we override whatever cursor is set by TCastleUserInterface.Cursor or TCastleContainer.OverrideCursor). We keep repositioning mouse to the middle of the container.

Source: ui/castleuicontrols_pointer_lock_desktop.inc (line 27).

Hierarchy

Show Additional Members:

Overview

Methods

Protected procedure CancelActive;
Public constructor Create(const AContainer: TCastleContainer);
Public destructor Destroy; override;
Public procedure AddUserCancelledListener(const Event: TNotifyEvent);
Public procedure RemoveUserCancelledListener(const Event: TNotifyEvent);
Protected procedure ActiveChanged(const NewValue: Boolean); override;
Protected function Delta(const Event: TInputMotion): TVector2; override;
Public procedure InternalIgnoreNextMotion; override;

Properties

Protected property Container: TCastleContainer read FContainer;
Public property Active: Boolean read FActive write SetActive;
Public property Controller: TCastleUserInterface read FController write SetController;

Description

Methods

Protected procedure CancelActive;

This item is declared in ancestor TCastleAbstractPointerLock.

Set Active to False without calling virtual ActiveChanged. Calls callbacks registered with AddUserCancelledListener. To be used by descendants when we lost pointer lock because of user action, e.g. on web when user cancels pointer lock by pressing Escape key.

Descendants are responsible to reset their own state before/after calling this, since this does not call ActiveChanged, so descendants are not notified about the cancellation in any other way. E.g. web implementation sets "FEffective := false" before calling this.

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 165).

Public constructor Create(const AContainer: TCastleContainer);

This item is declared in ancestor TCastleAbstractPointerLock.

This item has no description.

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 195).

Public destructor Destroy; override;

This item is declared in ancestor TCastleAbstractPointerLock.

This item has no description.

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 196).

Public procedure AddUserCancelledListener(const Event: TNotifyEvent);

This item is declared in ancestor TCastleAbstractPointerLock.

Called when user cancels pointer lock, e.g. by pressing Escape key on web. When this is triggered, the Active property is already set to False.

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 213).

Public procedure RemoveUserCancelledListener(const Event: TNotifyEvent);

This item is declared in ancestor TCastleAbstractPointerLock.

This item has no description.

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 214).

Protected procedure ActiveChanged(const NewValue: Boolean); override;

This item has no description. Showing description inherited from TCastleAbstractPointerLock.ActiveChanged.

Start or stop mouse look.

Source: ui/castleuicontrols_pointer_lock_desktop.inc (line 33).

Protected function Delta(const Event: TInputMotion): TVector2; override;

This item has no description. Showing description inherited from TCastleAbstractPointerLock.Delta.

Read current delta of mouse movement, assuming that mouse look is active.

This is internally used by container to set TInputMotion.Delta before TInputMotion is passed to TCastleUserInterface.Motion events.

This is called exactly once per motion event (so it doesn't need to be deterministic based on Event; on desktop it will indeed do some side-effects like repositioning mouse).

Always returns zero if Active is False. Remember that on some platforms (web) user may cancel the "pointer lock" mode at any moment, so be sure to tolerate it by doing nothing when this is zero.

It also returns zero if Active is True but we have not yet prepared for this mode. On desktops, "not prepared" means that mouse was not positioned correctly yet. On web, "not prepared" means that browser/user didn't yet confirm pointer lock mode. Again, the simple solution is to do nothing when this is zero.

The returned value is in final device pixels, so it is not affected by UI scale. If you want to adjust to UI scale (so user will have to move mouse by more pixels, when on a larger screen, when UI is larger) then just use Delta / UiScale.

Source: ui/castleuicontrols_pointer_lock_desktop.inc (line 34).

Public procedure InternalIgnoreNextMotion; override;

This item has no description.

Source: ui/castleuicontrols_pointer_lock_desktop.inc (line 36).

Properties

Protected property Container: TCastleContainer read FContainer;

This item is declared in ancestor TCastleAbstractPointerLock.

Container performing this pointer lock logic.

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 154).

Public property Active: Boolean read FActive write SetActive;

This item is declared in ancestor TCastleAbstractPointerLock.

Enable or disable pointer lock. Note that on some platforms (web) user can cancel pointer lock at any time, in which case this property turns to False. On other platforms (desktop) this stays completely under control of the application.

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 203).

Public property Controller: TCastleUserInterface read FController write SetController;

This item is declared in ancestor TCastleAbstractPointerLock.

Optionally, when requesting pointer lock (by setting Active to True), you can set this property to indicate what component is responsible for the pointer lock.

This controller, and not others, should process deltas during pointer lock. This controller should also set Active to False when no longer needed. This is just a convention: since in practice it doesn't make sense for mutliple components to process pointer lock deltas at the same time, this property allows them to coordinate "which one processes deltas now" and avoid conflicts. E.g. when we have multiple viewports and multiple TCastleWalkNavigation instances, only one of them can effectively process pointer lock deltas.

Guaranteed effects of setting this:

  1. We will make sure to pass Motion events to this controller, first, even if it is not focused. This allows to capture motion events even by TCastleWalkNavigation that doesn't fill the middle of the screen. This makes sense, since mouse position in general should not matter when pointer lock is active.

  2. When we detect this no longer exists (or parent of it) we will call TCastleUserInterface.ReleasePointerLock on it. Once the control (and its parents) exist again, it will again receive events like Update, so it can again then grab mouse look (that's what TCastleWalkNavigation does, for example).

Source: ui/castleuicontrols_pointer_lock_abstract.inc (line 248).

Generated by PasDoc 1.0.4.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.