1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/base/public/nsISelection.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,153 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +/* THIS IS A PUBLIC INTERFACE */
1.12 +
1.13 +interface nsIDOMNode;
1.14 +interface nsIDOMRange;
1.15 +interface nsINode;
1.16 +
1.17 +/**
1.18 + * Interface for manipulating and querying the current selected range
1.19 + * of nodes within the document.
1.20 + *
1.21 + * @version 1.0
1.22 + */
1.23 +
1.24 +[scriptable, builtinclass, uuid(e0a4d4b3-f34e-44bd-b1f2-4e3bde9b6915)]
1.25 +interface nsISelection : nsISupports
1.26 +{
1.27 + /**
1.28 + * Returns the node in which the selection begins.
1.29 + */
1.30 + readonly attribute nsIDOMNode anchorNode;
1.31 +
1.32 + /**
1.33 + * The offset within the (text) node where the selection begins.
1.34 + */
1.35 + readonly attribute long anchorOffset;
1.36 +
1.37 + /**
1.38 + * Returns the node in which the selection ends.
1.39 + */
1.40 + readonly attribute nsIDOMNode focusNode;
1.41 +
1.42 + /**
1.43 + * The offset within the (text) node where the selection ends.
1.44 + */
1.45 + readonly attribute long focusOffset;
1.46 +
1.47 + /**
1.48 + * Indicates if the selection is collapsed or not.
1.49 + */
1.50 + readonly attribute boolean isCollapsed;
1.51 + [noscript,notxpcom,nostdcall] boolean collapsed();
1.52 +
1.53 + /**
1.54 + * Returns the number of ranges in the selection.
1.55 + */
1.56 + readonly attribute long rangeCount;
1.57 +
1.58 + /**
1.59 + * Returns the range at the specified index.
1.60 + */
1.61 + nsIDOMRange getRangeAt(in long index);
1.62 +
1.63 + /**
1.64 + * Collapses the selection to a single point, at the specified offset
1.65 + * in the given DOM node. When the selection is collapsed, and the content
1.66 + * is focused and editable, the caret will blink there.
1.67 + * @param parentNode The given dom node where the selection will be set
1.68 + * @param offset Where in given dom node to place the selection (the offset into the given node)
1.69 + */
1.70 + void collapse(in nsIDOMNode parentNode, in long offset);
1.71 + [noscript] void collapseNative(in nsINode parentNode, in long offset);
1.72 +
1.73 + /**
1.74 + * Extends the selection by moving the selection end to the specified node and offset,
1.75 + * preserving the selection begin position. The new selection end result will always
1.76 + * be from the anchorNode to the new focusNode, regardless of direction.
1.77 + * @param parentNode The node where the selection will be extended to
1.78 + * @param offset Where in node to place the offset in the new selection end
1.79 + */
1.80 + void extend(in nsIDOMNode parentNode, in long offset);
1.81 + [noscript] void extendNative(in nsINode parentNode, in long offset);
1.82 +
1.83 + /**
1.84 + * Collapses the whole selection to a single point at the start
1.85 + * of the current selection (irrespective of direction). If content
1.86 + * is focused and editable, the caret will blink there.
1.87 + */
1.88 + void collapseToStart();
1.89 +
1.90 + /**
1.91 + * Collapses the whole selection to a single point at the end
1.92 + * of the current selection (irrespective of direction). If content
1.93 + * is focused and editable, the caret will blink there.
1.94 + */
1.95 + void collapseToEnd();
1.96 +
1.97 + /**
1.98 + * Indicates whether the node is part of the selection. If partlyContained
1.99 + * is set to PR_TRUE, the function returns true when some part of the node
1.100 + * is part of the selection. If partlyContained is set to PR_FALSE, the
1.101 + * function only returns true when the entire node is part of the selection.
1.102 + */
1.103 + boolean containsNode(in nsIDOMNode node, in boolean partlyContained);
1.104 +
1.105 + /**
1.106 + * Adds all children of the specified node to the selection.
1.107 + * @param parentNode the parent of the children to be added to the selection.
1.108 + */
1.109 + void selectAllChildren(in nsIDOMNode parentNode);
1.110 +
1.111 + /**
1.112 + * Adds a range to the current selection.
1.113 + */
1.114 + void addRange(in nsIDOMRange range);
1.115 +
1.116 + /**
1.117 + * Removes a range from the current selection.
1.118 + */
1.119 + void removeRange(in nsIDOMRange range);
1.120 +
1.121 + /**
1.122 + * Removes all ranges from the current selection.
1.123 + */
1.124 + void removeAllRanges();
1.125 +
1.126 + /**
1.127 + * Deletes this selection from document the nodes belong to.
1.128 + */
1.129 + void deleteFromDocument();
1.130 +
1.131 + /**
1.132 + * Returns the whole selection into a plain text string.
1.133 + */
1.134 + DOMString toString();
1.135 +
1.136 + /**
1.137 + * Modifies the selection. Note that the parameters are case-insensitive.
1.138 + *
1.139 + * @param alter can be one of { "move", "extend" }
1.140 + * - "move" collapses the selection to the end of the selection and
1.141 + * applies the movement direction/granularity to the collapsed
1.142 + * selection.
1.143 + * - "extend" leaves the start of the selection unchanged, and applies
1.144 + * movement direction/granularity to the end of the selection.
1.145 + * @param direction can be one of { "forward", "backward", "left", "right" }
1.146 + * @param granularity can be one of { "character", "word",
1.147 + * "line", "lineboundary" }
1.148 + *
1.149 + * @returns NS_ERROR_NOT_IMPLEMENTED if the granularity is "sentence",
1.150 + * "sentenceboundary", "paragraph", "paragraphboundary", or
1.151 + * "documentboundary". Returns NS_ERROR_INVALID_ARG if alter, direction,
1.152 + * or granularity has an unrecognized value.
1.153 + */
1.154 + void modify(in DOMString alter, in DOMString direction,
1.155 + in DOMString granularity);
1.156 +};
