1
// Copyright 2008 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 IE control ranges.
17
 *
18
 * @author [email protected] (Robby Walker)
19
 */
20

21

22
goog.provide('goog.dom.ControlRange');
23
goog.provide('goog.dom.ControlRangeIterator');
24

25
goog.require('goog.array');
26
goog.require('goog.dom');
27
goog.require('goog.dom.AbstractMultiRange');
28
goog.require('goog.dom.AbstractRange');
29
goog.require('goog.dom.RangeIterator');
30
goog.require('goog.dom.RangeType');
31
goog.require('goog.dom.SavedRange');
32
goog.require('goog.dom.TagWalkType');
33
goog.require('goog.dom.TextRange');
34
goog.require('goog.iter.StopIteration');
35
goog.require('goog.userAgent');
36

37

38

39
/**
40
 * Create a new control selection with no properties.  Do not use this
41
 * constructor: use one of the goog.dom.Range.createFrom* methods instead.
42
 * @constructor
43
 * @extends {goog.dom.AbstractMultiRange}
44
 * @final
45
 */
46
goog.dom.ControlRange = function() {
47
  /**
48
   * The IE control range obejct.
49
   * @private {Object}
50
   */
51
  this.range_ = null;
52

53
  /**
54
   * Cached list of elements.
55
   * @private {Array<Element>}
56
   */
57
  this.elements_ = null;
58

59
  /**
60
   * Cached sorted list of elements.
61
   * @private {Array<Element>}
62
   */
63
  this.sortedElements_ = null;
64
};
65
goog.inherits(goog.dom.ControlRange, goog.dom.AbstractMultiRange);
66

67

68
/**
69
 * Create a new range wrapper from the given browser range object.  Do not use
70
 * this method directly - please use goog.dom.Range.createFrom* instead.
71
 * @param {Object} controlRange The browser range object.
72
 * @return {!goog.dom.ControlRange} A range wrapper object.
73
 */
74
goog.dom.ControlRange.createFromBrowserRange = function(controlRange) {
75
  var range = new goog.dom.ControlRange();
76
  range.range_ = controlRange;
77
  return range;
78
};
79

80

81
/**
82
 * Create a new range wrapper that selects the given element.  Do not use
83
 * this method directly - please use goog.dom.Range.createFrom* instead.
84
 * @param {...Element} var_args The element(s) to select.
85
 * @return {!goog.dom.ControlRange} A range wrapper object.
86
 */
87
goog.dom.ControlRange.createFromElements = function(var_args) {
88
  var range = goog.dom.getOwnerDocument(arguments[0]).body.createControlRange();
89
  for (var i = 0, len = arguments.length; i < len; i++) {
90
    range.addElement(arguments[i]);
91
  }
92
  return goog.dom.ControlRange.createFromBrowserRange(range);
93
};
94

95

96
// Method implementations
97

98

99
/**
100
 * Clear cached values.
101
 * @private
102
 */
103
goog.dom.ControlRange.prototype.clearCachedValues_ = function() {
104
  this.elements_ = null;
105
  this.sortedElements_ = null;
106
};
107

108

109
/** @override */
110
goog.dom.ControlRange.prototype.clone = function() {
111
  return goog.dom.ControlRange.createFromElements.apply(
112
      this, this.getElements());
113
};
114

115

116
/** @override */
117
goog.dom.ControlRange.prototype.getType = function() {
118
  return goog.dom.RangeType.CONTROL;
119
};
120

121

122
/** @override */
123
goog.dom.ControlRange.prototype.getBrowserRangeObject = function() {
124
  return this.range_ || document.body.createControlRange();
125
};
126

127

128
/** @override */
129
goog.dom.ControlRange.prototype.setBrowserRangeObject = function(nativeRange) {
130
  if (!goog.dom.AbstractRange.isNativeControlRange(nativeRange)) {
131
    return false;
132
  }
133
  this.range_ = nativeRange;
134
  return true;
135
};
136

137

138
/** @override */
139
goog.dom.ControlRange.prototype.getTextRangeCount = function() {
140
  return this.range_ ? this.range_.length : 0;
141
};
142

143

144
/** @override */
145
goog.dom.ControlRange.prototype.getTextRange = function(i) {
146
  return goog.dom.TextRange.createFromNodeContents(this.range_.item(i));
147
};
148

149

150
/** @override */
151
goog.dom.ControlRange.prototype.getContainer = function() {
152
  return goog.dom.findCommonAncestor.apply(null, this.getElements());
153
};
154

155

156
/** @override */
157
goog.dom.ControlRange.prototype.getStartNode = function() {
158
  return this.getSortedElements()[0];
159
};
160

161

162
/** @override */
163
goog.dom.ControlRange.prototype.getStartOffset = function() {
164
  return 0;
165
};
166

167

