/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is 
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2000
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Vidur Apparao <vidur@netscape.com> (original author)
 *   Johnny Stenback <jst@netscape.com>
 *
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the NPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/*
 * The complete Range spec is located at:
 * http://www.w3.org/TR/DOM-Level-2-Traversal-Range/ranges.html
 */
#include "domstubs.idl"
[scriptable, uuid(a6cf90ce-15b3-11d2-932e-00805f8add32)]
interface nsIDOMRange : nsISupports
{
  /**
   * CompareHow group
   * Passed as a parameter to the compareBoundaryPoints method.
   */
    const unsigned short START_TO_START = 0;// Compare start boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked
    const unsigned short START_TO_END = 1;  // Compare start boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked
    const unsigned short END_TO_START = 2;  // Compare end boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked
    const unsigned short END_TO_END = 3;    // Compare end boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked

    readonly attribute nsIDOMNode startContainer;// Node within which the Range begins
    readonly attribute long startOffset;         // Offset within the starting node of the Range
    readonly attribute nsIDOMNode endContainer;  // Node within which the Range ends
    readonly attribute long endOffset;           // Offset within the ending node of the Range

    readonly attribute boolean collapsed; // TRUE if the Range is collapsed
    readonly attribute nsIDOMNode commonAncestorContainer; //The deepest common ancestor container of the Range's two boundary-points


    /**
     * Sets the attributes describing the start of the Range. The start 
     * position of a Range is guaranteed to never be after the end position.
     * To enforce this restriction, if the start is set to be at a position
     * after the end, the Range is collapsed to that position
     * @param parent      The Parent Node value. This parameter must not be null. 
     * @param offset      start offset value.
     */
     void setStart(in nsIDOMNode parent, in long offset);

    /**
     * Sets the start position to be before the specified node.
     * @param sibling     Range starts before sibling Node. 
     */
     void setStartBefore(in nsIDOMNode sibling);

    /**
     * Sets the start position to be after the specified node.
     * @param sibling     Range starts after sibling Node. 
     */
     void setStartAfter(in nsIDOMNode sibling);

    /**
     * Sets the attributes describing the end of a Range.  If the
     * end is set to be at a position before the start, the Range
     * is collapsed to that position.
     * @param parent      The Parent Node value. This parameter must not be null. 
     * @param offset      end offset value.
     */
     void setEnd(in nsIDOMNode parent, in long offset);

    /**
     * Sets the end position to be before the specified node
     * @param sibling     Range ends before sibling Node. 
     */
     void setEndBefore(in nsIDOMNode sibling);

    /**
     * Sets the end position to be after the specified node
     * @param sibling     Range ends before sibling Node. 
     */
     void setEndAfter(in nsIDOMNode sibling);
 
    /**
     * Collapse a Range onto one of its boundary-points 
     * @param toStart     If TRUE. collapses the Range onto its start,
     *                    if FALSE, collapses onto its end.
     */
     void collapse(in boolean toStart);
 
    /**
     * Select a node and its contents.  Replaces the 
     * contents of the range with this node.
     * @param n           The Node to select.
     */
     void selectNode(in nsIDOMNode n);

    /**
     * Select the contents within a node.  Replace the 
     * contents of the range with this node's contents.
     * @param n           Node to select from. 
     */
     void selectNodeContents(in nsIDOMNode n);
 
    /**
     * Compare the boundary-points of two Ranges in a document.
     * @param how         parameter from CompareHow group, how the boundary points
     *                    are to be compared. 
     * @param srcRange    the range which will have its boundary points compared. 
     * Return Value:      -1, 0 or 1 depending on whether the corresponding 
     *                    boundary-point of the Range is before, equal to, or after the
     *                    corresponding boundary-point of sourceRange. 
     */
     long  compareBoundaryPoints(in unsigned short how, in nsIDOMRange srcRange);
 
    /**
     * Removes the contents of a Range from the containing document or document
     * fragment without returning a reference to the removed content.
     */
     void deleteContents();
 
    /**
     * Moves the contents of a Range from the containing document or document
     * fragment to a new DocumentFragment. 
     * Return Value:      A DocumentFragment containing the extracted contents. 
     */
     nsIDOMDocumentFragment extractContents();

    /**
     * Duplicates the contents of a Range  
     * Return Value:      A DocumentFragment that contains content equivalent to this Range. 
     */
     nsIDOMDocumentFragment cloneContents();
 
    /**
     * Inserts a node into the Document or DocumentFragment at the start of the Range.
     * If the container is a Text node, this will be split at the start of the Range.
     * Adjacent Text nodes will not be automatically merged.
     * @param n           The node to insert at the start of the Range 
     */
     void insertNode(in nsIDOMNode n);

    /**
     * Reparents the contents of the Range to the given node and inserts
     * the node at the position of the start of the Range. 
     * @param n          The node to surround the contents with.
     */
     void surroundContents(in nsIDOMNode n);
 
    /**
     * Produces a new Range whose boundary-points are equal to the
     * boundary-points of the Range. 
     * Return Value:      The duplicated Range. 
     */
     nsIDOMRange cloneRange();
 
    /**
     * Called to indicate that the Range is no longer in use and that
     * the implementation may relinquish any resources associated with
     * this Range. Subsequent calls to any methods or attribute getters
     * on this Range will result in a DOMException being thrown with an
     * error code of INVALID_STATE_ERR. 
     */
     void detach();
 
    /**
     * Returns the contents of a Range as a string. This string contains
     * only the data characters, not any markup. 
     * Return Value:      The contents of the Range.
     */
     DOMString toString();
};
 

.