1 | import { MimeData } from '@phosphor/coreutils';
|
2 | import { IDisposable } from '@phosphor/disposable';
|
3 | /**
|
4 | * A type alias which defines the possible independent drop actions.
|
5 | */
|
6 | export declare type DropAction = 'none' | 'copy' | 'link' | 'move';
|
7 | /**
|
8 | * A type alias which defines the possible supported drop actions.
|
9 | */
|
10 | export declare type SupportedActions = DropAction | 'copy-link' | 'copy-move' | 'link-move' | 'all';
|
11 | /**
|
12 | * A custom event type used for drag-drop operations.
|
13 | *
|
14 | * #### Notes
|
15 | * In order to receive `'p-dragover'`, `'p-dragleave'`, or `'p-drop'`
|
16 | * events, a drop target must cancel the `'p-dragenter'` event by
|
17 | * calling the event's `preventDefault()` method.
|
18 | */
|
19 | export interface IDragEvent extends MouseEvent {
|
20 | /**
|
21 | * The drop action supported or taken by the drop target.
|
22 | *
|
23 | * #### Notes
|
24 | * At the start of each event, this value will be `'none'`. During a
|
25 | * `'p-dragover'` event, the drop target must set this value to one
|
26 | * of the supported actions, or the drop event will not occur.
|
27 | *
|
28 | * When handling the drop event, the drop target should set this
|
29 | * to the action which was *actually* taken. This value will be
|
30 | * reported back to the drag initiator.
|
31 | */
|
32 | dropAction: DropAction;
|
33 | /**
|
34 | * The drop action proposed by the drag initiator.
|
35 | *
|
36 | * #### Notes
|
37 | * This is the action which is *preferred* by the drag initiator. The
|
38 | * drop target is not required to perform this action, but should if
|
39 | * it all possible.
|
40 | */
|
41 | readonly proposedAction: DropAction;
|
42 | /**
|
43 | * The drop actions supported by the drag initiator.
|
44 | *
|
45 | * #### Notes
|
46 | * If the `dropAction` is not set to one of the supported actions
|
47 | * during the `'p-dragover'` event, the drop event will not occur.
|
48 | */
|
49 | readonly supportedActions: SupportedActions;
|
50 | /**
|
51 | * The mime data associated with the event.
|
52 | *
|
53 | * #### Notes
|
54 | * This is mime data provided by the drag initiator. Drop targets
|
55 | * should use this data to determine if they can handle the drop.
|
56 | */
|
57 | readonly mimeData: MimeData;
|
58 | /**
|
59 | * The source object of the drag, as provided by the drag initiator.
|
60 | *
|
61 | * #### Notes
|
62 | * For advanced applications, the drag initiator may wish to expose
|
63 | * a source object to the drop targets. That will be provided here
|
64 | * if given by the drag initiator, otherwise it will be `null`.
|
65 | */
|
66 | readonly source: any;
|
67 | }
|
68 | /**
|
69 | * An object which manages a drag-drop operation.
|
70 | *
|
71 | * A drag object dispatches four different events to drop targets:
|
72 | *
|
73 | * - `'p-dragenter'` - Dispatched when the mouse enters the target
|
74 | * element. This event must be canceled in order to receive any
|
75 | * of the other events.
|
76 | *
|
77 | * - `'p-dragover'` - Dispatched when the mouse moves over the drop
|
78 | * target. It must cancel the event and set the `dropAction` to one
|
79 | * of the supported actions in order to receive drop events.
|
80 | *
|
81 | * - `'p-dragleave'` - Dispatched when the mouse leaves the target
|
82 | * element. This includes moving the mouse into child elements.
|
83 | *
|
84 | * - `'p-drop'`- Dispatched when the mouse is released over the target
|
85 | * element when the target indicates an appropriate drop action. If
|
86 | * the event is canceled, the indicated drop action is returned to
|
87 | * the initiator through the resolved promise.
|
88 | *
|
89 | * A drag operation can be terminated at any time by pressing `Escape`
|
90 | * or by disposing the drag object.
|
91 | *
|
92 | * A drag object has the ability to automatically scroll a scrollable
|
93 | * element when the mouse is hovered near one of its edges. To enable
|
94 | * this, add the `data-p-dragscroll` attribute to any element which
|
95 | * the drag object should consider for scrolling.
|
96 | *
|
97 | * #### Notes
|
98 | * This class is designed to be used when dragging and dropping custom
|
99 | * data *within* a single application. It is *not* a replacement for
|
100 | * the native drag-drop API. Instead, it provides an API which allows
|
101 | * drag operations to be initiated programmatically and enables the
|
102 | * transfer of arbitrary non-string objects; features which are not
|
103 | * possible with the native drag-drop API.
|
104 | */
|
105 | export declare class Drag implements IDisposable {
|
106 | /**
|
107 | * Construct a new drag object.
|
108 | *
|
109 | * @param options - The options for initializing the drag.
|
110 | */
|
111 | constructor(options: Drag.IOptions);
|
112 | /**
|
113 | * Dispose of the resources held by the drag object.
|
114 | *
|
115 | * #### Notes
|
116 | * This will cancel the drag operation if it is active.
|
117 | */
|
118 | dispose(): void;
|
119 | /**
|
120 | * The mime data for the drag object.
|
121 | */
|
122 | readonly mimeData: MimeData;
|
123 | /**
|
124 | * The drag image element for the drag object.
|
125 | */
|
126 | readonly dragImage: HTMLElement | null;
|
127 | /**
|
128 | * The proposed drop action for the drag object.
|
129 | */
|
130 | readonly proposedAction: DropAction;
|
131 | /**
|
132 | * The supported drop actions for the drag object.
|
133 | */
|
134 | readonly supportedActions: SupportedActions;
|
135 | /**
|
136 | * Get the drag source for the drag object.
|
137 | */
|
138 | readonly source: any;
|
139 | /**
|
140 | * Test whether the drag object is disposed.
|
141 | */
|
142 | readonly isDisposed: boolean;
|
143 | /**
|
144 | * Start the drag operation at the specified client position.
|
145 | *
|
146 | * @param clientX - The client X position for the drag start.
|
147 | *
|
148 | * @param clientY - The client Y position for the drag start.
|
149 | *
|
150 | * @returns A promise which resolves to the result of the drag.
|
151 | *
|
152 | * #### Notes
|
153 | * If the drag has already been started, the promise created by the
|
154 | * first call to `start` is returned.
|
155 | *
|
156 | * If the drag operation has ended, or if the drag object has been
|
157 | * disposed, the returned promise will resolve to `'none'`.
|
158 | *
|
159 | * The drag object will be automatically disposed when drag operation
|
160 | * completes. This means `Drag` objects are for single-use only.
|
161 | *
|
162 | * This method assumes the left mouse button is already held down.
|
163 | */
|
164 | start(clientX: number, clientY: number): Promise<DropAction>;
|
165 | /**
|
166 | * Handle the DOM events for the drag operation.
|
167 | *
|
168 | * @param event - The DOM event sent to the drag object.
|
169 | *
|
170 | * #### Notes
|
171 | * This method implements the DOM `EventListener` interface and is
|
172 | * called in response to events on the document. It should not be
|
173 | * called directly by user code.
|
174 | */
|
175 | handleEvent(event: Event): void;
|
176 | /**
|
177 | * Handle the `'mousemove'` event for the drag object.
|
178 | */
|
179 | private _evtMouseMove;
|
180 | /**
|
181 | * Handle the `'mouseup'` event for the drag object.
|
182 | */
|
183 | private _evtMouseUp;
|
184 | /**
|
185 | * Handle the `'keydown'` event for the drag object.
|
186 | */
|
187 | private _evtKeyDown;
|
188 | /**
|
189 | * Add the document event listeners for the drag object.
|
190 | */
|
191 | private _addListeners;
|
192 | /**
|
193 | * Remove the document event listeners for the drag object.
|
194 | */
|
195 | private _removeListeners;
|
196 | /**
|
197 | * Update the drag scroll element under the mouse.
|
198 | */
|
199 | private _updateDragScroll;
|
200 | /**
|
201 | * Update the current target node using the given mouse event.
|
202 | */
|
203 | private _updateCurrentTarget;
|
204 | /**
|
205 | * Attach the drag image element at the specified location.
|
206 | *
|
207 | * This is a no-op if there is no drag image element.
|
208 | */
|
209 | private _attachDragImage;
|
210 | /**
|
211 | * Move the drag image element to the specified location.
|
212 | *
|
213 | * This is a no-op if there is no drag image element.
|
214 | */
|
215 | private _moveDragImage;
|
216 | /**
|
217 | * Detach the drag image element from the DOM.
|
218 | *
|
219 | * This is a no-op if there is no drag image element.
|
220 | */
|
221 | private _detachDragImage;
|
222 | /**
|
223 | * Set the internal drop action state and update the drag cursor.
|
224 | */
|
225 | private _setDropAction;
|
226 | /**
|
227 | * Finalize the drag operation and resolve the drag promise.
|
228 | */
|
229 | private _finalize;
|
230 | /**
|
231 | * The scroll loop handler function.
|
232 | */
|
233 | private _onScrollFrame;
|
234 | private _disposed;
|
235 | private _dropAction;
|
236 | private _override;
|
237 | private _currentTarget;
|
238 | private _currentElement;
|
239 | private _promise;
|
240 | private _scrollTarget;
|
241 | private _resolve;
|
242 | }
|
243 | /**
|
244 | * The namespace for the `Drag` class statics.
|
245 | */
|
246 | export declare namespace Drag {
|
247 | /**
|
248 | * An options object for initializing a `Drag` object.
|
249 | */
|
250 | interface IOptions {
|
251 | /**
|
252 | * The populated mime data for the drag operation.
|
253 | */
|
254 | mimeData: MimeData;
|
255 | /**
|
256 | * An optional drag image which follows the mouse cursor.
|
257 | *
|
258 | * #### Notes
|
259 | * The drag image can be any DOM element. It is not limited to
|
260 | * image or canvas elements as with the native drag-drop APIs.
|
261 | *
|
262 | * If provided, this will be positioned at the mouse cursor on each
|
263 | * mouse move event. A CSS transform can be used to offset the node
|
264 | * from its specified position.
|
265 | *
|
266 | * The drag image will automatically have the `p-mod-drag-image`
|
267 | * class name added.
|
268 | *
|
269 | * The default value is `null`.
|
270 | */
|
271 | dragImage?: HTMLElement;
|
272 | /**
|
273 | * The optional proposed drop action for the drag operation.
|
274 | *
|
275 | * #### Notes
|
276 | * This can be provided as a hint to the drop targets as to which
|
277 | * drop action is preferred.
|
278 | *
|
279 | * The default value is `'copy'`.
|
280 | */
|
281 | proposedAction?: DropAction;
|
282 | /**
|
283 | * The drop actions supported by the drag initiator.
|
284 | *
|
285 | * #### Notes
|
286 | * A drop target must indicate that it intends to perform one of the
|
287 | * supported actions in order to receive a drop event. However, it is
|
288 | * not required to *actually* perform that action when handling the
|
289 | * drop event. Therefore, the initiator must be prepared to handle
|
290 | * any drop action performed by a drop target.
|
291 | *
|
292 | * The default value is `'all'`.
|
293 | */
|
294 | supportedActions?: SupportedActions;
|
295 | /**
|
296 | * An optional object which indicates the source of the drag.
|
297 | *
|
298 | * #### Notes
|
299 | * For advanced applications, the drag initiator may wish to expose
|
300 | * a source object to the drop targets. That object can be specified
|
301 | * here and will be carried along with the drag events.
|
302 | *
|
303 | * The default value is `null`.
|
304 | */
|
305 | source?: any;
|
306 | }
|
307 | /**
|
308 | * Override the cursor icon for the entire document.
|
309 | *
|
310 | * @param cursor - The string representing the cursor style.
|
311 | *
|
312 | * @returns A disposable which will clear the override when disposed.
|
313 | *
|
314 | * #### Notes
|
315 | * The most recent call to `overrideCursor` takes precedence.
|
316 | * Disposing an old override has no effect on the current override.
|
317 | *
|
318 | * This utility function is used by the `Drag` class to override the
|
319 | * mouse cursor during a drag-drop operation, but it can also be used
|
320 | * by other classes to fix the cursor icon during normal mouse drags.
|
321 | *
|
322 | * #### Example
|
323 | * ```typescript
|
324 | * import { Drag } from '@phosphor/dragdrop';
|
325 | *
|
326 | * // Force the cursor to be 'wait' for the entire document.
|
327 | * let override = Drag.overrideCursor('wait');
|
328 | *
|
329 | * // Clear the override by disposing the return value.
|
330 | * override.dispose();
|
331 | * ```
|
332 | */
|
333 | function overrideCursor(cursor: string): IDisposable;
|
334 | }
|