168
/** @override */
169
goog.dom.ControlRange.prototype.getEndNode = function() {
170
  var sorted = this.getSortedElements();
171
  var startsLast = /** @type {Node} */ (goog.array.peek(sorted));
172
  return /** @type {Node} */ (goog.array.find(sorted, function(el) {
173
    return goog.dom.contains(el, startsLast);
174
  }));
175
};
176

177

178
/** @override */
179
goog.dom.ControlRange.prototype.getEndOffset = function() {
180
  return this.getEndNode().childNodes.length;
181
};
182

183

184
// TODO(robbyw): Figure out how to unify getElements with TextRange API.
185
/**
186
 * @return {!Array<Element>} Array of elements in the control range.
187
 */
188
goog.dom.ControlRange.prototype.getElements = function() {
189
  if (!this.elements_) {
190
    this.elements_ = [];
191
    if (this.range_) {
192
      for (var i = 0; i < this.range_.length; i++) {
193
        this.elements_.push(this.range_.item(i));
194
      }
195
    }
196
  }
197

198
  return this.elements_;
199
};
200

201

202
/**
203
 * @return {!Array<Element>} Array of elements comprising the control range,
204
 *     sorted by document order.
205
 */
206
goog.dom.ControlRange.prototype.getSortedElements = function() {
207
  if (!this.sortedElements_) {
208
    this.sortedElements_ = this.getElements().concat();
209
    this.sortedElements_.sort(function(a, b) {
210
      return a.sourceIndex - b.sourceIndex;
211
    });
212
  }
213

214
  return this.sortedElements_;
215
};
216

217

218
/** @override */
219
goog.dom.ControlRange.prototype.isRangeInDocument = function() {
220
  var returnValue = false;
221

222
  try {
223
    returnValue = goog.array.every(this.getElements(), function(element) {
224
      // On IE, this throws an exception when the range is detached.
225
      return goog.userAgent.IE ?
226
          !!element.parentNode :
227
          goog.dom.contains(element.ownerDocument.body, element);
228
    });
229
  } catch (e) {
230
    // IE sometimes throws Invalid Argument errors for detached elements.
231
    // Note: trying to return a value from the above try block can cause IE
232
    // to crash.  It is necessary to use the local returnValue.
233
  }
234

235
  return returnValue;
236
};
237

238

239
/** @override */
240
goog.dom.ControlRange.prototype.isCollapsed = function() {
241
  return !this.range_ || !this.range_.length;
242
};
243

244

245
/** @override */
246
goog.dom.ControlRange.prototype.getText = function() {
247
  // TODO(robbyw): What about for table selections?  Should those have text?
248
  return '';
249
};
250

251

252
/** @override */
253
goog.dom.ControlRange.prototype.getHtmlFragment = function() {
254
  return goog.array.map(this.getSortedElements(), goog.dom.getOuterHtml)
255
      .join('');
256
};
257

258

259
/** @override */
260
goog.dom.ControlRange.prototype.getValidHtml = function() {
261
  return this.getHtmlFragment();
262
};
263

264

265
/** @override */
266
goog.dom.ControlRange.prototype.getPastableHtml =
267
    goog.dom.ControlRange.prototype.getValidHtml;
268

269

270
/** @override */
271
goog.dom.ControlRange.prototype.__iterator__ = function(opt_keys) {
272
  return new goog.dom.ControlRangeIterator(this);
273
};
274

275

276
// RANGE ACTIONS
277

278

279
/** @override */
280
goog.dom.ControlRange.prototype.select = function() {
281
  if (this.range_) {
282
    this.range_.select();
283
  }
284
};
285

286

287
/** @override */
288
goog.dom.ControlRange.prototype.removeContents = function() {
289
  // TODO(robbyw): Test implementing with execCommand('Delete')
290
  if (this.range_) {
291
    var nodes = [];
292
    for (var i = 0, len = this.range_.length; i < len; i++) {
293
      nodes.push(this.range_.item(i));
294
    }
295
    goog.array.forEach(nodes, goog.dom.removeNode);
296

297
    this.collapse(false);
298
  }
299
};
300

301

302
/** @override */
303
goog.dom.ControlRange.prototype.replaceContentsWithNode = function(node) {
304
  // Control selections have to have the node inserted before removing the
305
  // selection contents because a collapsed control range doesn't have start or
306
  // end nodes.
307
  var result = this.insertNode(node, true);
308

309
  if (!this.isCollapsed()) {
310
    this.removeContents();
311
  }
312

313
  return result;
314
};
315

316

317
// SAVE/RESTORE
318

319

320
/** @override */
321
goog.dom.ControlRange.prototype.saveUsingDom = function() {
322
  return new goog.dom.DomSavedControlRange_(this);
323
};
324

325

326
// RANGE MODIFICATION
327

328

329
/** @override */
330
goog.dom.ControlRange.prototype.collapse = function(toAnchor) {
331
  // TODO(robbyw): Should this return a text range?  If so, API needs to change.
332
  this.range_ = null;
333
  this.clearCachedValues_();
334
};
335

336

337
// SAVED RANGE OBJECTS
338

339

340

