Debian Codegraph @

closure-library/closure/goog/dom/range.js

raw
1 // Copyright 2007 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Utilities for working with ranges in HTML documents.
17 *
18 * @author [email protected] (Robby Walker)
19 */
20
21 goog.provide('goog.dom.Range');
22
23 goog.require('goog.dom');
24 goog.require('goog.dom.AbstractRange');
25 goog.require('goog.dom.BrowserFeature');
26 goog.require('goog.dom.ControlRange');
27 goog.require('goog.dom.MultiRange');
28 goog.require('goog.dom.NodeType');
29 goog.require('goog.dom.TextRange');
30
31
32 /**
33 * Create a new selection from the given browser window's current selection.
34 * Note that this object does not auto-update if the user changes their
35 * selection and should be used as a snapshot.
36 * @param {Window=} opt_win The window to get the selection of. Defaults to the
37 * window this class was defined in.
38 * @return {goog.dom.AbstractRange?} A range wrapper object, or null if there
39 * was an error.
40 */
41 goog.dom.Range.createFromWindow = function(opt_win) {
42 var sel =
43 goog.dom.AbstractRange.getBrowserSelectionForWindow(opt_win || window);
44 return sel && goog.dom.Range.createFromBrowserSelection(sel);
45 };
46
47
48 /**
49 * Create a new range wrapper from the given browser selection object. Note
50 * that this object does not auto-update if the user changes their selection and
51 * should be used as a snapshot.
52 * @param {!Object} selection The browser selection object.
53 * @return {goog.dom.AbstractRange?} A range wrapper object or null if there
54 * was an error.
55 */
56 goog.dom.Range.createFromBrowserSelection = function(selection) {
57 var range;
58 var isReversed = false;
59 if (selection.createRange) {
60
61 try {
62 range = selection.createRange();
63 } catch (e) {
64 // Access denied errors can be thrown here in IE if the selection was
65 // a flash obj or if there are cross domain issues
66 return null;
67 }
68 } else if (selection.rangeCount) {
69 if (selection.rangeCount > 1) {
70 return goog.dom.MultiRange.createFromBrowserSelection(
71 /** @type {!Selection} */ (selection));
72 } else {
73 range = selection.getRangeAt(0);
74 isReversed = goog.dom.Range.isReversed(
75 selection.anchorNode, selection.anchorOffset, selection.focusNode,
76 selection.focusOffset);
77 }
78 } else {
79 return null;
80 }
81
82 return goog.dom.Range.createFromBrowserRange(range, isReversed);
83 };
84
85
86 /**
87 * Create a new range wrapper from the given browser range object.
88 * @param {Range|TextRange} range The browser range object.
89 * @param {boolean=} opt_isReversed Whether the focus node is before the anchor
90 * node.
91 * @return {!goog.dom.AbstractRange} A range wrapper object.
92 */
93 goog.dom.Range.createFromBrowserRange = function(range, opt_isReversed) {
94 // Create an IE control range when appropriate.
95 return goog.dom.AbstractRange.isNativeControlRange(range) ?
96 goog.dom.ControlRange.createFromBrowserRange(range) :
97 goog.dom.TextRange.createFromBrowserRange(range, opt_isReversed);
98 };
99
100
101 /**
102 * Create a new range wrapper that selects the given node's text.
103 * @param {Node} node The node to select.
104 * @param {boolean=} opt_isReversed Whether the focus node is before the anchor
105 * node.
106 * @return {!goog.dom.AbstractRange} A range wrapper object.
107 */
108 goog.dom.Range.createFromNodeContents = function(node, opt_isReversed) {
109 return goog.dom.TextRange.createFromNodeContents(node, opt_isReversed);
110 };
111
112
113 /**
114 * Create a new range wrapper that represents a caret at the given node,
115 * accounting for the given offset. This always creates a TextRange, regardless
116 * of whether node is an image node or other control range type node.
117 * @param {Node} node The node to place a caret at.
118 * @param {number} offset The offset within the node to place the caret at.
119 * @return {!goog.dom.AbstractRange} A range wrapper object.
120 */
121 goog.dom.Range.createCaret = function(node, offset) {
122 return goog.dom.TextRange.createFromNodes(node, offset, node, offset);
123 };
124
125
126 /**
127 * Create a new range wrapper that selects the area between the given nodes,
128 * accounting for the given offsets.
129 * @param {Node} anchorNode The node to anchor on.
130 * @param {number} anchorOffset The offset within the node to anchor on.
131 * @param {Node} focusNode The node to focus on.
132 * @param {number} focusOffset The offset within the node to focus on.
133 * @return {!goog.dom.AbstractRange} A range wrapper object.
134 */
135 goog.dom.Range.createFromNodes = function(
136 anchorNode, anchorOffset, focusNode, focusOffset) {
137 return goog.dom.TextRange.createFromNodes(
138 anchorNode, anchorOffset, focusNode, focusOffset);
139 };
140
141
142 /**
143 * Clears the window's selection.
144 * @param {Window=} opt_win The window to get the selection of. Defaults to the
145 * window this class was defined in.
146 */
147 goog.dom.Range.clearSelection = function(opt_win) {
148 var sel =
149 goog.dom.AbstractRange.getBrowserSelectionForWindow(opt_win || window);
150 if (!sel) {
151 return;
152 }
153 if (sel.empty) {
154 // We can't just check that the selection is empty, because IE
155 // sometimes gets confused.
156 try {
157 sel.empty();
158 } catch (e) {
159 // Emptying an already empty selection throws an exception in IE
160 }
161 } else {
162 try {
163 sel.removeAllRanges();
164 } catch (e) {
165 // This throws in IE9 if the range has been invalidated; for example, if
166 // the user clicked on an element which disappeared during the event
167 // handler.
168 }
169 }
170 };
171
172
173 /**
174 * Tests if the window has a selection.
175 * @param {Window=} opt_win The window to check the selection of. Defaults to
176 * the window this class was defined in.
177 * @return {boolean} Whether the window has a selection.
178 */
179 goog.dom.Range.hasSelection = function(opt_win) {
180 var sel =
181 goog.dom.AbstractRange.getBrowserSelectionForWindow(opt_win || window);
182 return !!sel &&
183 (goog.dom.BrowserFeature.LEGACY_IE_RANGES ? sel.type != 'None' :
184 !!sel.rangeCount);
185 };
186
187
188 /**
189 * Returns whether the focus position occurs before the anchor position.
190 * @param {Node} anchorNode The node to anchor on.
191 * @param {number} anchorOffset The offset within the node to anchor on.
192 * @param {Node} focusNode The node to focus on.
193 * @param {number} focusOffset The offset within the node to focus on.
194 * @return {boolean} Whether the focus position occurs before the anchor
195 * position.
196 */
197 goog.dom.Range.isReversed = function(
198 anchorNode, anchorOffset, focusNode, focusOffset) {
199 if (anchorNode == focusNode) {
200 return focusOffset < anchorOffset;
201 }
202 var child;
203 if (anchorNode.nodeType == goog.dom.NodeType.ELEMENT && anchorOffset) {
204 child = anchorNode.childNodes[anchorOffset];
205 if (child) {
206 anchorNode = child;
207 anchorOffset = 0;
208 } else if (goog.dom.contains(anchorNode, focusNode)) {
209 // If focus node is contained in anchorNode, it must be before the
210 // end of the node. Hence we are reversed.
211 return true;
212 }
213 }
214 if (focusNode.nodeType == goog.dom.NodeType.ELEMENT && focusOffset) {
215 child = focusNode.childNodes[focusOffset];
216 if (child) {
217 focusNode = child;
218 focusOffset = 0;
219 } else if (goog.dom.contains(focusNode, anchorNode)) {
220 // If anchor node is contained in focusNode, it must be before the
221 // end of the node. Hence we are not reversed.
222 return false;
223 }
224 }
225 return (goog.dom.compareNodeOrder(anchorNode, focusNode) ||
226 anchorOffset - focusOffset) > 0;
227 };