Skip to content

range.md

Latest commit

 

History

History
76 lines (54 loc) · 2.96 KB

range.md

File metadata and controls

76 lines (54 loc) · 2.96 KB

@constructor jQuery.Range jQuery.Range @parent jquerypp

@body jQuery.Range provides text range helpers for creating, moving, and comparing ranges cross browser. You can get the currently selected range by calling [jQuery.Range.static.current $.Range.current()] a new range can be created by passing

  • undefined or null - returns a range with nothing selected

  • HTMLElement - returns a range with the node's text selected

  • Point - returns a range at the point on the screen. The point can be specified like:

      //client coordinates
  {clientX: 200, clientY: 300}
  //page coordinates
  {pageX: 200, pageY: 300}
  {top: 200, left: 300}

  • TextRange a raw text range object.

to the constructor.

$.Range

An instance of $.Range offers the following methods:

  • [jQuery.Range::clone clone] - clones the range and returns a new $.Range object
  • [jQuery.Range::collapse collapse] - clones the range and returns a new $.Range object
  • [jQuery.Range::compare compare] - compares one range to another range
  • [jQuery.Range::end end] - sets or returns the end of the range
  • [jQuery.Range::move move] - move the endpoints of a range relative to another range
  • [jQuery.Range::overlaps overlaps] - returns if any portion of these two ranges overlap
  • [jQuery.Range::parent parent] - returns the most common ancestor element of the endpoints in the range
  • [jQuery.Range::rect rect] - returns the bounding rectangle of this range
  • [jQuery.Range::rects rects] - returns the client rects
  • [jQuery.Range::start start] - sets or returns the beginning of the range
  • [jQuery.Range::toString toString] - returns the text of the range

Note, that the container returned by [jQuery.Range::start start] and [jQuery.Range::end end] can be a text node or cdata section (see node types). It can be checked by comparing the returned elements nodeType with Node.TEXT_NODE or Node.CDATA_SECTION_NODE which you will need to get the element containing the selected text:

var startNode = range.start().container;
if( startNode.nodeType === Node.TEXT_NODE ||
  startNode.nodeType === Node.CDATA_SECTION_NODE ) {
  startNode = startNode.parentNode;
}
$(startNode).addClass('highlight');

Examples

Consider an HTML element like

<div id="text">This is some text</div>`

$.Range can be used like this:

// Get a text range for #text
var range = $('#text').range();

// Move the start 5 characters to the right
range.start('+5');

// Move the end 5 characters to the left
range.end('-5');

// Return the range text
range.toString() // is some

// Select the current range
range.select();

 // get the startOffset of the range and the container
 range.start() //-> { offset: 5, container: HTMLELement }

 //get the most common ancestor element
 var parent = range.parent();

 //select the parent
 var range2 = new $.Range(parent);