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 W3C multi-part ranges.
17
 *
18
 * @author [email protected] (Robby Walker)
19
 */
20

21

22
goog.provide('goog.dom.MultiRange');
23
goog.provide('goog.dom.MultiRangeIterator');
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.TextRange');
33
goog.require('goog.iter');
34
goog.require('goog.iter.StopIteration');
35
goog.require('goog.log');
36

37

38

39
/**
40
 * Creates a new multi part range 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.MultiRange = function() {
47
  /**
48
   * Logging object.
49
   * @private {goog.log.Logger}
50
   */
51
  this.logger_ = goog.log.getLogger('goog.dom.MultiRange');
52

53
  /**
54
   * Array of browser sub-ranges comprising this multi-range.
55
   * @private {Array<Range>}
56
   */
57
  this.browserRanges_ = [];
58

59
  /**
60
   * Lazily initialized array of range objects comprising this multi-range.
61
   * @private {Array<goog.dom.TextRange>}
62
   */
63
  this.ranges_ = [];
64

65
  /**
66
   * Lazily computed sorted version of ranges_, sorted by start point.
67
   * @private {Array<goog.dom.TextRange>?}
68
   */
69
  this.sortedRanges_ = null;
70

71
  /**
72
   * Lazily computed container node.
73
   * @private {Node}
74
   */
75
  this.container_ = null;
76
};
77
goog.inherits(goog.dom.MultiRange, goog.dom.AbstractMultiRange);
78

79

80
/**
81
 * Creates a new range wrapper from the given browser selection object.  Do not
82
 * use this method directly - please use goog.dom.Range.createFrom* instead.
83
 * @param {Selection} selection The browser selection object.
84
 * @return {!goog.dom.MultiRange} A range wrapper object.
85
 */
86
goog.dom.MultiRange.createFromBrowserSelection = function(selection) {
87
  var range = new goog.dom.MultiRange();
88
  for (var i = 0, len = selection.rangeCount; i < len; i++) {
89
    range.browserRanges_.push(selection.getRangeAt(i));
90
  }
91
  return range;
92
};
93

94

95
/**
96
 * Creates a new range wrapper from the given browser ranges.  Do not
97
 * use this method directly - please use goog.dom.Range.createFrom* instead.
98
 * @param {Array<Range>} browserRanges The browser ranges.
99
 * @return {!goog.dom.MultiRange} A range wrapper object.
100
 */
101
goog.dom.MultiRange.createFromBrowserRanges = function(browserRanges) {
102
  var range = new goog.dom.MultiRange();
103
  range.browserRanges_ = goog.array.clone(browserRanges);
104
  return range;
105
};
106

107

108
/**
109
 * Creates a new range wrapper from the given goog.dom.TextRange objects.  Do
110
 * not use this method directly - please use goog.dom.Range.createFrom* instead.
111
 * @param {Array<goog.dom.TextRange>} textRanges The text range objects.
112
 * @return {!goog.dom.MultiRange} A range wrapper object.
113
 */
114
goog.dom.MultiRange.createFromTextRanges = function(textRanges) {
115
  var range = new goog.dom.MultiRange();
116
  range.ranges_ = textRanges;
117
  range.browserRanges_ = goog.array.map(
118
      textRanges, function(range) { return range.getBrowserRangeObject(); });
119
  return range;
120
};
121

122

123
// Method implementations
124

125

126
/**
127
 * Clears cached values.  Should be called whenever this.browserRanges_ is
128
 * modified.
129
 * @private
130
 */
131
goog.dom.MultiRange.prototype.clearCachedValues_ = function() {
132
  this.ranges_ = [];
133
  this.sortedRanges_ = null;
134
  this.container_ = null;
135
};
136

137

138
/**
139
 * @return {!goog.dom.MultiRange} A clone of this range.
140
 * @override
141
 */
142
goog.dom.MultiRange.prototype.clone = function() {
143
  return goog.dom.MultiRange.createFromBrowserRanges(this.browserRanges_);
144
};
145

146

