content/base/public/nsISelection.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 /* THIS IS A PUBLIC INTERFACE */
  41
  42 interface nsIDOMNode;
  43 interface nsIDOMRange;
  44
  45 /**
  46  * Interface for manipulating and querying the current selected range
  47  * of nodes within the document.
  48  *
  49  * @status FROZEN
  50  * @version 1.0
  51  */
  52
  53 [scriptable, uuid(B2C7ED59-8634-4352-9E37-5484C8B6E4E1)]
  54 interface nsISelection : nsISupports
  55 {
  56     /**
  57      * Returns the node in which the selection begins.
  58      */
  59     readonly attribute nsIDOMNode anchorNode;
  60
  61     /**
  62      * The offset within the (text) node where the selection begins.
  63      */
  64     readonly attribute long anchorOffset;
  65
  66     /**
  67      * Returns the node in which the selection ends.
  68      */
  69     readonly attribute nsIDOMNode focusNode;
  70
  71     /**
  72      * The offset within the (text) node where the selection ends.
  73      */
  74     readonly attribute long focusOffset;
  75
  76     /**
  77      * Indicates if the selection is collapsed or not.
  78      */
  79     readonly attribute boolean isCollapsed;
  80
  81     /**
  82      * Returns the number of ranges in the selection.
  83      */
  84     readonly attribute long rangeCount;
  85
  86     /**
  87      * Returns the range at the specified index.
  88      */
  89     nsIDOMRange getRangeAt(in long index);
  90
  91     /**
  92      * Collapses the selection to a single point, at the specified offset
  93      * in the given DOM node. When the selection is collapsed, and the content
  94      * is focused and editable, the caret will blink there.
  95      * @param parentNode      The given dom node where the selection will be set
  96      * @param offset          Where in given dom node to place the selection (the offset into the given node)
  97      */
  98     void collapse(in nsIDOMNode parentNode, in long offset);
  99
 100
 101     /**
 102      * Extends the selection by moving the selection end to the specified node and offset,
 103      * preserving the selection begin position. The new selection end result will always
 104      * be from the anchorNode to the new focusNode, regardless of direction.
 105      * @param parentNode      The node where the selection will be extended to
 106      * @param offset          Where in node to place the offset in the new selection end
 107      */
 108     void extend(in nsIDOMNode parentNode, in long offset);
 109
 110     /**
 111      * Collapses the whole selection to a single point at the start
 112      * of the current selection (irrespective of direction).  If content
 113      * is focused and editable, the caret will blink there.
 114      */
 115     void collapseToStart();
 116
 117     /**
 118      * Collapses the whole selection to a single point at the end
 119      * of the current selection (irrespective of direction).  If content
 120      * is focused and editable, the caret will blink there.
 121      */
 122     void collapseToEnd();
 123
 124     /**
 125      * Indicates whether the node is part of the selection. If partlyContained
 126      * is set to PR_TRUE, the function returns true when some part of the node
 127      * is part of the selection. If partlyContained is set to PR_FALSE, the
 128      * function only returns true when the entire node is part of the selection.
 129      */
 130     boolean containsNode(in nsIDOMNode node, in boolean partlyContained);
 131
 132     /**
 133      * Adds all children of the specified node to the selection.
 134      * @param parentNode  the parent of the children to be added to the selection.
 135      */
 136     void selectAllChildren(in nsIDOMNode parentNode);
 137
 138     /**
 139      * Adds a range to the current selection.
 140      */
 141     void addRange(in nsIDOMRange range);
 142
 143     /**
 144      * Removes a range from the current selection.
 145      */
 146     void removeRange(in nsIDOMRange range);
 147
 148     /**
 149      * Removes all ranges from the current selection.
 150      */
 151     void removeAllRanges();
 152
 153     /**
 154      * Deletes this selection from document the nodes belong to.
 155      */
 156     void deleteFromDocument();
 157
 158     /**
 159      * Modifies the cursor Bidi level after a change in keyboard direction
 160      * @param langRTL is PR_TRUE if the new language is right-to-left or
 161      *                PR_FALSE if the new language is left-to-right.
 162      */
 163     void selectionLanguageChange(in boolean langRTL);
 164
 165     /**
 166      * Returns the whole selection into a plain text string.
 167      */
 168     wstring toString();
 169 };