michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: /* THIS IS A PUBLIC INTERFACE */ michael@0: michael@0: interface nsIDOMNode; michael@0: interface nsIDOMRange; michael@0: interface nsINode; michael@0: michael@0: /** michael@0: * Interface for manipulating and querying the current selected range michael@0: * of nodes within the document. michael@0: * michael@0: * @version 1.0 michael@0: */ michael@0: michael@0: [scriptable, builtinclass, uuid(e0a4d4b3-f34e-44bd-b1f2-4e3bde9b6915)] michael@0: interface nsISelection : nsISupports michael@0: { michael@0: /** michael@0: * Returns the node in which the selection begins. michael@0: */ michael@0: readonly attribute nsIDOMNode anchorNode; michael@0: michael@0: /** michael@0: * The offset within the (text) node where the selection begins. michael@0: */ michael@0: readonly attribute long anchorOffset; michael@0: michael@0: /** michael@0: * Returns the node in which the selection ends. michael@0: */ michael@0: readonly attribute nsIDOMNode focusNode; michael@0: michael@0: /** michael@0: * The offset within the (text) node where the selection ends. michael@0: */ michael@0: readonly attribute long focusOffset; michael@0: michael@0: /** michael@0: * Indicates if the selection is collapsed or not. michael@0: */ michael@0: readonly attribute boolean isCollapsed; michael@0: [noscript,notxpcom,nostdcall] boolean collapsed(); michael@0: michael@0: /** michael@0: * Returns the number of ranges in the selection. michael@0: */ michael@0: readonly attribute long rangeCount; michael@0: michael@0: /** michael@0: * Returns the range at the specified index. michael@0: */ michael@0: nsIDOMRange getRangeAt(in long index); michael@0: michael@0: /** michael@0: * Collapses the selection to a single point, at the specified offset michael@0: * in the given DOM node. When the selection is collapsed, and the content michael@0: * is focused and editable, the caret will blink there. michael@0: * @param parentNode The given dom node where the selection will be set michael@0: * @param offset Where in given dom node to place the selection (the offset into the given node) michael@0: */ michael@0: void collapse(in nsIDOMNode parentNode, in long offset); michael@0: [noscript] void collapseNative(in nsINode parentNode, in long offset); michael@0: michael@0: /** michael@0: * Extends the selection by moving the selection end to the specified node and offset, michael@0: * preserving the selection begin position. The new selection end result will always michael@0: * be from the anchorNode to the new focusNode, regardless of direction. michael@0: * @param parentNode The node where the selection will be extended to michael@0: * @param offset Where in node to place the offset in the new selection end michael@0: */ michael@0: void extend(in nsIDOMNode parentNode, in long offset); michael@0: [noscript] void extendNative(in nsINode parentNode, in long offset); michael@0: michael@0: /** michael@0: * Collapses the whole selection to a single point at the start michael@0: * of the current selection (irrespective of direction). If content michael@0: * is focused and editable, the caret will blink there. michael@0: */ michael@0: void collapseToStart(); michael@0: michael@0: /** michael@0: * Collapses the whole selection to a single point at the end michael@0: * of the current selection (irrespective of direction). If content michael@0: * is focused and editable, the caret will blink there. michael@0: */ michael@0: void collapseToEnd(); michael@0: michael@0: /** michael@0: * Indicates whether the node is part of the selection. If partlyContained michael@0: * is set to PR_TRUE, the function returns true when some part of the node michael@0: * is part of the selection. If partlyContained is set to PR_FALSE, the michael@0: * function only returns true when the entire node is part of the selection. michael@0: */ michael@0: boolean containsNode(in nsIDOMNode node, in boolean partlyContained); michael@0: michael@0: /** michael@0: * Adds all children of the specified node to the selection. michael@0: * @param parentNode the parent of the children to be added to the selection. michael@0: */ michael@0: void selectAllChildren(in nsIDOMNode parentNode); michael@0: michael@0: /** michael@0: * Adds a range to the current selection. michael@0: */ michael@0: void addRange(in nsIDOMRange range); michael@0: michael@0: /** michael@0: * Removes a range from the current selection. michael@0: */ michael@0: void removeRange(in nsIDOMRange range); michael@0: michael@0: /** michael@0: * Removes all ranges from the current selection. michael@0: */ michael@0: void removeAllRanges(); michael@0: michael@0: /** michael@0: * Deletes this selection from document the nodes belong to. michael@0: */ michael@0: void deleteFromDocument(); michael@0: michael@0: /** michael@0: * Returns the whole selection into a plain text string. michael@0: */ michael@0: DOMString toString(); michael@0: michael@0: /** michael@0: * Modifies the selection. Note that the parameters are case-insensitive. michael@0: * michael@0: * @param alter can be one of { "move", "extend" } michael@0: * - "move" collapses the selection to the end of the selection and michael@0: * applies the movement direction/granularity to the collapsed michael@0: * selection. michael@0: * - "extend" leaves the start of the selection unchanged, and applies michael@0: * movement direction/granularity to the end of the selection. michael@0: * @param direction can be one of { "forward", "backward", "left", "right" } michael@0: * @param granularity can be one of { "character", "word", michael@0: * "line", "lineboundary" } michael@0: * michael@0: * @returns NS_ERROR_NOT_IMPLEMENTED if the granularity is "sentence", michael@0: * "sentenceboundary", "paragraph", "paragraphboundary", or michael@0: * "documentboundary". Returns NS_ERROR_INVALID_ARG if alter, direction, michael@0: * or granularity has an unrecognized value. michael@0: */ michael@0: void modify(in DOMString alter, in DOMString direction, michael@0: in DOMString granularity); michael@0: };