Class TCastleExamineNavigation

Unit

Declaration

type TCastleExamineNavigation = class(TCastleNavigation)

Description

Navigate the 3D model in examine mode, like you would hold a box with the model inside.

Hierarchy

Overview

Fields

Public nested const DefaultRotationAccelerationSpeed = 5.0;
Public nested const DefaultRotationSpeed = 2.0;

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public function AllowSuspendForInput: boolean; override;
Public function Press(const Event: TInputPressRelease): boolean; override;
Public function Release(const Event: TInputPressRelease): boolean; override;
Public function Motion(const Event: TInputMotion): boolean; override;
Public function SensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; override;
Public function SensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; override;
Public procedure Init(const AModelBox: TBox3D; const ARadius: Single); deprecated 'use Viewport.Camera.SetWorldView, and set GravityUp, ModelBox, Radius manually';
Public function StopRotating: boolean;

Properties

Public property Input_Rotate: TInputShortcut read FInput_Rotate;
Public property Input_Move: TInputShortcut read FInput_Move;
Public property Input_Zoom: TInputShortcut read FInput_Zoom;
Public property MouseButtonRotate: TCastleMouseButton read GetMouseButtonRotate write SetMouseButtonRotate default buttonLeft; deprecated 'use Input_Rotate';
Public property MouseButtonMove: TCastleMouseButton read GetMouseButtonMove write SetMouseButtonMove default buttonMiddle; deprecated 'use Input_Move';
Public property MouseButtonZoom: TCastleMouseButton read GetMouseButtonZoom write SetMouseButtonZoom default buttonRight; deprecated 'use Input_Zoom';
Public property Rotations: TQuaternion read GetRotations write SetRotations;
Public property RotationsAnim: TVector3 read FRotationsAnim write SetRotationsAnim;
Public property DragMoveSpeed: Single read FDragMoveSpeed write FDragMoveSpeed default 1.0;
Public property KeysMoveSpeed: Single read FKeysMoveSpeed write FKeysMoveSpeed default 1.0;
Public property MoveAmount: TVector3 read GetTranslation write SetTranslation; deprecated 'use Translation';
Public property Translation: TVector3 read GetTranslation write SetTranslation;
Public property Turntable: boolean read FTurntable write FTurntable default false;
Public property ScaleFactorMin: Single read FScaleFactorMin write FScaleFactorMin default 0.01; deprecated 'this does nothing now; it was already only a limit in case of orthographic projection';
Public property ScaleFactorMax: Single read FScaleFactorMax write FScaleFactorMax default 100.0; deprecated 'this does nothing now; it was already only a limit in case of orthographic projection';
Public property Inputs_Move: T3BoolInputs read FInputs_Move;
Public property Inputs_Rotate: T3BoolInputs read FInputs_Rotate;
Public property Input_MoveXInc: TInputShortcut read GetInput_MoveXInc;
Public property Input_MoveXDec: TInputShortcut read GetInput_MoveXDec;
Public property Input_MoveYInc: TInputShortcut read GetInput_MoveYInc;
Public property Input_MoveYDec: TInputShortcut read GetInput_MoveYDec;
Public property Input_MoveZInc: TInputShortcut read GetInput_MoveZInc;
Public property Input_MoveZDec: TInputShortcut read GetInput_MoveZDec;
Public property Input_RotateXInc: TInputShortcut read GetInput_RotateXInc;
Public property Input_RotateXDec: TInputShortcut read GetInput_RotateXDec;
Public property Input_RotateYInc: TInputShortcut read GetInput_RotateYInc;
Public property Input_RotateYDec: TInputShortcut read GetInput_RotateYDec;
Public property Input_RotateZInc: TInputShortcut read GetInput_RotateZInc;
Public property Input_RotateZDec: TInputShortcut read GetInput_RotateZDec;
Public property Input_ScaleLarger: TInputShortcut read FInput_ScaleLarger;
Public property Input_ScaleSmaller: TInputShortcut read FInput_ScaleSmaller;
Public property Input_Home: TInputShortcut read FInput_Home;
Public property Input_StopRotating: TInputShortcut read FInput_StopRotating;
Public property MouseNavigation: boolean read GetMouseNavigation write SetMouseNavigation default true; deprecated;
Public property RotationAccelerationSpeed: Single read FRotationAccelerationSpeed write FRotationAccelerationSpeed default DefaultRotationAccelerationSpeed;
Public property RotationSpeed: Single read FRotationSpeed write FRotationSpeed default DefaultRotationSpeed;
Published property RotationEnabled: Boolean read FRotationEnabled write FRotationEnabled default true;
Published property MoveEnabled: Boolean read FMoveEnabled write FMoveEnabled default true;
Published property ZoomEnabled default true;
Published property RotationAccelerate: boolean read FRotationAccelerate write SetRotationAccelerate default true;
Published property ExactMovement: Boolean read FExactMovement write FExactMovement default true;

