CKEDITOR.dom.selection

var sel = editor.getSelection();

Properties

• since 4.5.7 readonly

  FILLING_CHAR_SEQUENCE : StringCKEDITOR.dom.selection#FILLING_CHAR_SEQUENCE

  See source

  The sequence used in a WebKit-based browser to create a Filling Character. By default it is a string of 7 zero-width space characters (U+200B).

• readonly

  document : documentCKEDITOR.dom.selection#document

  See source

  Document in which selection is anchored.

• readonly

  isFake : BooleanCKEDITOR.dom.selection#isFake

  See source

  Whether selection is a fake selection.

  See fake method.

• readonly

  isLocked : BooleanCKEDITOR.dom.selection#isLocked

  See source

  Whether selection is locked (cannot be modified).

  See lock and unlock methods.

• since 4.3.0 readonly

  rev : NumberCKEDITOR.dom.selection#rev

  See source

  Selection's revision. This value is incremented every time new selection is created or existing one is modified.

• readonly

  root : elementCKEDITOR.dom.selection#root

  See source

  Selection's root element.

Methods

• constructor( target ) → selectionCKEDITOR.dom.selection#constructor

  See source

  Creates a selection class instance.

  // Selection scoped in document.
  var sel = new CKEDITOR.dom.selection( CKEDITOR.document );
  
  // Selection scoped in element with 'editable' id.
  var sel = new CKEDITOR.dom.selection( CKEDITOR.document.getById( 'editable' ) );
  
  // Cloning selection.
  var clone = new CKEDITOR.dom.selection( sel );
  

  Parameters

  target : document | element | selection

  The DOM document/element that the DOM selection is restrained to. Only selection which spans within the target element is considered as valid.

  If CKEDITOR.dom.selection is passed, then its clone will be created.

  Returns

  selection

  createBookmarks( serializable ) → ArrayCKEDITOR.dom.selection#createBookmarks

  See source

  Creates a bookmark for each range of this selection (from getRanges) by calling the CKEDITOR.dom.range.createBookmark method, with extra care taken to avoid interference among those ranges. The arguments received are the same as with the underlying range method.

  var bookmarks = editor.getSelection().createBookmarks();
  

  Parameters

  serializable : Object

  Returns

  Array

  Array of bookmarks for each range.

  createBookmarks2( normalized ) → ArrayCKEDITOR.dom.selection#createBookmarks2

  See source

  Creates a bookmark for each range of this selection (from getRanges) by calling the CKEDITOR.dom.range.createBookmark2 method, with extra care taken to avoid interference among those ranges. The arguments received are the same as with the underlying range method.

  var bookmarks = editor.getSelection().createBookmarks2();
  

  Parameters

  normalized : Object

  Returns

  Array

  Array of bookmarks for each range.

  fake( element, [ ariaLabel ] )CKEDITOR.dom.selection#fake

  See source

  Makes a "fake selection" of an element.

  A fake selection does not render UI artifacts over the selected element. Additionally, the browser native selection system is not aware of the fake selection. In practice, the native selection is moved to a hidden place where no native selection UI artifacts are displayed to the user.

  Parameters

  element : element

  The element to be "selected".

  [ ariaLabel ] : String

  A string to be used by the screen reader to describe the selection.

  getCommonAncestor() → elementCKEDITOR.dom.selection#getCommonAncestor

  See source

  Retrieves the common ancestor node of the first range and the last range.

  var ancestor = editor.getSelection().getCommonAncestor();
  

  Returns

  element

  The common ancestor of the selection or null if selection is empty.

  getNative() → ObjectCKEDITOR.dom.selection#getNative

  See source

  Gets the native selection object from the browser.

  var selection = editor.getSelection().getNative();
  

  Returns

  Object

  The native browser selection object or null if this is a fake selection.

  getRanges( [ onlyEditables ] ) → ArrayCKEDITOR.dom.selection#getRanges

  See source

  Retrieves the CKEDITOR.dom.range instances that represent the current selection.

  Note: Some browsers return multiple ranges even for a continuous selection. Firefox, for example, returns one range for each table cell when one or more table rows are selected.

  var ranges = selection.getRanges();
  alert( ranges.length );
  

  Parameters

  [ onlyEditables ] : Boolean

  If set to true, this function retrieves editable ranges only.

  Returns

  Array

  Range instances that represent the current selection.

  getSelectedElement() → element | nullCKEDITOR.dom.selection#getSelectedElement

  See source

  Gets the currently selected element.

  var element = editor.getSelection().getSelectedElement();
  alert( element.getName() );
  

  Returns

  element | null

  The selected element. null if no selection is available or the selection type is not CKEDITOR.SELECTION_ELEMENT.

  since 3.6.1

  getSelectedText() → StringCKEDITOR.dom.selection#getSelectedText

  See source

  Retrieves the text contained within the range. An empty string is returned for non-text selection.

  var text = editor.getSelection().getSelectedText();
  alert( text );
  

  Returns

  String

  A string of text within the current selection.

  getStartElement() → elementCKEDITOR.dom.selection#getStartElement

  See source

  Gets the DOM element in which the selection starts.

  var element = editor.getSelection().getStartElement();
  alert( element.getName() );
  

  Returns

  element

  The element at the beginning of the selection.

  getType() → NumberCKEDITOR.dom.selection#getType

  See source

  Gets the type of the current selection. The following values are available:

  • CKEDITOR.SELECTION_NONE (1): No selection.
  • CKEDITOR.SELECTION_TEXT (2): A text or a collapsed selection is selected.
  • CKEDITOR.SELECTION_ELEMENT (3): An element is selected.

  Example:

  if ( editor.getSelection().getType() == CKEDITOR.SELECTION_TEXT )
      alert( 'A text is selected' );
  

  Returns

  Number

  One of the following constant values: CKEDITOR.SELECTION_NONE, CKEDITOR.SELECTION_TEXT or CKEDITOR.SELECTION_ELEMENT.

  since 4.7.3

  isCollapsed() → BooleanCKEDITOR.dom.selection#isCollapsed

  See source

  Checks if the selection contains only one range which is collapsed.

  if ( editor.getSelection().isCollapsed() ) {
      // Do something when the selection is collapsed.
  }
  

  Returns

  Boolean

  isHidden() → BooleanCKEDITOR.dom.selection#isHidden

  See source

  Checks whether selection is placed in hidden element.

  This method is to be used to verify whether fake selection (see fake) is still hidden.

  Note: this method should be executed on real selection - e.g.:

  editor.getSelection( true ).isHidden();
  

  Returns

  Boolean

  since 4.7.0

  isInTable( [ allowPartialSelection ] ) → BooleanCKEDITOR.dom.selection#isInTable

  See source

  Checks if the selection contains an HTML element inside a table. Returns false for text selection inside a table (e.g. it will return false for text selected in one cell).

  editor.getSelection().isInTable();
  

  Parameters

  [ allowPartialSelection ] : Boolean

  Whether a partial cell selection should be included. Added in 4.7.2.

  Defaults to false

  Returns

  Boolean

  lock()CKEDITOR.dom.selection#lock

  See source

  Locks the selection made in the editor in order to make it possible to manipulate it without browser interference. A locked selection is cached and remains unchanged until it is released with the unlock method.

  editor.getSelection().lock();
  

  since 4.13.0

  optimizeInElementEnds()CKEDITOR.dom.selection#optimizeInElementEnds

  See source

  Performs an optimization on the current selection if necessary.

  The general idea is to shrink the range to text when:

  • The range starts at the end of an element.
  • The range ends at the start of an element.
  • One of the range ends is anchored in a text node and another in an element.

  For example:

   <p>{foo</p>
   <p>]bar</p>
  

  is optimized too:

   <p>{foo}</p>
   <p>bar</p>
  

  removeAllRanges()CKEDITOR.dom.selection#removeAllRanges

  See source

  Remove all the selection ranges from the document.

  reset()CKEDITOR.dom.selection#reset

  See source

  Clears the selection cache.

  editor.getSelection().reset();
  

  scrollIntoView()CKEDITOR.dom.selection#scrollIntoView

  See source

  Moves the scrollbar to the starting position of the current selection.

  editor.getSelection().scrollIntoView();
  

  chainable

  selectBookmarks( bookmarks ) → selectionCKEDITOR.dom.selection#selectBookmarks

  See source

  Selects the virtual ranges denoted by the bookmarks by calling selectRanges.

  var bookmarks = editor.getSelection().createBookmarks();
  editor.getSelection().selectBookmarks( bookmarks );
  

  Parameters

  bookmarks : Array

  The bookmarks representing ranges to be selected.

  Returns

  selection

  This selection object, after the ranges were selected.

  selectElement( element )CKEDITOR.dom.selection#selectElement

  See source

  Makes the current selection of type CKEDITOR.SELECTION_ELEMENT by enclosing the specified element.

  var element = editor.document.getById( 'sampleElement' );
  editor.getSelection().selectElement( element );
  

  Parameters

  element : element

  The element to enclose in the selection.

  selectRanges( ranges )CKEDITOR.dom.selection#selectRanges

  See source

  Clears the original selection and adds the specified ranges to the document selection.

      // Move selection to the end of the editable element.
  var range = editor.createRange();
  range.moveToPosition( range.root, CKEDITOR.POSITION_BEFORE_END );
  editor.getSelection().selectRanges( [ ranges ] );
  

  Parameters

  ranges : Array

  An array of CKEDITOR.dom.range instances representing ranges to be added to the document.

  unlock( restore )CKEDITOR.dom.selection#unlock

  See source

  Parameters

  restore : Object

  Static methods

  • since 4.13.0 static

    setupEditorOptimization( editor )CKEDITOR.dom.selection#setupEditorOptimization

    See source

    Sets editor listeners up to optimize the selection.

    Note: This method is called automatically during the editor initialization and should not be called manually.

    CKEDITOR.dom.selection.optimizeInElementEnds

    Parameters

    editor : editor