Class TCastleTouchNavigation

Unit

Declaration

type TCastleTouchNavigation = class(TCastleUserInterface)

Description

Show draggable controls in the corner, to navigate in the viewport comfortably on touch devices.

Depending on AutoTouchInterface and TouchInterface, we will show 0, 1 or 2 controls to navigate at the bottom, in the left-bottom and right-bottom. It is easiest to just set

MyTouchNavigation.TouchInterface := tiNone; // default
MyTouchNavigation.AutoTouchInterface := ApplicationProperties.TouchDevice;

to activate this automatically on mobile devices, leaving MyTouchNavigation.TouchInterface equal tiNone on non-mobile devices. Alternatively, you can do something like this to control it manually on mobile devices:

MyTouchNavigation.AutoTouchInterface := false; // default
MyTouchNavigation.Exists := ApplicationProperties.TouchDevice;
MyTouchNavigation.TouchInterface := tiSomething;

The size and position of this control determines where the controls appear. Typically this control is added as a direct child of TCastleViewport and has FullSize = True, this way it just fills the TCastleViewport.

The Viewport determines the viewport where navigation is affected by this control. Typically the Viewport is also our visual parent, but it doesn't have to be.

Hierarchy

Overview

Fields

Public nested const DefaultAutoWalkTouchInterface = tiWalk;
Public nested const DefaultAutoExamineTouchInterface = tiPan;

Methods

Public constructor Create(AOwner: TComponent); override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: Boolean); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;

Properties

Published property Viewport: TCastleViewport read FViewport write SetViewport;
Published property TouchInterface: TTouchInterface read FTouchInterface write SetTouchInterface stored TouchInterfaceStored default tiNone;
Published property AutoTouchInterface: boolean read FAutoTouchInterface write SetAutoTouchInterface default false;
Published property AutoWalkTouchInterface: TTouchInterface read FAutoWalkTouchInterface write SetAutoWalkTouchInterface default DefaultAutoWalkTouchInterface;
Published property AutoExamineTouchInterface: TTouchInterface read FAutoExamineTouchInterface write SetAutoExamineTouchInterface default DefaultAutoExamineTouchInterface;
Published property ControlMouseDragMode: Boolean read FControlMouseDragMode write SetControlMouseDragMode default false;
Published property Scale: Single read FScale write SetScale default 1.0;

Description

Fields

Public nested const DefaultAutoWalkTouchInterface = tiWalk;

This item has no description.

Public nested const DefaultAutoExamineTouchInterface = tiPan;

This item has no description.

Methods

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public procedure Update(const SecondsPassed: Single; var HandleInput: Boolean); override;

This item has no description. Showing description inherited from TCastleUserInterface.Update.

Control may do here anything that must be continuously 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 continuously 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[keyArrowRight] then
    Transform.Position := Transform.Position + Vector3(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 continuous 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 TCastleUserInterface.CapturesEventsAtPosition). 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 TCastleUserInterface, see TCastleUserInterface.Exists) 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.

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Properties

Published property Viewport: TCastleViewport read FViewport write SetViewport;

Viewport where navigation is affected by this control.

You must set this property to something non-nil, otherwise this UI control doesn't do much, it will not affect anything.

Published property TouchInterface: TTouchInterface read FTouchInterface write SetTouchInterface stored TouchInterfaceStored default tiNone;

Configure controls to be visible and available to navigate. This automatically manages under the hood 0, 1 or 2 controls to navigate, placing them at suitable positions and handling their operations.

Note that you can set AutoTouchInterface = True to have this property automatically adjusted. (In which case you should not set this directly.)

When ControlMouseDragMode then this property additionally controls the TCastleWalkNavigation.MouseDragMode.

Published property AutoTouchInterface: boolean read FAutoTouchInterface write SetAutoTouchInterface default false;

Automatically adjust TouchInterface (showing / hiding proper touch controls) based on the detected current Viewport navigation type.

Published property AutoWalkTouchInterface: TTouchInterface read FAutoWalkTouchInterface write SetAutoWalkTouchInterface default DefaultAutoWalkTouchInterface;

When using AutoTouchInterface = True, which touch interface should be used when walking (since there are multiple sensible choices). Select between tiWalkRotate or tiWalk (default).

Published property AutoExamineTouchInterface: TTouchInterface read FAutoExamineTouchInterface write SetAutoExamineTouchInterface default DefaultAutoExamineTouchInterface;

When using AutoTouchInterface = True, which touch interface should be used in examine camera (since examine camera can use multi-touch gesture instead). Select between tiPan (default) or tiNone.

Published property ControlMouseDragMode: Boolean read FControlMouseDragMode write SetControlMouseDragMode default false;

Control also TCastleWalkNavigation.MouseDragMode by the AutoTouchInterface and TouchInterface setting.

We advise to not use this property, and instead set TCastleWalkNavigation.MouseDragMode manually and explicitly. Otherwise this automatic control may be confusing, as it overrides what you set in editor as TCastleWalkNavigation.MouseDragMode value.

Published property Scale: Single read FScale write SetScale default 1.0;

Visual scale of the device.


Generated by PasDoc 0.16.0.