@needle-tools/engine/lib/engine-components/DropListener.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in

import { Object3D, Vector3 } from "three";
import { Model, Vec3 } from "../engine/engine_types.js";
import { Behaviour } from "./Component.js";
import { EventList } from "./EventList.js";
export declare enum DropListenerEvents {
    /**
     * Dispatched when a file is dropped into the scene. The detail of the event is the file that was dropped.
     */
    FileDropped = "file-dropped",
    /**
     * Dispatched when a new object is added to the scene. The detail of the event is the glTF that was added.
     */
    ObjectAdded = "object-added"
}
/**  Networking event arguments for the DropListener component */
export declare type DropListenerNetworkEventArguments = {
    guid: string;
    name: string;
    url: string | string[];
    /** Worldspace point where the object was placed in the scene */
    point: Vec3;
    /** Bounding box size */
    size: Vec3;
    contentMD5: string;
};
declare type AddedEventArguments = {
    sender: DropListener;
    /** the root object added to the scene */
    object: Object3D;
    /** The whole dropped model */
    model: Model;
    contentMD5: string;
    dropped: URL | File | undefined;
};
/** Dispatched when an object is dropped/changed */
export declare class DropListenerAddedEvent<T extends AddedEventArguments> extends CustomEvent<T> {
    constructor(detail: T);
}
/** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene
 * It can be used to allow users to drag and drop glTF files into the scene to add new objects.
 *
 * ## Events
 * - **object-added** - dispatched when a new object is added to the scene
 * - **file-dropped** - dispatched when a file is dropped into the scene
 *
 * @example
 * ```typescript
 * import { DropListener, DropListenerEvents } from "@needle-tools/engine";
 *
 * const dropListener = new DropListener();
 *
 * gameObject.addComponent(dropListener);
 * dropListener.on(DropListenerEvents.FileDropped, (evt) => {
 *   console.log("File dropped", evt.detail);
 *   const file = evt.detail as File;
 * });
 *
 * dropListener.on(DropListenerEvents.ObjectAdded, (evt) => {
 *    console.log("Object added", evt.detail);
 *    const gltf = evt.detail as GLTF;
 * });
 * ```
 *
 * @category Asset Management
 * @group Components
 */
export declare class DropListener extends Behaviour {
    /**
     * When enabled the DropListener will automatically network dropped files to other clients.
     */
    useNetworking: boolean;
    /**
     * When assigned the Droplistener will only accept files that are dropped on this object.
     */
    dropArea?: Object3D;
    /**
     * When enabled the object will be fitted into a volume. Use {@link fitVolumeSize} to specify the volume size.
     * @default false
     */
    fitIntoVolume: boolean;
    /**
     * The volume size will be used to fit the object into the volume. Use {@link fitIntoVolume} to enable this feature.
     */
    fitVolumeSize: Vector3;
    /** When enabled the object will be placed at the drop position (under the cursor)
     * @default true
     */
    placeAtHitPosition: boolean;
    /**
     * Invoked after a file has been **added** to the scene.
     * Arguments are {@link AddedEventArguments}
     * @event object-added
     * @param {AddedEventArguments} evt
     * @example
     * ```typescript
     * dropListener.onDropped.addEventListener((evt) => {
     *  console.log("Object added", evt.model);
     * });
     */
    onDropped: EventList<AddedEventArguments>;
    /** @internal */
    onEnable(): void;
    /** @internal */
    onDisable(): void;
    /**
     * Loads a file from the given URL and adds it to the scene.
     */
    loadFromURL(url: string, data?: {
        point?: Vec3;
        size?: Vec3;
    }): void;
    /**
     * Forgets all previously added objects.
     * The droplistener will then not be able to remove previously added objects.
     */
    forgetObjects(): void;
    private onNetworkEvent;
    private handlePaste;
    private onDrag;
    private onDrop;
    private addFromUrl;
    private _abort;
    private addDroppedFiles;
    /** Previously added objects */
    private readonly _addedObjects;
    private readonly _addedModels;
    /** Removes all previously added objects from the scene and removes those object references  */
    private removePreviouslyAddedObjects;
    /**
     * Adds the object to the scene and fits it into the volume if {@link fitIntoVolume} is enabled.
     */
    private addObject;
    private sendDropEvent;
    private deleteDropEvent;
    private testIfIsInDropArea;
}
export {};