Description

Fields

Public nested const DefaultRotationAccelerationSpeed = 5.0;

This item has no description.

Public nested const DefaultRotationSpeed = 2.0;

This item has no description.

Methods

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

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.

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 AllowSuspendForInput: boolean; override;

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

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.

Public function Press(const Event: TInputPressRelease): boolean; override;

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

Handle press or release of a key, mouse button or mouse wheel. Return True if the event was somehow handled, which prevents from passing this event to other UI controls.

When implementing in descendants it is best to override it like this:

function TMyControl.Press(const Event: TInputPressRelease): boolean;
begin
  Result := inherited;
  if Result then Exit; // exit if ancestor already handled event

  if Event.IsKey(keyEnter) then
  begin
    // do something in reaction on Enter
    Exit(ExclusiveEvents); // ExclusiveEvents is true by default
  end;

  if Event.IsMouseButton(buttonLeft) then
  begin
    // do something in reaction on Enter
    Exit(ExclusiveEvents); // ExclusiveEvents is true by default
  end;
end;

Note that releasing of the mouse wheel is not reported now by any backend. Only releasing of keys and mouse buttons is reported.

The events PreviewPress and PreviewRelease are passed first to the parent control, before children have a chance to process this event. Overriding them makes sense if you draw something in TCastleUserInterface.RenderOverChildren.

The events Press and Release are passed to the parent only after the children had a chance to process this event. Overriding them makes sense if you draw something in TCastleUserInterface.Render. This is usually more natural, and adviced.

Public function Release(const Event: TInputPressRelease): boolean; override;

This item has no description.

Public function Motion(const Event: TInputMotion): boolean; override;

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

Motion of mouse or touch.

Public function SensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; override;

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

Translation detected by 3D sensor. Used for example by 3Dconnexion devices.

Public function SensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; override;

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

Rotation detected by 3D sensor. Used for example by 3Dconnexion devices.

Public procedure Init(const AModelBox: TBox3D; const ARadius: Single); deprecated 'use Viewport.Camera.SetWorldView, and set GravityUp, ModelBox, Radius manually';

Warning: this symbol is deprecated: use Viewport.Camera.SetWorldView, and set GravityUp, ModelBox, Radius manually

Initialize most important properties of this class: sets ModelBox and goes to a nice view over the entire scene.

In other words, this is just a shortcut to setting ModelBox, and setting suitable view by SetWorldView.

Public function StopRotating: boolean;

Sets RotationsAnim to zero, stopping the rotation of the model.

Properties

Public property Input_Rotate: TInputShortcut read FInput_Rotate;

Which input (like mouse button) should rotate the model. By default this is left mouse button.

Public property Input_Move: TInputShortcut read FInput_Move;

Which input (like mouse button) should move the model. By default this is middle mouse button, or left mouse button while holding Shift.

Public property Input_Zoom: TInputShortcut read FInput_Zoom;

Which input (like mouse button) should zoom (look closer / further at model). By default this is right mouse button, or left mouse button while holding Ctrl.

Public property MouseButtonRotate: TCastleMouseButton read GetMouseButtonRotate write SetMouseButtonRotate default buttonLeft; deprecated 'use Input_Rotate';

Warning: this symbol is deprecated: use Input_Rotate

This item has no description.

Public property MouseButtonMove: TCastleMouseButton read GetMouseButtonMove write SetMouseButtonMove default buttonMiddle; deprecated 'use Input_Move';

Warning: this symbol is deprecated: use Input_Move

This item has no description.

Public property MouseButtonZoom: TCastleMouseButton read GetMouseButtonZoom write SetMouseButtonZoom default buttonRight; deprecated 'use Input_Zoom';

Warning: this symbol is deprecated: use Input_Zoom

This item has no description.

Public property Rotations: TQuaternion read GetRotations write SetRotations;

Current rotation of the model. Rotation is done around ModelBox middle (with Translation added).

Public property RotationsAnim: TVector3 read FRotationsAnim write SetRotationsAnim;

Continuous rotation animation, applied each Update to Rotations.

Public property DragMoveSpeed: Single read FDragMoveSpeed write FDragMoveSpeed default 1.0;

How fast user moves the scene by mouse/touch dragging.

Public property KeysMoveSpeed: Single read FKeysMoveSpeed write FKeysMoveSpeed default 1.0;

How fast user moves the scene by pressing keys.

Public property MoveAmount: TVector3 read GetTranslation write SetTranslation; deprecated 'use Translation';

Warning: this symbol is deprecated: use Translation

This item has no description.

Public property Translation: TVector3 read GetTranslation write SetTranslation;

How much to move the model. By default, zero.

