1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/widget/nsIClipboardDragDropHooks.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,101 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsITransferable;
1.11 +interface nsIDragSession;
1.12 +interface nsIDOMEvent;
1.13 +
1.14 +
1.15 +/**
1.16 + * Interfaces for overriding the built-in drag, drop, copy, and paste
1.17 + * implementations in the content area and editors. Use this to do things
1.18 + * such as prevent a drag from starting, adding or removing
1.19 + * data and flavors, or preventing the drop.
1.20 + *
1.21 + * Embedders who want to have these hooks made available should implement
1.22 + * nsIClipboardDragDropHooks and use the command manager to send the
1.23 + * appropriate commands with these parameters/settings:
1.24 + * command: cmd_clipboardDragDropHook
1.25 + *
1.26 + * params value type possible values
1.27 + * "addhook" isupports nsIClipboardDragDropHooks as nsISupports
1.28 + * "removehook" isupports nsIClipboardDragDropHooks as nsISupports
1.29 + *
1.30 + * Notes:
1.31 + * * Overrides/hooks need to be added to each window (as appropriate).
1.32 + * Adding them to the first window does not enable them for every window.
1.33 + * * If more than one implementation is set for a window, the hooks will be
1.34 + * called in the order they are added.
1.35 + * * Adding the same hook to the same window will not add a second call.
1.36 + * Each hook can only be called once per user action/api.
1.37 + * * Not all hooks are guaranteed to be called. If there are multiple hooks
1.38 + * set for a window, any of them has an opportunity to cancel the action
1.39 + * so no further processing will occur.
1.40 + * * If any errors occur (without setting the boolean result) the default
1.41 + * action will occur.
1.42 + * * AllowDrop will be called MANY times during drag so ensure that it is
1.43 + * efficient.
1.44 + */
1.45 +
1.46 +
1.47 +[scriptable,uuid(e03e6c5e-0d84-4c0b-8739-e6b8d51922de)]
1.48 +interface nsIClipboardDragDropHooks : nsISupports
1.49 +{
1.50 + /**
1.51 + * Prevents the drag from starting
1.52 + *
1.53 + * @param event DOM event (drag gesture)
1.54 + *
1.55 + * @return TRUE drag can proceed
1.56 + * @return FALSE drag is cancelled, does not go to OS
1.57 + */
1.58 + boolean allowStartDrag(in nsIDOMEvent event);
1.59 +
1.60 + /**
1.61 + * Tells gecko whether a drop is allowed on this content area
1.62 + *
1.63 + * @param event DOM event (drag over)
1.64 + * @param session the drag session from which client can get
1.65 + * the flavors present or the actual data
1.66 + *
1.67 + * @return TRUE indicates to OS that if a drop does happen on this
1.68 + * browser, it will be accepted.
1.69 + * @return FALSE indicates to OS drop is not allowed. On win32, this
1.70 + * will change the cursor to "reject".
1.71 + */
1.72 + boolean allowDrop(in nsIDOMEvent event, in nsIDragSession session);
1.73 +
1.74 + /**
1.75 + * Alter the flavors or data presented to the OS
1.76 + * Used for drag and copy actions
1.77 + * Because this can be called many times, it is highly recommended
1.78 + * that the implementation be very efficient so user feedback is
1.79 + * not negatively impacted.
1.80 + *
1.81 + * @param event DOM event (drag drop); null if triggered by copy.
1.82 + * @param trans the transferable holding the list of flavors
1.83 + * and the data for each flavor
1.84 + *
1.85 + * @return TRUE copy/drag can proceed
1.86 + * @return FALSE copy/drag is cancelled, does not go to OS
1.87 + */
1.88 + boolean onCopyOrDrag(in nsIDOMEvent aEvent, in nsITransferable trans);
1.89 +
1.90 + /**
1.91 + * Provide an alternative action to the built-in behavior when
1.92 + * something is dropped on the browser or in an editor
1.93 + *
1.94 + * @param event DOM event (drag drop); null if triggered by paste.
1.95 + * @param trans the transferable holding the list of flavors
1.96 + * and the data for each flavor
1.97 + *
1.98 + * @return TRUE action was handled, do not perform built-in
1.99 + * behavior
1.100 + * @return FALSE action was not overridden, do built-in behavior
1.101 + */
1.102 + boolean onPasteOrDrop(in nsIDOMEvent event, in nsITransferable trans);
1.103 +};
1.104 +
