1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/editor/idl/nsIContentFilter.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,85 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +#include "domstubs.idl"
1.11 +
1.12 +interface nsIURL;
1.13 +
1.14 +[scriptable, uuid(c18c49a8-62f0-4045-9884-4aa91e388f14)]
1.15 +interface nsIContentFilter : nsISupports
1.16 +{
1.17 + /**
1.18 + * This notification occurs in an editor during these events:
1.19 + * * open of document (once rendered in window but before editable)
1.20 + * * paste from clipboard
1.21 + * * drop from mouse
1.22 + * * insertion of html (such as with "cmd_insertHTML")
1.23 + * It provides a hook so the above actions can be canceled or the data
1.24 + * can be modified (using standard DOM APIs) or left untouched. The data
1.25 + * that results (if any) from all filter callbacks is what will be used
1.26 + * for transaction purposes (undo/redo) except for the open event.
1.27 + *
1.28 + * The willDeleteSelection parameter is offered for filters who want to
1.29 + * handle the insertion themselves and need to handle drag/drop correctly.
1.30 + * The flag is true when the editor intends to delete the selection.
1.31 + *
1.32 + * Callers who want to cancel all insertion can simply set
1.33 + * continueWithInsertion to PR_FALSE and return.
1.34 + * Note: If cancellation occurs during the "open" event, the editor will
1.35 + * still be available but will be empty.
1.36 + *
1.37 + * Callers who want to allow insertion of the data with no changes
1.38 + * can simply set continueWithInsertion to PR_TRUE and return.
1.39 + *
1.40 + * Callers who want to modify the content (docFragment) being inserted are
1.41 + * responsible for updating contentStartNode, contentStartOffset,
1.42 + * contentEndNode, and contentEndOffset (if necessary).
1.43 + * Callers are responsible for freeing and addref'ing if they want to
1.44 + * completely replace any of the DOM nodes passed in.
1.45 + *
1.46 + * The location where insertion will occur should be considered an
1.47 + * approximation since the editor may need to adjust it if it deletes
1.48 + * the selection as part of the event and later determines that insertion
1.49 + * point is an empty container which should also be removed (or in other
1.50 + * scenarios such as -moz-user-select:none).
1.51 + *
1.52 + * In some scenarios the selection will be deleted. If callers choose
1.53 + * to adjust the insertion point, they should be careful that the insertion
1.54 + * point is not in the current selection.
1.55 + *
1.56 + * The contentStartNode and contentEndNode are not necessarily
1.57 + * immediate children of the docFragment. Any nodes outside of the range
1.58 + * set by contentStartNode and contentEndNode are for context from the
1.59 + * source document.
1.60 + *
1.61 + * @param mimeType the mimetype used for retrieving data
1.62 + * @param contentSourceURL location where docFragment came from
1.63 + * @param sourceDocument document where content came from (can be null)
1.64 + * @param willDeleteSelection tells hook if selection will/should be deleted
1.65 + * @param docFragment fragment of node to be inserted
1.66 + * @param contentStartNode node under which content to be inserted begins
1.67 + * @param contentStartOffset start offset within contentStartNode
1.68 + * @param contentEndNode node under which content to be inserted ends
1.69 + * @param contentEndOffset ending offset withing contentEndNode
1.70 + * @param insertionPointNode location where insertion will occur
1.71 + * @param insertionPointOffset offset within node where insertion occurs
1.72 + * @param continueWithInsertion flag to cancel insertion (if desired)
1.73 + */
1.74 +
1.75 + void notifyOfInsertion(in AString mimeType,
1.76 + in nsIURL contentSourceURL,
1.77 + in nsIDOMDocument sourceDocument,
1.78 + in boolean willDeleteSelection,
1.79 + inout nsIDOMNode docFragment,
1.80 + inout nsIDOMNode contentStartNode,
1.81 + inout long contentStartOffset,
1.82 + inout nsIDOMNode contentEndNode,
1.83 + inout long contentEndOffset,
1.84 + inout nsIDOMNode insertionPointNode,
1.85 + inout long insertionPointOffset,
1.86 + out boolean continueWithInsertion);
1.87 +
1.88 +};
