michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0:  
michael@0: #include "nsISupports.idl"
michael@0: #include "domstubs.idl"
michael@0: 
michael@0: interface nsIURL;
michael@0: 
michael@0: [scriptable, uuid(c18c49a8-62f0-4045-9884-4aa91e388f14)]
michael@0: interface nsIContentFilter : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * This notification occurs in an editor during these events:
michael@0:    *    * open of document (once rendered in window but before editable)
michael@0:    *    * paste from clipboard
michael@0:    *    * drop from mouse
michael@0:    *    * insertion of html (such as with "cmd_insertHTML")
michael@0:    * It provides a hook so the above actions can be canceled or the data
michael@0:    * can be modified (using standard DOM APIs) or left untouched.  The data
michael@0:    * that results (if any) from all filter callbacks is what will be used
michael@0:    * for transaction purposes (undo/redo) except for the open event.
michael@0:    *
michael@0:    * The willDeleteSelection parameter is offered for filters who want to
michael@0:    * handle the insertion themselves and need to handle drag/drop correctly.
michael@0:    * The flag is true when the editor intends to delete the selection.
michael@0:    *
michael@0:    * Callers who want to cancel all insertion can simply set
michael@0:    * continueWithInsertion to PR_FALSE and return.
michael@0:    * Note: If cancellation occurs during the "open" event, the editor will
michael@0:    * still be available but will be empty.
michael@0:    *
michael@0:    * Callers who want to allow insertion of the data with no changes
michael@0:    * can simply set continueWithInsertion to PR_TRUE and return.
michael@0:    *
michael@0:    * Callers who want to modify the content (docFragment) being inserted are 
michael@0:    * responsible for updating contentStartNode, contentStartOffset, 
michael@0:    * contentEndNode, and contentEndOffset (if necessary).  
michael@0:    * Callers are responsible for freeing and addref'ing if they want to 
michael@0:    * completely replace any of the DOM nodes passed in.
michael@0:    *
michael@0:    * The location where insertion will occur should be considered an
michael@0:    * approximation since the editor may need to adjust it if it deletes
michael@0:    * the selection as part of the event and later determines that insertion
michael@0:    * point is an empty container which should also be removed (or in other
michael@0:    * scenarios such as -moz-user-select:none).
michael@0:    *
michael@0:    * In some scenarios the selection will be deleted.  If callers choose
michael@0:    * to adjust the insertion point, they should be careful that the insertion
michael@0:    * point is not in the current selection.
michael@0:    *
michael@0:    * The contentStartNode and contentEndNode are not necessarily
michael@0:    * immediate children of the docFragment.  Any nodes outside of the range
michael@0:    * set by contentStartNode and contentEndNode are for context from the
michael@0:    * source document.
michael@0:    *
michael@0:    * @param mimeType          the mimetype used for retrieving data
michael@0:    * @param contentSourceURL  location where docFragment came from
michael@0:    * @param sourceDocument      document where content came from (can be null)
michael@0:    * @param willDeleteSelection tells hook if selection will/should be deleted
michael@0:    * @param docFragment         fragment of node to be inserted
michael@0:    * @param contentStartNode    node under which content to be inserted begins
michael@0:    * @param contentStartOffset  start offset within contentStartNode
michael@0:    * @param contentEndNode      node under which content to be inserted ends
michael@0:    * @param contentEndOffset    ending offset withing contentEndNode
michael@0:    * @param insertionPointNode     location where insertion will occur
michael@0:    * @param insertionPointOffset   offset within node where insertion occurs
michael@0:    * @param continueWithInsertion  flag to cancel insertion (if desired)
michael@0:    */
michael@0: 
michael@0:   void notifyOfInsertion(in AString mimeType,
michael@0:                          in nsIURL contentSourceURL,
michael@0:                          in nsIDOMDocument sourceDocument,
michael@0:                          in boolean willDeleteSelection,
michael@0:                          inout nsIDOMNode docFragment,
michael@0:                          inout nsIDOMNode contentStartNode,
michael@0:                          inout long contentStartOffset,
michael@0:                          inout nsIDOMNode contentEndNode,
michael@0:                          inout long contentEndOffset,
michael@0:                          inout nsIDOMNode insertionPointNode,
michael@0:                          inout long insertionPointOffset,
michael@0:                          out boolean continueWithInsertion);
michael@0: 
michael@0: };