147
/** @override */
148
goog.dom.MultiRange.prototype.getType = function() {
149
  return goog.dom.RangeType.MULTI;
150
};
151

152

153
/** @override */
154
goog.dom.MultiRange.prototype.getBrowserRangeObject = function() {
155
  // NOTE(robbyw): This method does not make sense for multi-ranges.
156
  if (this.browserRanges_.length > 1) {
157
    goog.log.warning(
158
        this.logger_,
159
        'getBrowserRangeObject called on MultiRange with more than 1 range');
160
  }
161
  return this.browserRanges_[0];
162
};
163

164

165
/** @override */
166
goog.dom.MultiRange.prototype.setBrowserRangeObject = function(nativeRange) {
167
  // TODO(robbyw): Look in to adding setBrowserSelectionObject.
168
  return false;
169
};
170

171

172
/** @override */
173
goog.dom.MultiRange.prototype.getTextRangeCount = function() {
174
  return this.browserRanges_.length;
175
};
176

177

178
/** @override */
179
goog.dom.MultiRange.prototype.getTextRange = function(i) {
180
  if (!this.ranges_[i]) {
181
    this.ranges_[i] =
182
        goog.dom.TextRange.createFromBrowserRange(this.browserRanges_[i]);
183
  }
184
  return this.ranges_[i];
185
};
186

187

188
/** @override */
189
goog.dom.MultiRange.prototype.getContainer = function() {
190
  if (!this.container_) {
191
    var nodes = [];
192
    for (var i = 0, len = this.getTextRangeCount(); i < len; i++) {
193
      nodes.push(this.getTextRange(i).getContainer());
194
    }
195
    this.container_ = goog.dom.findCommonAncestor.apply(null, nodes);
196
  }
197
  return this.container_;
198
};
199

200

201
/**
202
 * @return {!Array<goog.dom.TextRange>} An array of sub-ranges, sorted by start
203
 *     point.
204
 */
205
goog.dom.MultiRange.prototype.getSortedRanges = function() {
206
  if (!this.sortedRanges_) {
207
    this.sortedRanges_ = this.getTextRanges();
208
    this.sortedRanges_.sort(function(a, b) {
209
      var aStartNode = a.getStartNode();
210
      var aStartOffset = a.getStartOffset();
211
      var bStartNode = b.getStartNode();
212
      var bStartOffset = b.getStartOffset();
213

214
      if (aStartNode == bStartNode && aStartOffset == bStartOffset) {
215
        return 0;
216
      }
217

218
      /**
219
       * @suppress {missingRequire} Cannot depend on goog.dom.Range because
220
       *     it creates a circular dependency.
221
       */
222
      return goog.dom.Range.isReversed(
223
                 aStartNode, aStartOffset, bStartNode, bStartOffset) ?
224
          1 :
225
          -1;
226
    });
227
  }
228
  return this.sortedRanges_;
229
};
230

231

232
/** @override */
233
goog.dom.MultiRange.prototype.getStartNode = function() {
234
  return this.getSortedRanges()[0].getStartNode();
235
};
236

237

238
/** @override */
239
goog.dom.MultiRange.prototype.getStartOffset = function() {
240
  return this.getSortedRanges()[0].getStartOffset();
241
};
242

243

244
/** @override */
245
goog.dom.MultiRange.prototype.getEndNode = function() {
246
  // NOTE(robbyw): This may return the wrong node if any subranges overlap.
247
  return goog.array.peek(this.getSortedRanges()).getEndNode();
248
};
249

250

251
/** @override */
252
goog.dom.MultiRange.prototype.getEndOffset = function() {
253
  // NOTE(robbyw): This may return the wrong value if any subranges overlap.
254
  return goog.array.peek(this.getSortedRanges()).getEndOffset();
255
};
256

257

258
/** @override */
259
goog.dom.MultiRange.prototype.isRangeInDocument = function() {
260
  return goog.array.every(this.getTextRanges(), function(range) {
261
    return range.isRangeInDocument();
262
  });
263
};
264

265

