Selection.webidl (5941B)
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 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 file, 4 * You can obtain one at http://mozilla.org/MPL/2.0/. 5 * 6 * The origin of this IDL file is 7 * https://w3c.github.io/selection-api/#selection-interface 8 * 9 * Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C 10 * liability, trademark and document use rules apply. 11 */ 12 13 // https://www.w3.org/TR/selection-api/#dom-getcomposedrangesoptions 14 dictionary GetComposedRangesOptions { 15 sequence<ShadowRoot> shadowRoots = []; 16 }; 17 18 [Exposed=Window] 19 interface Selection { 20 [NeedsCallerType] 21 readonly attribute Node? anchorNode; 22 [NeedsCallerType] 23 readonly attribute unsigned long anchorOffset; 24 [NeedsCallerType] 25 readonly attribute Node? focusNode; 26 [NeedsCallerType] 27 readonly attribute unsigned long focusOffset; 28 readonly attribute boolean isCollapsed; 29 [ChromeOnly] 30 readonly attribute boolean areNormalAndCrossShadowBoundaryRangesCollapsed; 31 32 [ChromeOnly] 33 readonly attribute Node? mayCrossShadowBoundaryFocusNode; 34 35 /** 36 * Returns the number of ranges in the selection. 37 */ 38 readonly attribute unsigned long rangeCount; 39 readonly attribute DOMString type; 40 readonly attribute DOMString direction; 41 /** 42 * Returns the range at the specified index. Throws if the index is 43 * out of range. 44 */ 45 [Throws] 46 Range getRangeAt(unsigned long index); 47 /** 48 * Adds a range to the current selection. 49 */ 50 [Throws, BinaryName="addRangeJS"] 51 undefined addRange(Range range); 52 /** 53 * Removes a range from the current selection. 54 */ 55 [Throws, BinaryName="removeRangeAndUnselectFramesAndNotifyListeners"] 56 undefined removeRange(Range range); 57 /** 58 * Removes all ranges from the current selection. 59 */ 60 [Throws] 61 undefined removeAllRanges(); 62 [Throws, BinaryName="RemoveAllRanges"] 63 undefined empty(); 64 65 [Pref="dom.shadowdom.selection_across_boundary_enabled"] 66 sequence<StaticRange> getComposedRanges(optional (ShadowRoot or GetComposedRangesOptions) options = {}, ShadowRoot... shadowRoots); 67 68 [Throws, BinaryName="collapseJS"] 69 undefined collapse(Node? node, optional unsigned long offset = 0); 70 [Throws, BinaryName="collapseJS"] 71 undefined setPosition(Node? node, optional unsigned long offset = 0); 72 [Throws, BinaryName="collapseToStartJS"] 73 undefined collapseToStart(); 74 [Throws, BinaryName="collapseToEndJS"] 75 undefined collapseToEnd(); 76 [Throws, BinaryName="extendJS"] 77 undefined extend(Node node, optional unsigned long offset = 0); 78 [Throws, BinaryName="setBaseAndExtentJS"] 79 undefined setBaseAndExtent(Node anchorNode, 80 unsigned long anchorOffset, 81 Node focusNode, 82 unsigned long focusOffset); 83 [Throws, BinaryName="selectAllChildrenJS"] 84 undefined selectAllChildren(Node node); 85 undefined modify(optional DOMString alter = "", optional DOMString direction = "", 86 optional DOMString granularity = ""); 87 [CEReactions, Throws] 88 undefined deleteFromDocument(); 89 [Throws] 90 boolean containsNode(Node node, 91 optional boolean allowPartialContainment = false); 92 [NeedsCallerType] 93 stringifier DOMString (); 94 }; 95 96 // Additional chrome-only methods. 97 interface nsISelectionListener; 98 partial interface Selection { 99 /** 100 * A true value means "selection after newline"; false means "selection before 101 * newline" when a selection is positioned "between lines". 102 */ 103 [ChromeOnly,Throws, BinaryName=interlinePositionJS] 104 attribute boolean interlinePosition; 105 106 [Throws] 107 attribute short? caretBidiLevel; 108 109 [ChromeOnly,Throws] 110 DOMString toStringWithFormat(DOMString formatType, unsigned long flags, long wrapColumn); 111 [ChromeOnly] 112 undefined addSelectionListener(nsISelectionListener newListener); 113 [ChromeOnly] 114 undefined removeSelectionListener(nsISelectionListener listenerToRemove); 115 116 [ChromeOnly,BinaryName="rawType"] 117 readonly attribute short selectionType; 118 119 /** 120 * Return array of ranges intersecting with the given DOM interval. 121 */ 122 [ChromeOnly,Throws,Pref="dom.testing.selection.GetRangesForInterval"] 123 sequence<Range> GetRangesForInterval(Node beginNode, long beginOffset, Node endNode, long endOffset, 124 boolean allowAdjacent); 125 126 /** 127 * setColors() sets custom colors for the selection. 128 * Currently, this is supported only when the selection type is SELECTION_FIND. 129 * Otherwise, throws an exception. 130 * 131 * @param aForegroundColor The foreground color of the selection. 132 * If this is "currentColor", foreground color 133 * isn't changed by this selection. 134 * @param aBackgroundColor The background color of the selection. 135 * If this is "transparent", background color is 136 * never painted. 137 * @param aAltForegroundColor The alternative foreground color of the 138 * selection. 139 * If aBackgroundColor doesn't have sufficient 140 * contrast with its around or foreground color 141 * if "currentColor" is specified, alternative 142 * colors are used if it have higher contrast. 143 * @param aAltBackgroundColor The alternative background color of the 144 * selection. 145 */ 146 [ChromeOnly,Throws] 147 undefined setColors(DOMString aForegroundColor, DOMString aBackgroundColor, 148 DOMString aAltForegroundColor, DOMString aAltBackgroundColor); 149 150 /** 151 * resetColors() forget the customized colors which were set by setColors(). 152 */ 153 [ChromeOnly] 154 undefined resetColors(); 155 };