dom/base/nsISelection.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 /* THIS IS A PUBLIC INTERFACE */
   9
  10 interface nsIDOMNode;
  11 interface nsIDOMRange;
  12 interface nsINode;
  13
  14 /**
  15  * Interface for manipulating and querying the current selected range
  16  * of nodes within the document.
  17  *
  18  * @version 1.0
  19  */
  20
  21 [builtinclass, uuid(e0a4d4b3-f34e-44bd-b1f2-4e3bde9b6915)]
  22 interface nsISelection : nsISupports
  23 {
  24     /**
  25      * Returns the node in which the selection begins.
  26      */
  27     readonly attribute nsIDOMNode anchorNode;
  28
  29     /**
  30      * The offset within the (text) node where the selection begins.
  31      */
  32     readonly attribute long anchorOffset;
  33
  34     /**
  35      * Returns the node in which the selection ends.
  36      */
  37     readonly attribute nsIDOMNode focusNode;
  38
  39     /**
  40      * The offset within the (text) node where the selection ends.
  41      */
  42     readonly attribute long focusOffset;
  43
  44     /**
  45      * Indicates if the selection is collapsed or not.
  46      */
  47     readonly attribute boolean isCollapsed;
  48     [noscript,notxpcom,nostdcall] boolean collapsed();
  49
  50     /**
  51      * Returns the number of ranges in the selection.
  52      */
  53     readonly attribute long rangeCount;
  54
  55     /**
  56      * Returns the range at the specified index.
  57      */
  58     nsIDOMRange getRangeAt(in long index);
  59
  60     /**
  61      * Collapses the selection to a single point, at the specified offset
  62      * in the given DOM node. When the selection is collapsed, and the content
  63      * is focused and editable, the caret will blink there.
  64      * @param parentNode      The given dom node where the selection will be set
  65      * @param offset          Where in given dom node to place the selection (the offset into the given node)
  66      */
  67     void collapse(in nsIDOMNode parentNode, in long offset);
  68     [noscript] void collapseNative(in nsINode parentNode, in long offset);
  69
  70     /**
  71      * Extends the selection by moving the selection end to the specified node and offset,
  72      * preserving the selection begin position. The new selection end result will always
  73      * be from the anchorNode to the new focusNode, regardless of direction.
  74      * @param parentNode      The node where the selection will be extended to
  75      * @param offset          Where in node to place the offset in the new selection end
  76      */
  77     void extend(in nsIDOMNode parentNode, in long offset);
  78     [noscript] void extendNative(in nsINode parentNode, in long offset);
  79
  80     /**
  81      * Collapses the whole selection to a single point at the start
  82      * of the current selection (irrespective of direction).  If content
  83      * is focused and editable, the caret will blink there.
  84      */
  85     void collapseToStart();
  86
  87     /**
  88      * Collapses the whole selection to a single point at the end
  89      * of the current selection (irrespective of direction).  If content
  90      * is focused and editable, the caret will blink there.
  91      */
  92     void collapseToEnd();
  93
  94     /**
  95      * Indicates whether the node is part of the selection. If partlyContained
  96      * is set to PR_TRUE, the function returns true when some part of the node
  97      * is part of the selection. If partlyContained is set to PR_FALSE, the
  98      * function only returns true when the entire node is part of the selection.
  99      */
 100     boolean containsNode(in nsIDOMNode node, in boolean partlyContained);
 101
 102     /**
 103      * Adds all children of the specified node to the selection.
 104      * @param parentNode  the parent of the children to be added to the selection.
 105      */
 106     void selectAllChildren(in nsIDOMNode parentNode);
 107
 108     /**
 109      * Adds a range to the current selection.
 110      */
 111     void addRange(in nsIDOMRange range);
 112
 113     /**
 114      * Removes a range from the current selection.
 115      */
 116     void removeRange(in nsIDOMRange range);
 117
 118     /**
 119      * Removes all ranges from the current selection.
 120      */
 121     void removeAllRanges();
 122
 123     /**
 124      * Deletes this selection from document the nodes belong to.
 125      */
 126     void deleteFromDocument();
 127
 128     /**
 129      * Returns the whole selection into a plain text string.
 130      */
 131     DOMString toString();
 132
 133     /**
 134      * Modifies the selection.  Note that the parameters are case-insensitive.
 135      *
 136      * @param alter can be one of { "move", "extend" }
 137      *   - "move" collapses the selection to the end of the selection and
 138      *      applies the movement direction/granularity to the collapsed
 139      *      selection.
 140      *   - "extend" leaves the start of the selection unchanged, and applies
 141      *      movement direction/granularity to the end of the selection.
 142      * @param direction can be one of { "forward", "backward", "left", "right" }
 143      * @param granularity can be one of { "character", "word",
 144      *                                    "line", "lineboundary" }
 145      *
 146      * @returns NS_ERROR_NOT_IMPLEMENTED if the granularity is "sentence",
 147      * "sentenceboundary", "paragraph", "paragraphboundary", or
 148      * "documentboundary".  Returns NS_ERROR_INVALID_ARG if alter, direction,
 149      * or granularity has an unrecognized value.
 150      */
 151     void modify(in DOMString alter, in DOMString direction,
 152                 in DOMString granularity);
 153 };