Logo for jsDocs.io

@phosphor/dragdrop

  • Version 1.4.1
  • Published
  • 48.2 kB
  • 2 dependencies
  • BSD-3-Clause license

Install

npm i @phosphor/dragdrop
yarn add @phosphor/dragdrop
pnpm add @phosphor/dragdrop

Overview

PhosphorJS - Drag and Drop

Index

Classes

Interfaces

Type Aliases

Namespaces

Classes

class Drag

class Drag implements IDisposable {}

  • An object which manages a drag-drop operation.

    A drag object dispatches four different events to drop targets:

    - 'p-dragenter' - Dispatched when the mouse enters the target element. This event must be canceled in order to receive any of the other events.

    - 'p-dragover' - Dispatched when the mouse moves over the drop target. It must cancel the event and set the dropAction to one of the supported actions in order to receive drop events.

    - 'p-dragleave' - Dispatched when the mouse leaves the target element. This includes moving the mouse into child elements.

    - 'p-drop'- Dispatched when the mouse is released over the target element when the target indicates an appropriate drop action. If the event is canceled, the indicated drop action is returned to the initiator through the resolved promise.

    A drag operation can be terminated at any time by pressing Escape or by disposing the drag object.

    A drag object has the ability to automatically scroll a scrollable element when the mouse is hovered near one of its edges. To enable this, add the data-p-dragscroll attribute to any element which the drag object should consider for scrolling.

    #### Notes This class is designed to be used when dragging and dropping custom data *within* a single application. It is *not* a replacement for the native drag-drop API. Instead, it provides an API which allows drag operations to be initiated programmatically and enables the transfer of arbitrary non-string objects; features which are not possible with the native drag-drop API.

constructor

constructor(options: Drag.IOptions);

  • Construct a new drag object.

    Parameter options

    The options for initializing the drag.

property dragImage

readonly dragImage: HTMLElement;

  • The drag image element for the drag object.

property isDisposed

readonly isDisposed: boolean;

  • Test whether the drag object is disposed.

property mimeData

readonly mimeData: MimeData;

  • The mime data for the drag object.

property proposedAction

readonly proposedAction: DropAction;

  • The proposed drop action for the drag object.

property source

readonly source: any;

  • Get the drag source for the drag object.

property supportedActions

readonly supportedActions: SupportedActions;

  • The supported drop actions for the drag object.

method dispose

dispose: () => void;

  • Dispose of the resources held by the drag object.

    #### Notes This will cancel the drag operation if it is active.

method handleEvent

handleEvent: (event: Event) => void;

  • Handle the DOM events for the drag operation.

    Parameter event

    The DOM event sent to the drag object.

    #### Notes This method implements the DOM EventListener interface and is called in response to events on the document. It should not be called directly by user code.

method start

start: (clientX: number, clientY: number) => Promise<DropAction>;

  • Start the drag operation at the specified client position.

    Parameter clientX

    The client X position for the drag start.

    Parameter clientY

    The client Y position for the drag start.

    Returns

    A promise which resolves to the result of the drag.

    #### Notes If the drag has already been started, the promise created by the first call to start is returned.

    If the drag operation has ended, or if the drag object has been disposed, the returned promise will resolve to 'none'.

    The drag object will be automatically disposed when drag operation completes. This means Drag objects are for single-use only.

    This method assumes the left mouse button is already held down.

Interfaces

interface IDragEvent

interface IDragEvent extends MouseEvent {}

  • A custom event type used for drag-drop operations.

    #### Notes In order to receive 'p-dragover', 'p-dragleave', or 'p-drop' events, a drop target must cancel the 'p-dragenter' event by calling the event's preventDefault() method.

property dropAction

dropAction: DropAction;

  • The drop action supported or taken by the drop target.

    #### Notes At the start of each event, this value will be 'none'. During a 'p-dragover' event, the drop target must set this value to one of the supported actions, or the drop event will not occur.

    When handling the drop event, the drop target should set this to the action which was *actually* taken. This value will be reported back to the drag initiator.

property mimeData

readonly mimeData: MimeData;

  • The mime data associated with the event.

    #### Notes This is mime data provided by the drag initiator. Drop targets should use this data to determine if they can handle the drop.

property proposedAction

readonly proposedAction: DropAction;

  • The drop action proposed by the drag initiator.

    #### Notes This is the action which is *preferred* by the drag initiator. The drop target is not required to perform this action, but should if it all possible.

property source

readonly source: any;

  • The source object of the drag, as provided by the drag initiator.

    #### Notes For advanced applications, the drag initiator may wish to expose a source object to the drop targets. That will be provided here if given by the drag initiator, otherwise it will be null.

property supportedActions

readonly supportedActions: SupportedActions;

  • The drop actions supported by the drag initiator.

    #### Notes If the dropAction is not set to one of the supported actions during the 'p-dragover' event, the drop event will not occur.

Type Aliases

type DropAction

type DropAction = 'none' | 'copy' | 'link' | 'move';

  • A type alias which defines the possible independent drop actions.

type SupportedActions

type SupportedActions = DropAction | 'copy-link' | 'copy-move' | 'link-move' | 'all';

  • A type alias which defines the possible supported drop actions.

Namespaces

namespace Drag

namespace Drag {}

  • The namespace for the Drag class statics.

function overrideCursor

overrideCursor: (cursor: string) => IDisposable;

  • Override the cursor icon for the entire document.

    Parameter cursor

    The string representing the cursor style.

    Returns

    A disposable which will clear the override when disposed.

    #### Notes The most recent call to overrideCursor takes precedence. Disposing an old override has no effect on the current override.

    This utility function is used by the Drag class to override the mouse cursor during a drag-drop operation, but it can also be used by other classes to fix the cursor icon during normal mouse drags.

    #### Example

    import { Drag } from '@phosphor/dragdrop';
    

    // Force the cursor to be 'wait' for the entire document.
    let override = Drag.overrideCursor('wait');
    

    // Clear the override by disposing the return value.
    override.dispose();

interface IOptions

interface IOptions {}

  • An options object for initializing a Drag object.

property dragImage

dragImage?: HTMLElement;

  • An optional drag image which follows the mouse cursor.

    #### Notes The drag image can be any DOM element. It is not limited to image or canvas elements as with the native drag-drop APIs.

    If provided, this will be positioned at the mouse cursor on each mouse move event. A CSS transform can be used to offset the node from its specified position.

    The drag image will automatically have the p-mod-drag-image class name added.

    The default value is null.

property mimeData

mimeData: MimeData;

  • The populated mime data for the drag operation.

property proposedAction

proposedAction?: DropAction;

  • The optional proposed drop action for the drag operation.

    #### Notes This can be provided as a hint to the drop targets as to which drop action is preferred.

    The default value is 'copy'.

property source

source?: any;

  • An optional object which indicates the source of the drag.

    #### Notes For advanced applications, the drag initiator may wish to expose a source object to the drop targets. That object can be specified here and will be carried along with the drag events.

    The default value is null.

property supportedActions

supportedActions?: SupportedActions;

  • The drop actions supported by the drag initiator.

    #### Notes A drop target must indicate that it intends to perform one of the supported actions in order to receive a drop event. However, it is not required to *actually* perform that action when handling the drop event. Therefore, the initiator must be prepared to handle any drop action performed by a drop target.

    The default value is 'all'.

Package Files (1)

Dependencies (2)

Dev Dependencies (18)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@phosphor/dragdrop.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@phosphor/dragdrop)
  • HTML
    <a href="https://www.jsdocs.io/package/@phosphor/dragdrop"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>