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 = 1.0;
Public nested const DefaultZoomSpeed = 1.0;

Methods

Protected function Zoom(const Factor: Single): Boolean; override;
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 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 CenterOfRotation: TVector3 read FCenterOfRotation write FCenterOfRotation;
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;
Published property AutoCenterOfRotation: Boolean read FAutoCenterOfRotation write FAutoCenterOfRotation default true;
Published property DragMoveSpeed: Single read FDragMoveSpeed write FDragMoveSpeed default 1.0;
Published property KeysMoveSpeed: Single read FKeysMoveSpeed write FKeysMoveSpeed default 1.0;
Published property RotationAccelerationSpeed: Single read FRotationAccelerationSpeed write FRotationAccelerationSpeed default DefaultRotationAccelerationSpeed;
Published property RotationSpeed: Single read FRotationSpeed write FRotationSpeed default DefaultRotationSpeed;
Published property ZoomSpeed: Single read FZoomSpeed write FZoomSpeed default DefaultZoomSpeed;

Description

Fields

Public nested const DefaultRotationAccelerationSpeed = 5.0;

This item has no description.

Public nested const DefaultRotationSpeed = 1.0;

This item has no description.

Public nested const DefaultZoomSpeed = 1.0;

This item has no description.

Methods

Protected function Zoom(const Factor: Single): Boolean; override;

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

Zoom in / out. Negative Factor makes "zoom out", positive makes "zoom in" (zero makes nothing).

Called only if ZoomEnabled, so no need to check it within implementation.

Factor values correspond to TInputPressRelease.MouseWheelScroll values, so 1.0 should be treated like a "one operation" and some systems only generate values -1 or +1 (and never fractions).

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
  begin
    Transform.Position := Transform.Position + Vector3(SecondsPassed * 10, 0, 0);
    HandleInput := false;
  end;
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 := false. 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.

Override this method to react to user pressing a key, mouse button or mouse wheel. Return True if the event was 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 this event

  if Event.IsKey(keyEnter) then
  begin
    // do something in reaction to Enter key
    ...
    // let engine know that this input event was handled
    Exit(true);
  end;

  if Event.IsMouseButton(buttonLeft) then
  begin
    // do something in reaction to left mouse button press
    ...
    // let engine know that this input event was handled
    Exit(true);
  end;
end;

These events are generated for all UI controls, whether they are considered "interactive" or not. These events are generated for non-interactive controls like TCastleRectangleControl or TCastleLabel as well. For example, these events ignore the TCastleButton.Enabled state, they are generated always (see https://github.com/castle-engine/castle-engine/issues/413 ). Use instead TCastleButton.OnClick to detect clicks on a button in a way that honors the TCastleButton.Enabled state.

When a control returns True from Press, it means it starts to "capture" subsequent mouse events: subsequent mouse moves and release will be send to this control even if mouse will move outside of this control.

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 that "looks clickable" in TCastleUserInterface.Render, which is the standard place you should draw stuff. For example our TCastleButton draws there.

In contrast, the events PreviewPress and PreviewRelease are passed first to the parent control, before children have a chance to process this event. In partcular, overriding them makes sense if you draw something that "looks clickable" in TCastleUserInterface.RenderOverChildren.

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

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

Override this method to react to user releasing a key, mouse button. Return True if the event was handled, which prevents from passing this event to other UI controls.

This is counterpart to Press method. See Press for more details.

Note: We'd like this method to also be called when user releases a mouse wheel. But currently releasing of the mouse wheel is not reported now by any backend. Only releasing of keys and mouse buttons is reported.

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 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 CenterOfRotation: TVector3 read FCenterOfRotation write FCenterOfRotation;

3D point around which we rotate, in world coordinates. This is used only when AutoCenterOfRotation = 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.

Published property AutoCenterOfRotation: Boolean read FAutoCenterOfRotation write FAutoCenterOfRotation default true;

Should we calculate center of rotation automatically (based on world bounding box) or use explicit CenterOfRotation.

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

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

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

How fast user moves the scene by pressing keys.

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

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

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

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

Published property ZoomSpeed: Single read FZoomSpeed write FZoomSpeed default DefaultZoomSpeed;

Speed to change the Zoom, when ZoomEnabled = True.


Generated by PasDoc 0.16.0-snapshot.