266
/** @override */
267
goog.dom.MultiRange.prototype.isCollapsed = function() {
268
  return this.browserRanges_.length == 0 ||
269
      this.browserRanges_.length == 1 && this.getTextRange(0).isCollapsed();
270
};
271

272

273
/** @override */
274
goog.dom.MultiRange.prototype.getText = function() {
275
  return goog.array
276
      .map(this.getTextRanges(), function(range) { return range.getText(); })
277
      .join('');
278
};
279

280

281
/** @override */
282
goog.dom.MultiRange.prototype.getHtmlFragment = function() {
283
  return this.getValidHtml();
284
};
285

286

287
/** @override */
288
goog.dom.MultiRange.prototype.getValidHtml = function() {
289
  // NOTE(robbyw): This does not behave well if the sub-ranges overlap.
290
  return goog.array
291
      .map(
292
          this.getTextRanges(),
293
          function(range) { return range.getValidHtml(); })
294
      .join('');
295
};
296

297

298
/** @override */
299
goog.dom.MultiRange.prototype.getPastableHtml = function() {
300
  // TODO(robbyw): This should probably do something smart like group TR and TD
301
  // selections in to the same table.
302
  return this.getValidHtml();
303
};
304

305

306
/** @override */
307
goog.dom.MultiRange.prototype.__iterator__ = function(opt_keys) {
308
  return new goog.dom.MultiRangeIterator(this);
309
};
310

311

312
// RANGE ACTIONS
313

314

315
/** @override */
316
goog.dom.MultiRange.prototype.select = function() {
317
  var selection =
318
      goog.dom.AbstractRange.getBrowserSelectionForWindow(this.getWindow());
319
  selection.removeAllRanges();
320
  for (var i = 0, len = this.getTextRangeCount(); i < len; i++) {
321
    selection.addRange(this.getTextRange(i).getBrowserRangeObject());
322
  }
323
};
324

325

326
/** @override */
327
goog.dom.MultiRange.prototype.removeContents = function() {
328
  goog.array.forEach(
329
      this.getTextRanges(), function(range) { range.removeContents(); });
330
};
331

332

333
// SAVE/RESTORE
334

335

336
/** @override */
337
goog.dom.MultiRange.prototype.saveUsingDom = function() {
338
  return new goog.dom.DomSavedMultiRange_(this);
339
};
340

341

342
// RANGE MODIFICATION
343

344

345
/**
346
 * Collapses this range to a single point, either the first or last point
347
 * depending on the parameter.  This will result in the number of ranges in this
348
 * multi range becoming 1.
349
 * @param {boolean} toAnchor Whether to collapse to the anchor.
350
 * @override
351
 */
352
goog.dom.MultiRange.prototype.collapse = function(toAnchor) {
353
  if (!this.isCollapsed()) {
354
    var range = toAnchor ? this.getTextRange(0) :
355
                           this.getTextRange(this.getTextRangeCount() - 1);
356

357
    this.clearCachedValues_();
358
    range.collapse(toAnchor);
359
    this.ranges_ = [range];
360
    this.sortedRanges_ = [range];
361
    this.browserRanges_ = [range.getBrowserRangeObject()];
362
  }
363
};
364

365

366
// SAVED RANGE OBJECTS
367

368

369

370
/**
371
 * A SavedRange implementation using DOM endpoints.
372
 * @param {goog.dom.MultiRange} range The range to save.
373
 * @constructor
374
 * @extends {goog.dom.SavedRange}
375
 * @private
376
 */
377
goog.dom.DomSavedMultiRange_ = function(range) {
378
  /**
379
   * Array of saved ranges.
380
   * @type {Array<goog.dom.SavedRange>}
381
   * @private
382
   */
383
  this.savedRanges_ = goog.array.map(
384
      range.getTextRanges(), function(range) { return range.saveUsingDom(); });
385
};
386
goog.inherits(goog.dom.DomSavedMultiRange_, goog.dom.SavedRange);
387

388

389
/**
390
 * @return {!goog.dom.MultiRange} The restored range.
391
 * @override
392
 */