341
/**
342
 * A SavedRange implementation using DOM endpoints.
343
 * @param {goog.dom.ControlRange} range The range to save.
344
 * @constructor
345
 * @extends {goog.dom.SavedRange}
346
 * @private
347
 */
348
goog.dom.DomSavedControlRange_ = function(range) {
349
  /**
350
   * The element list.
351
   * @type {Array<Element>}
352
   * @private
353
   */
354
  this.elements_ = range.getElements();
355
};
356
goog.inherits(goog.dom.DomSavedControlRange_, goog.dom.SavedRange);
357

358

359
/** @override */
360
goog.dom.DomSavedControlRange_.prototype.restoreInternal = function() {
361
  var doc = this.elements_.length ?
362
      goog.dom.getOwnerDocument(this.elements_[0]) :
363
      document;
364
  var controlRange = doc.body.createControlRange();
365
  for (var i = 0, len = this.elements_.length; i < len; i++) {
366
    controlRange.addElement(this.elements_[i]);
367
  }
368
  return goog.dom.ControlRange.createFromBrowserRange(controlRange);
369
};
370

371

372
/** @override */
373
goog.dom.DomSavedControlRange_.prototype.disposeInternal = function() {
374
  goog.dom.DomSavedControlRange_.superClass_.disposeInternal.call(this);
375
  delete this.elements_;
376
};
377

378

379
// RANGE ITERATION
380

381

382

383
/**
384
 * Subclass of goog.dom.TagIterator that iterates over a DOM range.  It
385
 * adds functions to determine the portion of each text node that is selected.
386
 *
387
 * @param {goog.dom.ControlRange?} range The range to traverse.
388
 * @constructor
389
 * @extends {goog.dom.RangeIterator}
390
 * @final
391
 */
392
goog.dom.ControlRangeIterator = function(range) {
393
  /**
394
   * The first node in the selection.
395
   * @private {Node}
396
   */
397
  this.startNode_ = null;
398

399
  /**
400
   * The last node in the selection.
401
   * @private {Node}
402
   */
403
  this.endNode_ = null;
404

405
  /**
406
   * The list of elements left to traverse.
407
   * @private {Array<Element>?}
408
   */
409
  this.elements_ = null;
410

411
  if (range) {
412
    this.elements_ = range.getSortedElements();
413
    this.startNode_ = this.elements_.shift();
414
    this.endNode_ = /** @type {Node} */ (goog.array.peek(this.elements_)) ||
415
        this.startNode_;
416
  }
417

418
  goog.dom.ControlRangeIterator.base(
419
      this, 'constructor', this.startNode_, false);
420
};
421
goog.inherits(goog.dom.ControlRangeIterator, goog.dom.RangeIterator);
422

423

424
/** @override */
425
goog.dom.ControlRangeIterator.prototype.getStartTextOffset = function() {
426
  return 0;
427
};
428

429

430
/** @override */
431
goog.dom.ControlRangeIterator.prototype.getEndTextOffset = function() {
432
  return 0;
433
};
434

435

436
/** @override */
437
goog.dom.ControlRangeIterator.prototype.getStartNode = function() {
438
  return this.startNode_;
439
};
440

441

442
/** @override */
443
goog.dom.ControlRangeIterator.prototype.getEndNode = function() {
444
  return this.endNode_;
445
};
446

447

448
/** @override */
449
goog.dom.ControlRangeIterator.prototype.isLast = function() {
450
  return !this.depth && !this.elements_.length;
451
};
452

453

454
/**
455
 * Move to the next position in the selection.
456
 * Throws {@code goog.iter.StopIteration} when it passes the end of the range.
457
 * @return {Node} The node at the next position.
458
 * @override
459
 */
460
goog.dom.ControlRangeIterator.prototype.next = function() {
461
  // Iterate over each element in the range, and all of its children.
462
  if (this.isLast()) {
463
    throw goog.iter.StopIteration;
464
  } else if (!this.depth) {
465
    var el = this.elements_.shift();
466
    this.setPosition(
467
        el, goog.dom.TagWalkType.START_TAG, goog.dom.TagWalkType.START_TAG);
468
    return el;
469
  }
470

471
  // Call the super function.
472
  return goog.dom.ControlRangeIterator.superClass_.next.call(this);
473
};
474

475

476
/** @override */
477
goog.dom.ControlRangeIterator.prototype.copyFrom = function(other) {
478
  this.elements_ = other.elements_;
479
  this.startNode_ = other.startNode_;
480
  this.endNode_ = other.endNode_;
481

482
  goog.dom.ControlRangeIterator.superClass_.copyFrom.call(this, other);
483
};
484

485

486
/**
487
 * @return {!goog.dom.ControlRangeIterator} An identical iterator.
488
 * @override
489
 */
490
goog.dom.ControlRangeIterator.prototype.clone = function() {
491
  var copy = new goog.dom.ControlRangeIterator(null);
492
  copy.copyFrom(this);
493
  return copy;
494
};
495

496