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
};
228

229