gecko-dev/dom/interfaces/events/nsIDOMDataTransfer.idl

144 строки
5.5 KiB
Plaintext

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "domstubs.idl"
interface nsIVariant;
interface nsIDOMFileList;
[builtinclass, uuid(655078bf-1675-4aa0-a48d-a133e864ce57)]
interface nsIDOMDataTransfer : nsISupports
{
/**
* The actual effect that will be used, and should always be one of the
* possible values of effectAllowed.
*
* For dragstart, drag and dragleave events, the dropEffect is initialized
* to none. Any value assigned to the dropEffect will be set, but the value
* isn't used for anything.
*
* For the dragenter and dragover events, the dropEffect will be initialized
* based on what action the user is requesting. How this is determined is
* platform specific, but typically the user can press modifier keys to
* adjust which action is desired. Within an event handler for the dragenter
* and dragover events, the dropEffect should be modified if the action the
* user is requesting is not the one that is desired.
*
* For the drop and dragend events, the dropEffect will be initialized to
* the action that was desired, which will be the value that the dropEffect
* had after the last dragenter or dragover event.
*
* Possible values:
* copy - a copy of the source item is made at the new location
* move - an item is moved to a new location
* link - a link is established to the source at the new location
* none - the item may not be dropped
*
* Assigning any other value has no effect and retains the old value.
*/
attribute DOMString dropEffect;
/*
* Specifies the effects that are allowed for this drag. You may set this in
* the dragstart event to set the desired effects for the source, and within
* the dragenter and dragover events to set the desired effects for the
* target. The value is not used for other events.
*
* Possible values:
* copy - a copy of the source item is made at the new location
* move - an item is moved to a new location
* link - a link is established to the source at the new location
* copyLink, copyMove, linkMove, all - combinations of the above
* none - the item may not be dropped
* uninitialized - the default value when the effect has not been set,
* equivalent to all.
*
* Assigning any other value has no effect and retains the old value.
*/
attribute DOMString effectAllowed;
/**
* Holds a list of all the local files available on this data transfer.
* A dataTransfer containing no files will return an empty list, and an
* invalid index access on the resulting file list will return null.
*/
readonly attribute nsIDOMFileList files;
/**
* Set the image to be used for dragging if a custom one is desired. Most of
* the time, this would not be set, as a default image is created from the
* node that was dragged.
*
* If the node is an HTML img element, an HTML canvas element or a XUL image
* element, the image data is used. Otherwise, image should be a visible
* node and the drag image will be created from this. If image is null, any
* custom drag image is cleared and the default is used instead.
*
* The coordinates specify the offset into the image where the mouse cursor
* should be. To center the image for instance, use values that are half the
* width and height.
*
* @param image a node to use
* @param x the horizontal offset
* @param y the vertical offset
* @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
*/
void setDragImage(in nsIDOMElement image, in long x, in long y);
/*
* Set the drag source. Usually you would not change this, but it will
* affect which node the drag and dragend events are fired at. The
* default target is the node that was dragged.
*
* @param element drag source to use
* @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
*/
void addElement(in nsIDOMElement element);
/**
* The number of items being dragged.
*/
readonly attribute unsigned long mozItemCount;
/**
* Sets the drag cursor state. Primarily used to control the cursor during
* tab drags, but could be expanded to other uses. XXX Currently implemented
* on Win32 only.
*
* Possible values:
* auto - use default system behavior.
* default - set the cursor to an arrow during the drag operation.
*
* Values other than 'default' are indentical to setting mozCursor to
* 'auto'.
*/
attribute DOMString mozCursor;
/**
* Will be true when the user has cancelled the drag (typically by pressing
* Escape) and when the drag has been cancelled unexpectedly. This will be
* false otherwise, including when the drop has been rejected by its target.
* This property is only relevant for the dragend event.
*/
readonly attribute boolean mozUserCancelled;
/**
* The node that the mouse was pressed over to begin the drag. For external
* drags, or if the caller cannot access this node, this will be null.
*/
readonly attribute nsIDOMNode mozSourceNode;
/*
* Integer version of dropEffect, set to one of the constants in nsIDragService.
*/
[noscript] attribute unsigned long dropEffectInt;
/*
* Integer version of effectAllowed, set to one or a combination of the
* constants in nsIDragService.
*/
[noscript] attribute unsigned long effectAllowedInt;
};