gecko/content/base/public/nsISelection.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* 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 "nsISupports.idl"

/* THIS IS A PUBLIC INTERFACE */

interface nsIDOMNode;
interface nsIDOMRange;
interface nsINode;

/**
 * Interface for manipulating and querying the current selected range
 * of nodes within the document.
 *
 * @version 1.0
 */

[scriptable, uuid(12cf5a4d-fffb-4f2f-9cec-c65195661d76)]
interface nsISelection : nsISupports
{
    /**
     * Returns the node in which the selection begins.
     */
    readonly attribute nsIDOMNode anchorNode;

    /**
     * The offset within the (text) node where the selection begins.
     */
    readonly attribute long anchorOffset;

    /**
     * Returns the node in which the selection ends.
     */
    readonly attribute nsIDOMNode focusNode;

    /**
     * The offset within the (text) node where the selection ends.
     */
    readonly attribute long focusOffset;

    /**
     * Indicates if the selection is collapsed or not.
     */
    readonly attribute boolean isCollapsed;
    [noscript,notxpcom,nostdcall] boolean collapsed();

    /**
     * Returns the number of ranges in the selection.
     */
    readonly attribute long rangeCount;

    /**
     * Returns the range at the specified index.
     */
    nsIDOMRange getRangeAt(in long index);

    /**
     * Collapses the selection to a single point, at the specified offset
     * in the given DOM node. When the selection is collapsed, and the content
     * is focused and editable, the caret will blink there.
     * @param parentNode      The given dom node where the selection will be set
     * @param offset          Where in given dom node to place the selection (the offset into the given node)
     */
    void collapse(in nsIDOMNode parentNode, in long offset);
    [noscript] void collapseNative(in nsINode parentNode, in long offset);

    /**
     * Extends the selection by moving the selection end to the specified node and offset,
     * preserving the selection begin position. The new selection end result will always
     * be from the anchorNode to the new focusNode, regardless of direction.
     * @param parentNode      The node where the selection will be extended to
     * @param offset          Where in node to place the offset in the new selection end
     */
    void extend(in nsIDOMNode parentNode, in long offset);
    [noscript] void extendNative(in nsINode parentNode, in long offset);

    /**
     * Collapses the whole selection to a single point at the start
     * of the current selection (irrespective of direction).  If content
     * is focused and editable, the caret will blink there.
     */
    void collapseToStart();

    /**
     * Collapses the whole selection to a single point at the end
     * of the current selection (irrespective of direction).  If content
     * is focused and editable, the caret will blink there.
     */
    void collapseToEnd();

    /**
     * Indicates whether the node is part of the selection. If partlyContained 
     * is set to PR_TRUE, the function returns true when some part of the node 
     * is part of the selection. If partlyContained is set to PR_FALSE, the
     * function only returns true when the entire node is part of the selection.
     */
    boolean containsNode(in nsIDOMNode node, in boolean partlyContained);

    /**
     * Adds all children of the specified node to the selection.
     * @param parentNode  the parent of the children to be added to the selection.
     */
    void selectAllChildren(in nsIDOMNode parentNode); 

    /**
     * Adds a range to the current selection.
     */
    void addRange(in nsIDOMRange range);
 
    /**
     * Removes a range from the current selection.
     */
    void removeRange(in nsIDOMRange range);

    /**
     * Removes all ranges from the current selection.
     */
    void removeAllRanges();

    /**
     * Deletes this selection from document the nodes belong to.
     */
    void deleteFromDocument();

    /**
     * Modifies the cursor Bidi level after a change in keyboard direction
     * @param langRTL is PR_TRUE if the new language is right-to-left or
     *                PR_FALSE if the new language is left-to-right.
     */
    void selectionLanguageChange(in boolean langRTL);

    /**
     * Returns the whole selection into a plain text string.
     */
    DOMString toString();

    /**
     * Modifies the selection.  Note that the parameters are case-insensitive.
     *
     * @param alter can be one of { "move", "extend" }
     *   - "move" collapses the selection to the end of the selection and
     *      applies the movement direction/granularity to the collapsed
     *      selection.
     *   - "extend" leaves the start of the selection unchanged, and applies
     *      movement direction/granularity to the end of the selection.
     * @param direction can be one of { "forward", "backward", "left", "right" }
     * @param granularity can be one of { "character", "word",
     *                                    "line", "lineboundary" }
     *
     * @returns NS_ERROR_NOT_IMPLEMENTED if the granularity is "sentence",
     * "sentenceboundary", "paragraph", "paragraphboundary", or
     * "documentboundary".  Returns NS_ERROR_INVALID_ARG if alter, direction,
     * or granularity has an unrecognized value.
     */
    void modify(in DOMString alter, in DOMString direction,
                in DOMString granularity);
};