diff --git a/types/three/examples/jsm/controls/DragControls.d.ts b/types/three/examples/jsm/controls/DragControls.d.ts index bba1fbfb0..8235eac56 100644 --- a/types/three/examples/jsm/controls/DragControls.d.ts +++ b/types/three/examples/jsm/controls/DragControls.d.ts @@ -77,21 +77,6 @@ declare class DragControls extends Controls { */ constructor(objects: Object3D[], camera: Camera, domElement?: HTMLElement | null); - /** - * Adds the event listeners of the controls. - */ - connect(): void; - - /** - * Removes the event listeners of the controls. - */ - disconnect(): void; - - /** - * Should be called if the controls is no longer required. - */ - dispose(): void; - /** * Returns the internal {@link Raycaster} instance that is used for intersection tests. * @deprecated getRaycaster() has been deprecated. Use controls.raycaster instead. diff --git a/types/three/examples/jsm/controls/TransformControls.d.ts b/types/three/examples/jsm/controls/TransformControls.d.ts index adf7757ac..568939b26 100644 --- a/types/three/examples/jsm/controls/TransformControls.d.ts +++ b/types/three/examples/jsm/controls/TransformControls.d.ts @@ -1,12 +1,29 @@ -import { Camera, Mesh, MOUSE, Object3D, Object3DEventMap, Quaternion, Raycaster, Vector3 } from "three"; +import { Camera, Controls, Mesh, Object3D, Quaternion, Raycaster, Vector3 } from "three"; type TransformControlsMode = "translate" | "rotate" | "scale"; -export interface TransformControlsEventMap extends Object3DEventMap { +export interface TransformControlsEventMap { + /** + * Fires if any type of change (object or property change) is performed. Property changes are separate events you + * can add event listeners to. The event type is "propertyname-changed". + */ change: {}; + + /** + * Fires if a pointer (mouse/touch) becomes active. + */ mouseDown: { mode: TransformControlsMode }; + + /** + * Fires if a pointer (mouse/touch) is no longer active. + */ mouseUp: { mode: TransformControlsMode }; + + /** + * Fires if the controlled 3D object is changed. + */ objectChange: {}; + "camera-changed": { value: unknown }; "object-changed": { value: unknown }; "enabled-changed": { value: unknown }; @@ -34,55 +51,164 @@ export interface TransformControlsEventMap extends Object3DEventMap { "eye-changed": { value: unknown }; } -export class TransformControls extends Object3D { - constructor(object: Camera, domElement?: HTMLElement); - - domElement: HTMLElement; - - // API - +/** + * This class can be used to transform objects in 3D space by adapting a similar interaction model of DCC tools like + * Blender. Unlike other controls, it is not intended to transform the scene's camera. + * + * TransformControls expects that its attached 3D object is part of the scene graph. + */ +declare class TransformControls extends Controls { + /** + * The camera of the rendered scene. + */ camera: Camera; - object: Object3D | undefined; - enabled: boolean; + + /** + * The current transformation axis. + */ axis: "X" | "Y" | "Z" | "E" | "XY" | "YZ" | "XZ" | "XYZ" | "XYZE" | null; + + /** + * The current transformation mode. Possible values are "translate", "rotate" and "scale". Default is `translate`. + */ mode: TransformControlsMode; + + /** + * By default, 3D objects are continuously translated. If you set this property to a numeric value (world units), + * you can define in which steps the 3D object should be translated. Default is `null`. + */ translationSnap: number | null; + + /** + * By default, 3D objects are continuously rotated. If you set this property to a numeric value (radians), you can + * define in which steps the 3D object should be rotated. Default is `null`. + */ rotationSnap: number | null; + + /** + * Defines in which coordinate space transformations should be performed. Possible values are "world" and "local". + * Default is `world`. + */ space: "world" | "local"; + + /** + * The size of the helper UI (axes/planes). Default is *1*. + */ size: number; + + /** + * Whether or not dragging is currently performed. Read-only property. + */ dragging: boolean; + + /** + * Whether or not the x-axis helper should be visible. Default is `true`. + */ showX: boolean; + + /** + * Whether or not the y-axis helper should be visible. Default is `true`. + */ showY: boolean; + + /** + * Whether or not the z-axis helper should be visible. Default is `true`. + */ showZ: boolean; - readonly isTransformControls: true; - mouseButtons: { - LEFT?: MOUSE | null | undefined; - MIDDLE?: MOUSE | null | undefined; - RIGHT?: MOUSE | null | undefined; - }; + /** + * Creates a new instance of TransformControls. + * @param camera The camera of the rendered scene. + * @param domElement The HTML element used for event listeners. (optional) + */ + constructor(camera: Camera, domElement?: HTMLElement); + + /** + * Returns the visual representation of the controls. Add the gizmo to your scene to visually transform the attached + * 3D object. + */ + getGizmo(): TransformControlsRoot; pointerHover(pointer: PointerEvent | null): void; pointerDown(pointer: PointerEvent | null): void; pointerMove(pointer: PointerEvent | null): void; pointerUp(pointer: PointerEvent | null): void; + /** + * Sets the 3D object that should be transformed and ensures the controls UI is visible. + * @param object The 3D object that should be transformed. + */ attach(object: Object3D): this; + + /** + * Removes the current 3D object from the controls and makes the helper UI invisible. + */ detach(): this; - getMode(): TransformControlsMode; + + /** + * Resets the object's position, rotation and scale to when the current transform began. + */ + reset(): void; + + /** + * Returns the {@link Raycaster} object that is used for user interaction. This object is shared between all + * instances of TransformControls. If you set the [.layers]{@link Object3D.layers} property of the + * TransformControls, you will also want to set the [.layers]{@link Raycaster.layers} property on the + * {@link Raycaster} with a matching value, or else the TransformControls won't work as expected. + */ getRaycaster(): Raycaster; + + /** + * Returns the transformation mode. + */ + getMode(): TransformControlsMode; + + /** + * Sets the transformation mode. + * @param mode The transformation mode. + */ setMode(mode: TransformControlsMode): void; + + /** + * Sets the translation snap. + * @param translationSnap The translation snap. + */ setTranslationSnap(translationSnap: number | null): void; + + /** + * Sets the rotation snap. + * @param rotationSnap The rotation snap. + */ setRotationSnap(rotationSnap: number | null): void; + + /** + * Sets the scale snap. + * @param scaleSnap The scale snap. + */ setScaleSnap(scaleSnap: number | null): void; + + /** + * Sets the size of the helper UI. + * @param size The size of the helper UI. + */ setSize(size: number): void; + + /** + * Sets the coordinate space in which transformations are applied. + * @param space The coordinate space in which transformations are applied. + */ setSpace(space: "world" | "local"): void; - reset(): void; - dispose(): void; } -export class TransformControlsGizmo extends Object3D { - type: "TransformControlsGizmo"; +declare class TransformControlsRoot extends Object3D { + readonly isTransformControlsRoot: true; + + controls: TransformControls; + + constructor(controls: TransformControls); +} + +declare class TransformControlsGizmo extends Object3D { isTransformControlsGizmo: true; gizmo: { @@ -104,9 +230,8 @@ export class TransformControlsGizmo extends Object3D { constructor(); } -export class TransformControlsPlane extends Mesh { - type: "TransformControlsPlane"; - isTransformControlsPlane: true; +declare class TransformControlsPlane extends Mesh { + readonly isTransformControlsPlane: true; constructor(); @@ -120,3 +245,5 @@ export class TransformControlsPlane extends Mesh { worldPosition: Vector3; worldQuaternion: Quaternion; } + +export { TransformControls, TransformControlsGizmo, TransformControlsPlane }; diff --git a/types/three/src/extras/Controls.d.ts b/types/three/src/extras/Controls.d.ts index f69e6093b..6202a5c0c 100644 --- a/types/three/src/extras/Controls.d.ts +++ b/types/three/src/extras/Controls.d.ts @@ -1,5 +1,5 @@ -import { Camera } from "../cameras/Camera.js"; import { EventDispatcher } from "../core/EventDispatcher.js"; +import { Object3D } from "../core/Object3D.js"; /** * Abstract base class for controls. @@ -8,7 +8,7 @@ declare abstract class Controls extends EventDispatcher extends EventDispatcher