diff --git a/types/three/examples/jsm/controls/ArcballControls.d.ts b/types/three/examples/jsm/controls/ArcballControls.d.ts index a59908017..930c338b0 100644 --- a/types/three/examples/jsm/controls/ArcballControls.d.ts +++ b/types/three/examples/jsm/controls/ArcballControls.d.ts @@ -1,169 +1,202 @@ -import { Camera, EventDispatcher, Raycaster, Scene, Vector3 } from "three"; +import { Camera, Raycaster, Scene } from "three"; +import { Controls } from "./Controls.js"; -export enum ArcballControlsMouseActionOperations { - PAN = "PAN", - ROTATE = "ROTATE", - ZOOM = "ZOOM", - FOV = "FOV", -} +export type ArcballControlsMouseActionOperation = "PAN" | "ROTATE" | "ZOOM" | "FOV"; export type ArcballControlsMouseActionMouse = 0 | 1 | 2 | "WHEEL"; -export enum ArcballControlsMouseActionKeys { - SHIFT = "SHIFT", - CTRL = "CTRL", -} +export type ArcballControlsMouseActionKey = "SHIFT" | "CTRL"; export interface ArcballControlsEventMap { - change: {}; - start: {}; - end: {}; -} - -export class ArcballControls extends EventDispatcher { - camera: Camera | null; - domElement: HTMLElement; - scene?: Scene | null | undefined; - /** - * @default 500 + * Fires when the camera has been transformed by the controls. */ - focusAnimationTime: number; + change: {}; /** - * @default true + * Fires when an interaction was initiated. */ - enabled: boolean; + start: {}; /** - * @default true + * Fires when an interaction has finished. */ - enablePan: boolean; + end: {}; +} +/** + * Arcball controls allow the camera to be controlled by a virtual trackball with full touch support and advanced + * navigation functionality. + */ +declare class ArcballControls extends Controls { /** - * @default true + * The scene rendered by the camera. */ - enableRotate: boolean; + scene: Scene | null; /** - * @default true + * The size of the gizmo relative to the screen width and height. Default is 0.67. */ - enableZoom: boolean; + radiusFactor: number; /** - * @default true + * Duration time of focus animation. */ - enableGizmos: boolean; + focusAnimationTime: number; /** - * @default true + * If true, camera's near and far values will be adjusted every time zoom is performed trying to mantain the same + * visible portion given by initial near and far values ( {@link PerspectiveCamera} only ). Default is false. */ adjustNearFar: boolean; /** - * @default 1.1 + * The scaling factor used when performing zoom operation. */ scaleFactor: number; /** - * @default 25 + * The damping inertia used if [page:.enableAnimations] is set to true. */ dampingFactor: number; /** - * @default 20 + * Maximum angular velocity allowed on rotation animation start. */ - wMax: number; // maximum angular velocity allowed + wMax: number; /** - * @default true + * Set to true to enable animations for rotation (damping) and focus operation. Default is true. */ - enableAnimations: boolean; // if animations should be performed + enableAnimations: boolean; /** - * @default false + * When set to true, a grid will appear when panning operation is being performed (desktop interaction only). Default is false. */ - enableGrid: boolean; // if grid should be showed during pan operation + enableGrid: boolean; /** - * @default false + * Set to true to make zoom become cursor centered. */ - cursorZoom: boolean; // if wheel zoom should be cursor centered + cursorZoom: boolean; /** - * @default 5 + * Speed of rotation. Default is 1. */ - minFov: number; + rotateSpeed: number; + + /** + * Enable or disable camera panning. Default is true. + */ + enablePan: boolean; + + /** + * Enable or disable camera rotation. Default is true. + */ + enableRotate: boolean; /** - * @default 90 + * Enable or disable zooming of the camera. */ - maxFov: number; + enableZoom: boolean; /** - * @default 0 + * How far you can dolly in ( {@link PerspectiveCamera} only ). Default is 0. */ minDistance: number; /** - * @default Infinity + * How far you can dolly out ( {@link PerspectiveCamera} only ). Default is Infinity. */ maxDistance: number; /** - * @default 0 + * How far you can zoom in ( {@link OrthographicCamera} only ). Default is 0. */ minZoom: number; /** - * @default Infinity + * How far you can zoom out ( {@link OrthographicCamera} only ). Default is Infinity. */ maxZoom: number; /** - * @default Vector3(0,0,0) + * @param camera The camera to be controlled. The camera must not be a child of another object, unless that object + * is the scene itself. + * @param domElement The HTML element used for event listeners. (optional) + * @param scene The scene rendered by the camera. If not given, gizmos cannot be shown. (optional) */ - target: Vector3; + constructor(camera: Camera, domElement?: HTMLElement | null, scene?: Scene | null); /** - * @default 0.67 + * Set a new mouse action by specifying the operation to be performed and a mouse/key combination. In case of + * conflict, replaces the existing one. + * @param operation Operations can be specified as 'ROTATE', 'PAN', 'FOV' or 'ZOOM'. + * @param mouse Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches. + * @param key Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed. */ - radiusFactor: number; + setMouseAction( + operation: ArcballControlsMouseActionOperation, + mouse: ArcballControlsMouseActionMouse, + key?: ArcballControlsMouseActionKey | null, + ): boolean; /** - * @default 1 + * Removes a mouse action by specifying its mouse/key combination. + * @param mouse Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches. + * @param key Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed. */ - rotateSpeed: number; - - constructor(camera: Camera, domElement: HTMLElement, scene?: Scene | null); - - getRaycaster(): Raycaster; + unsetMouseAction(mouse: ArcballControlsMouseActionMouse, key?: ArcballControlsMouseActionKey | null): boolean; + /** + * Make gizmos more or less visible. + */ activateGizmos(isActive: boolean): void; - copyState(): void; - - pasteState(): void; - - saveState(): void; - - reset(): void; - + /** + * Set the camera to be controlled. Must be called in order to set a new camera to be controlled. + */ setCamera(camera: Camera): void; + /** + * Set the visible property of gizmos. + */ setGizmosVisible(value: boolean): void; + /** + * Update the `radiusFactor` value, redraw the gizmo and send a `changeEvent` to visualise the changes. + */ setTbRadius(value: number): void; - setMouseAction( - operation: ArcballControlsMouseActionOperations, - mouse: ArcballControlsMouseActionMouse, - key?: ArcballControlsMouseActionKeys, - ): boolean; + /** + * Reset the controls to their state from either the last time the {@link .saveState} was called, or the initial + * state. + */ + reset(): void; - unsetMouseAction(mouse: ArcballControlsMouseActionMouse, key?: ArcballControlsMouseActionKeys): boolean; + /** + * Copy the current state to clipboard (as a readable JSON text). + */ + copyState(): void; + + /** + * Set the controls state from the clipboard, assumes that the clipboard stores a JSON text as saved from + * {@link .copyState}. + */ + pasteState(): void; - update(): void; + /** + * Save the current state of the controls. This can later be recovered with {@link .reset}. + */ + saveState(): void; - dispose(): void; + /** + * Returns the {@link Raycaster} object that is used for user interaction. This object is shared between all + * instances of ArcballControls. If you set the [.layers]{@link Object3D.layers} property of the + * {@link ArcballControls}, you will also want to set the [.layers]{@link Raycaster.layers} property on the + * {@link Raycaster} with a matching value, or else the {@link ArcballControls} won't work as expected. + */ + getRaycaster(): Raycaster; } + +export { ArcballControls }; diff --git a/types/three/examples/jsm/controls/Controls.d.ts b/types/three/examples/jsm/controls/Controls.d.ts index 79c72a757..d2e14ad8c 100644 --- a/types/three/examples/jsm/controls/Controls.d.ts +++ b/types/three/examples/jsm/controls/Controls.d.ts @@ -24,7 +24,7 @@ declare abstract class Controls extends EventDispatcher { * Creates a new instance of DragControls. * @param objects An array of draggable 3D objects. * @param camera The camera of the rendered scene. - * @param domElement The HTML element used for event listeners. + * @param domElement The HTML element used for event listeners. (optional) */ constructor(objects: Object3D[], camera: Camera, domElement?: HTMLElement | null); diff --git a/types/three/examples/jsm/controls/FirstPersonControls.d.ts b/types/three/examples/jsm/controls/FirstPersonControls.d.ts index e85c978f7..e3d80ae80 100644 --- a/types/three/examples/jsm/controls/FirstPersonControls.d.ts +++ b/types/three/examples/jsm/controls/FirstPersonControls.d.ts @@ -75,7 +75,7 @@ declare class FirstPersonControls extends Controls<{}> { /** * Creates a new instance of {@link FirstPersonControls}. * @param object The camera to be controlled. - * @param domElement The HTML element used for event listeners. + * @param domElement The HTML element used for event listeners. (optional) */ constructor(object: Camera, domElement?: HTMLElement); diff --git a/types/three/examples/jsm/controls/FlyControls.d.ts b/types/three/examples/jsm/controls/FlyControls.d.ts index 8c7b3fc37..b26f9aa9a 100644 --- a/types/three/examples/jsm/controls/FlyControls.d.ts +++ b/types/three/examples/jsm/controls/FlyControls.d.ts @@ -37,7 +37,7 @@ declare class FlyControls extends Controls { /** * Creates a new instance of {@link FlyControls}. * @param object The camera to be controlled. - * @param domElement The HTML element used for event listeners. + * @param domElement The HTML element used for event listeners. (optional) */ constructor(object: Camera, domElement?: HTMLElement | null); }