393
goog.dom.DomSavedMultiRange_.prototype.restoreInternal = function() {
394
  var ranges = goog.array.map(
395
      this.savedRanges_, function(savedRange) { return savedRange.restore(); });
396
  return goog.dom.MultiRange.createFromTextRanges(ranges);
397
};
398

399

400
/** @override */
401
goog.dom.DomSavedMultiRange_.prototype.disposeInternal = function() {
402
  goog.dom.DomSavedMultiRange_.superClass_.disposeInternal.call(this);
403

404
  goog.array.forEach(
405
      this.savedRanges_, function(savedRange) { savedRange.dispose(); });
406
  delete this.savedRanges_;
407
};
408

409

410
// RANGE ITERATION
411

412

413

414
/**
415
 * Subclass of goog.dom.TagIterator that iterates over a DOM range.  It
416
 * adds functions to determine the portion of each text node that is selected.
417
 *
418
 * @param {goog.dom.MultiRange} range The range to traverse.
419
 * @constructor
420
 * @extends {goog.dom.RangeIterator}
421
 * @final
422
 */
423
goog.dom.MultiRangeIterator = function(range) {
424
  /**
425
   * The list of range iterators left to traverse.
426
   * @private {Array<goog.dom.RangeIterator>}
427
   */
428
  this.iterators_ = null;
429

430
  /**
431
   * The index of the current sub-iterator being traversed.
432
   * @private {number}
433
   */
434
  this.currentIdx_ = 0;
435

436
  if (range) {
437
    this.iterators_ = goog.array.map(range.getSortedRanges(), function(r) {
438
      return goog.iter.toIterator(r);
439
    });
440
  }
441

442
  goog.dom.MultiRangeIterator.base(
443
      this, 'constructor', range ? this.getStartNode() : null, false);
444
};
445
goog.inherits(goog.dom.MultiRangeIterator, goog.dom.RangeIterator);
446

447

448
/** @override */
449
goog.dom.MultiRangeIterator.prototype.getStartTextOffset = function() {
450
  return this.iterators_[this.currentIdx_].getStartTextOffset();
451
};
452

453

454
/** @override */
455
goog.dom.MultiRangeIterator.prototype.getEndTextOffset = function() {
456
  return this.iterators_[this.currentIdx_].getEndTextOffset();
457
};
458

459

460
/** @override */
461
goog.dom.MultiRangeIterator.prototype.getStartNode = function() {
462
  return this.iterators_[0].getStartNode();
463
};
464

465

466
/** @override */
467
goog.dom.MultiRangeIterator.prototype.getEndNode = function() {
468
  return goog.array.peek(this.iterators_).getEndNode();
469
};
470

471

472
/** @override */
473
goog.dom.MultiRangeIterator.prototype.isLast = function() {
474
  return this.iterators_[this.currentIdx_].isLast();
475
};
476

477

478
/** @override */
479
goog.dom.MultiRangeIterator.prototype.next = function() {
480

481
  try {
482
    var it = this.iterators_[this.currentIdx_];
483
    var next = it.next();
484
    this.setPosition(it.node, it.tagType, it.depth);
485
    return next;
486
  } catch (ex) {
487
    if (ex !== goog.iter.StopIteration ||
488
        this.iterators_.length - 1 == this.currentIdx_) {
489
      throw ex;
490
    } else {
491
      // In case we got a StopIteration, increment counter and try again.
492
      this.currentIdx_++;
493
      return this.next();
494
    }
495
  }
496
};
497

498

499
/** @override */
500
goog.dom.MultiRangeIterator.prototype.copyFrom = function(other) {
501
  this.iterators_ = goog.array.clone(other.iterators_);
502
  goog.dom.MultiRangeIterator.superClass_.copyFrom.call(this, other);
503
};
504

505

506
/**
507
 * @return {!goog.dom.MultiRangeIterator} An identical iterator.
508
 * @override
509
 */
510
goog.dom.MultiRangeIterator.prototype.clone = function() {
511
  var copy = new goog.dom.MultiRangeIterator(null);
512
  copy.copyFrom(this);
513
  return copy;
514
};
515

516