Public property Turntable: boolean read FTurntable write FTurntable default false;

Turntable rotates the scene around its Y axis instead of current camera axis.

Public property ScaleFactorMin: Single read FScaleFactorMin write FScaleFactorMin default 0.01; deprecated 'this does nothing now; it was already only a limit in case of orthographic projection';

Warning: this symbol is deprecated: this does nothing now; it was already only a limit in case of orthographic projection

This item has no description.

Public property ScaleFactorMax: Single read FScaleFactorMax write FScaleFactorMax default 100.0; deprecated 'this does nothing now; it was already only a limit in case of orthographic projection';

Warning: this symbol is deprecated: this does nothing now; it was already only a limit in case of orthographic projection

This item has no description.

Public property Inputs_Move: T3BoolInputs read FInputs_Move;

Alternative ways to access Input_Move/Rotate(X|Y|Z)(Inc|Dec). Index the array (2nd index true means increase) instead of having to use the full identifier.

Public property Inputs_Rotate: T3BoolInputs read FInputs_Rotate;

This item has no description.

Public property Input_MoveXInc: TInputShortcut read GetInput_MoveXInc;

This item has no description.

Public property Input_MoveXDec: TInputShortcut read GetInput_MoveXDec;

This item has no description.

Public property Input_MoveYInc: TInputShortcut read GetInput_MoveYInc;

This item has no description.

Public property Input_MoveYDec: TInputShortcut read GetInput_MoveYDec;

This item has no description.

Public property Input_MoveZInc: TInputShortcut read GetInput_MoveZInc;

This item has no description.

Public property Input_MoveZDec: TInputShortcut read GetInput_MoveZDec;

This item has no description.

Public property Input_RotateXInc: TInputShortcut read GetInput_RotateXInc;

This item has no description.

Public property Input_RotateXDec: TInputShortcut read GetInput_RotateXDec;

This item has no description.

Public property Input_RotateYInc: TInputShortcut read GetInput_RotateYInc;

This item has no description.

Public property Input_RotateYDec: TInputShortcut read GetInput_RotateYDec;

This item has no description.

Public property Input_RotateZInc: TInputShortcut read GetInput_RotateZInc;

This item has no description.

Public property Input_RotateZDec: TInputShortcut read GetInput_RotateZDec;

This item has no description.

Public property Input_ScaleLarger: TInputShortcut read FInput_ScaleLarger;

This item has no description.

Public property Input_ScaleSmaller: TInputShortcut read FInput_ScaleSmaller;

This item has no description.

Public property Input_Home: TInputShortcut read FInput_Home;

This item has no description.

Public property Input_StopRotating: TInputShortcut read FInput_StopRotating;

This item has no description.

Public property MouseNavigation: boolean read GetMouseNavigation write SetMouseNavigation default true; deprecated;

Warning: this symbol is deprecated.

Include/exclude niMouseDragging from Input instead.

Public property RotationAccelerationSpeed: Single read FRotationAccelerationSpeed write FRotationAccelerationSpeed default DefaultRotationAccelerationSpeed;

Speed to change the rotation acceleration, used when RotationAccelerate = True.

Public property RotationSpeed: Single read FRotationSpeed write FRotationSpeed default DefaultRotationSpeed;

Speed to change the rotation, used when RotationAccelerate = False.

Published property RotationEnabled: Boolean read FRotationEnabled write FRotationEnabled default true;

Enable rotating the camera around the model by user input. When False, no keys / mouse dragging / 3D mouse etc. can cause a rotation.

Note that this doesn't prevent from rotating by code, e.g. by setting Rotations property or calling Camera.SetWorldView.

Published property MoveEnabled: Boolean read FMoveEnabled write FMoveEnabled default true;

Enable moving the camera by user input. When False, no keys / mouse dragging / 3D mouse etc. can make a move.

Note that this doesn't prevent from moving by code, e.g. by setting Translation property or calling Camera.SetWorldView.

Published property ZoomEnabled default true;

This item has no description. Showing description inherited from TCastleNavigation.ZoomEnabled.

Enable zooming in / out. Depending on the projection, zooming either moves camera or scales the projection size. When False, no keys / mouse dragging / 3d mouse etc. can make a zoom. If True, at least mouse wheel makes a zoom (som,e navigation methods may have additional ways to make zoom, they will all honor this property.)

Published property RotationAccelerate: boolean read FRotationAccelerate write SetRotationAccelerate default true;

When True, rotation keys make the rotation faster, and the model keeps rotating even when you don't hold any keys. When False, you have to hold rotation keys to rotate.

Published property ExactMovement: Boolean read FExactMovement write FExactMovement default true;

In orthographic projection with standard direction/up, move the camera exactly as many units as the mouse position change indicates. Makes the movemement in standard orthographic view most natural.


Generated by PasDoc 0.16.0.