CKEDITOR.tools

Properties

• array : arrayCKEDITOR.tools#array

  See source

  A set of array helpers.

• object : objectCKEDITOR.tools#object

  See source

  A set of object helpers.

• style : styleCKEDITOR.tools#style

  See source

  A set of functions for operations on styles.

• since 4.4.0 readonly

  transparentImageData : StringCKEDITOR.tools#transparentImageData

  See source

  The data URI of a transparent image. May be used e.g. in HTML as an image source or in CSS in url().

  Defaults to 'data:image/gif;base64,R0lGODlhAQABAPABAP///wAAACH5BAEKAAAALAAAAAABAAEAAAICRAEAOw=='

• deprecated 4.16.0 private

  _hslaRegExp : RegExpCKEDITOR.tools#_hslaRegExp

  See source

  Note: This regexp is deprecated, use CKEDITOR.tools.color to handle colors.

  Defaults to /hsla?\(\s*[0-9.]+\s*,\s*\d+%\s*,\s*\d+%\s*(?:,\s*[0-9.]+\s*)?\)/gi

• deprecated 4.16.0 private

  _rgbaRegExp : RegExpCKEDITOR.tools#_rgbaRegExp

  See source

  Note: This regexp is deprecated, use CKEDITOR.tools.color to handle colors.

  Defaults to /rgba?\(\s*\d+%?\s*,\s*\d+%?\s*,\s*\d+%?\s*(?:,\s*[0-9.]+\s*)?\)/gi

Methods

• addFunction( fn, [ scope ] ) → NumberCKEDITOR.tools#addFunction

  See source

  Creates a function reference that can be called later using callFunction. This approach is especially useful to make DOM attribute function calls to JavaScript-defined functions.

  var ref = CKEDITOR.tools.addFunction( function() {
      alert( 'Hello!');
  } );
  CKEDITOR.tools.callFunction( ref ); // 'Hello!'
  

  Parameters

  fn : Function

  The function to be executed on call.

  [ scope ] : Object

  The object to have the context on fn execution.

  Returns

  Number

  A unique reference to be used in conjuction with callFunction.

  arrayCompare( arrayA, arrayB ) → BooleanCKEDITOR.tools#arrayCompare

  See source

  Compares the elements of two arrays.

  var a = [ 1, 'a', 3 ];
  var b = [ 1, 3, 'a' ];
  var c = [ 1, 'a', 3 ];
  var d = [ 1, 'a', 3, 4 ];
  
  alert( CKEDITOR.tools.arrayCompare( a, b ) );  // false
  alert( CKEDITOR.tools.arrayCompare( a, c ) );  // true
  alert( CKEDITOR.tools.arrayCompare( a, d ) );  // false
  

  Parameters

  arrayA : Array

  An array to be compared.

  arrayB : Array

  The other array to be compared.

  Returns

  Boolean

  true if the arrays have the same length and their elements match.

  bind( func, obj, [ args ] ) → FunctionCKEDITOR.tools#bind

  See source

  Creates a function that will always execute in the context of a specified object.

  var obj = { text: 'My Object' };
  
  function alertText() {
      alert( this.text );
  }
  
  var newFunc = CKEDITOR.tools.bind( alertText, obj );
  newFunc(); // Alerts 'My Object'.
  

  Since 4.13.0 additional arguments can be bound to a function.

  function logData( text, number1, number2 ) {
      console.log( text, number1, number2 );
  }
  
  var newFunc = CKEDITOR.tools.bind( logData, null, 'Foo', 1 );
  newFunc(); // Logs: 'Foo', 1, undefined.
  newFunc( 2 ); // Logs: 'Foo', 1, 2.
  

  Parameters

  func : Function

  The function to be executed.

  obj : Object

  The object to which the execution context will be bound.

  [ args ] : *

  Arguments provided to the bound function when invoking the target function. Available since 4.13.0.

  Returns

  Function

  The function that can be used to execute the func function in the context of the specified obj object.

  buildStyleHtml( css ) → StringCKEDITOR.tools#buildStyleHtml

  See source

  Builds a HTML snippet from a set of <style>/<link>.

  Parameters

  css : String | Array

  Each of which are URLs (absolute) of a CSS file or a trunk of style text.

  Returns

  String

  buildTableMap( table, startRow, startCell, endRow, endCell )CKEDITOR.tools#buildTableMap

  See source

  Creates a two-dimension array that reflects the actual layout of table cells, with cell spans, with mappings to the original td elements.

  It could also create a map for the specified fragment of the table.

  Parameters

  table : element

  startRow : Number

  Row index from which the map should be created.

  startCell : Number

  Cell index from which the map should be created.

  endRow : Number

  Row index to which the map should be created.

  endCell : Number

  Cell index to which the map should be created.

  callFunction( ref, params ) → MixedCKEDITOR.tools#callFunction

  See source

  Executes a function based on the reference created with addFunction.

  var ref = CKEDITOR.tools.addFunction( function() {
      alert( 'Hello!');
  } );
  CKEDITOR.tools.callFunction( ref ); // 'Hello!'
  

  Parameters

  ref : Number

  The function reference created with addFunction.

  params : Mixed

  Any number of parameters to be passed to the executed function.

  Returns

  Mixed

  The return value of the function.

  capitalize( str, [ keepCase ] ) → StringCKEDITOR.tools#capitalize

  See source

  Turns the first letter of a string to upper-case.

  Parameters

  str : String

  [ keepCase ] : Boolean

  Keep the case of 2nd to last letter.

  Returns

  String

  since 4.4.0

  checkIfAnyArrayItemMatches( arr, regexp ) → BooleanCKEDITOR.tools#checkIfAnyArrayItemMatches

  See source

  Checks if any of the arr items match the provided regular expression.

  Parameters

  arr : Array

  The array whose items will be checked.

  regexp : RegExp

  The regular expression.

  Returns

  Boolean

  Returns true for the first occurrence of the search pattern.

  since 4.4.0

  checkIfAnyObjectPropertyMatches( obj, regexp ) → BooleanCKEDITOR.tools#checkIfAnyObjectPropertyMatches

  See source

  Checks if any of the obj properties match the provided regular expression.

  Parameters

  obj : Object

  The object whose properties will be checked.

  regexp : RegExp

  The regular expression.

  Returns

  Boolean

  Returns true for the first occurrence of the search pattern.

  clone( object ) → ObjectCKEDITOR.tools#clone

  See source

  Creates a deep copy of an object.

  Note: Recursive references are not supported.

  var obj = {
      name: 'John',
      cars: {
          Mercedes: { color: 'blue' },
          Porsche: { color: 'red' }
      }
  };
  var clone = CKEDITOR.tools.clone( obj );
  clone.name = 'Paul';
  clone.cars.Porsche.color = 'silver';
  
  alert( obj.name );                  // 'John'
  alert( clone.name );                // 'Paul'
  alert( obj.cars.Porsche.color );    // 'red'
  alert( clone.cars.Porsche.color );  // 'silver'
  

  Parameters

  object : Object

  The object to be cloned.

  Returns

  Object

  The object clone.

  since 4.1.0

  convertArrayToObject( arr, [ fillWith ] )CKEDITOR.tools#convertArrayToObject

  See source

  Converts an array to an object by rewriting array items to object properties.

  var arr = [ 'foo', 'bar', 'foo' ];
  console.log( CKEDITOR.tools.convertArrayToObject( arr ) );
  // -> { foo: true, bar: true }
  console.log( CKEDITOR.tools.convertArrayToObject( arr, 1 ) );
  // -> { foo: 1, bar: 1 }
  

  Parameters

  arr : Array

  The array to be converted to an object.

  [ fillWith ] : Object

  Set each property of an object to fillWith value.

  Defaults to true

  since 4.8.0

  convertBytesToBase64( bytesArray ) → StringCKEDITOR.tools#convertBytesToBase64

  See source

  Converts a bytes array into a a Base64-encoded string.

  Parameters

  bytesArray : Number[]

  An array that stores 1 byte in each cell as an Integer number.

  Returns

  String

  Base64-encoded string that represents input bytes.

  since 4.8.0

  convertHexStringToBytes( hexString ) → Number[]CKEDITOR.tools#convertHexStringToBytes

  See source

  Converts a hex string to an array containing 1 byte in each cell. Bytes are represented as Integer numbers.

  Parameters

  hexString : String

  Contains an input string which represents bytes, e.g. "08A11D8ADA2B".

  Returns

  Number[]

  Bytes stored in a form of Integer numbers, e.g. [ 8, 161, 29, 138, 218, 43 ].

  convertRgbToHex( styleText ) → StringCKEDITOR.tools#convertRgbToHex

  See source

  Finds and converts rgb(x,x,x) color definition into a given string to hexadecimal notation.

  Note: For handling RGB string only (not within text) it is recommended to use CKEDITOR.tools.color to create color instance and CKEDITOR.tools.color.getHex method to get its hexadecimal representation:

  var color = new CKEDITOR.tools.color( 'rgb( 225, 225, 225 )' ); // Create color instance.
  console.log( color.getHex() ); // #FFFFFF
  

  Parameters

  styleText : String

  The style data (or just a string containing RGB colors) to be converted.

  Returns

  String

  The style data with RGB colors converted to hexadecimal equivalents.

  convertToPx( cssLength ) → Number | StringCKEDITOR.tools#convertToPx

  See source

  Converts the specified CSS length value to the calculated pixel length inside this page.

  Since 4.11.0 it also returns negative values.

  Note: Percentage-based value is left intact.

  Parameters

  cssLength : String

  CSS length value.

  Returns

  Number | String

  A number representing the length in pixels or a string with a percentage value.

  since 4.1.0

  copy( source ) → ObjectCKEDITOR.tools#copy

  See source

  Makes fast (shallow) copy of an object. This method is faster than clone which does a deep copy of an object (including arrays).

  Parameters

  source : Object

  The object to be copied.

  Returns

  Object

  Copy of source.

  createClass( definition ) → FunctionCKEDITOR.tools#createClass

  See source

  Class creation based on prototype inheritance which supports the following features:

  • Static fields
  • Private fields
  • Public (prototype) fields
  • Chainable base class constructor

  Parameters

  definition : Object

  The class definition object.

  Returns

  Function

  A class-like JavaScript function.

  cssLength( length )CKEDITOR.tools#cssLength

  See source

  Appends the px length unit to the size value if it is missing.

  var cssLength = CKEDITOR.tools.cssLength;
  cssLength( 42 );        // '42px'
  cssLength( '42' );      // '42px'
  cssLength( '42px' );    // '42px'
  cssLength( '42%' );     // '42%'
  cssLength( 'bold' );    // 'bold'
  cssLength( false );     // ''
  cssLength( NaN );       // ''
  

  Parameters

  length : Number | String | Boolean

  cssStyleToDomStyle( cssName ) → StringCKEDITOR.tools#cssStyleToDomStyle

  See source

  Transforms a CSS property name to its relative DOM style name.

  alert( CKEDITOR.tools.cssStyleToDomStyle( 'background-color' ) );   // 'backgroundColor'
  alert( CKEDITOR.tools.cssStyleToDomStyle( 'float' ) );              // 'cssFloat'
  

  Parameters

  cssName : String

  The CSS property name.

  Returns

  String

  The transformed name.

  cssVendorPrefix( property, value, [ asString ] ) → Object | StringCKEDITOR.tools#cssVendorPrefix

  See source

  Generates an object or a string containing vendor-specific and vendor-free CSS properties.

  CKEDITOR.tools.cssVendorPrefix( 'border-radius', '0', true );
  // On Firefox: '-moz-border-radius:0;border-radius:0'
  // On Chrome: '-webkit-border-radius:0;border-radius:0'
  

  Parameters

  property : String

  The CSS property name.

  value : String

  The CSS value.

  [ asString ] : Boolean

  If true, then the returned value will be a CSS string.

  Defaults to false

  Returns

  Object | String

  The object containing CSS properties or its stringified version.

  since 4.19.1

  debounce( func, [ milliseconds ] ) → FunctionCKEDITOR.tools#debounce

  See source

  Returns a new debounced version of the passed function that will postpone its execution until the given milliseconds have elapsed since the last time it was invoked.

  Parameters

  func : Function

  The function to be executed.

  [ milliseconds ] : Number

  The amount of time (in milliseconds) to wait to fire the function execution.

  Defaults to 0

  Returns

  Function

  defer( fn ) → FunctionCKEDITOR.tools#defer

  See source

  Creates a "deferred" function which will not run immediately, but rather runs as soon as the interpreter’s call stack is empty. Behaves much like window.setTimeout with a delay.

  Note: The return value of the original function will be lost.

  Parameters

  fn : Function

  The callee function.

  Returns

  Function

  The new deferred function.

  since 4.3.0

  enableHtml5Elements( doc, [ withAppend ] )CKEDITOR.tools#enableHtml5Elements

  See source

  Enables HTML5 elements for older browsers (IE8) in the passed document.

  In IE8 this method can also be executed on a document fragment.

  Note: This method has to be used in the <head> section of the document.

  Parameters

  doc : Object

  Native Document or DocumentFragment in which the elements will be enabled.

  [ withAppend ] : Boolean

  Whether to append created elements to the doc.

  since 4.5.10

  escapeCss( selector ) → StringCKEDITOR.tools#escapeCss

  See source

  Returns an escaped CSS selector. CSS.escape() is used if defined, leading digit is escaped otherwise.

  Parameters

  selector : String

  A CSS selector to escape.

  Returns

  String

  An escaped selector.

  since 4.2.1

  eventsBuffer( minInterval, output, [ contextObj ] ) → eventCKEDITOR.tools#eventsBuffer

  See source

  Creates an events buffer instance.

  See the input method's documentation for example code listings.

  Parameters

  minInterval : Number

  The minimum interval between output calls in milliseconds.

  output : Function

  The function that will be executed as output.

  [ contextObj ] : Object

  The object used as context to the listener call (the this object).

  Returns

  event

  extend( target, source, [ overwrite ], [ properties ] ) → ObjectCKEDITOR.tools#extend

  See source

  Copies the properties from one object to another. By default, properties already present in the target object are not overwritten.

  // Create the sample object.
  var myObject = {
      prop1: true
  };
  
  // Extend the above object with two properties.
  CKEDITOR.tools.extend( myObject, {
      prop2: true,
      prop3: true
  } );
  
  // Alert 'prop1', 'prop2' and 'prop3'.
  for ( var p in myObject )
      alert( p );
  

  Parameters

  target : Object

  The object to be extended.

  source : Object

  The object(s) from properties will be copied. Any number of objects can be passed to this function.

  [ overwrite ] : Boolean

  If true is specified, it indicates that properties already present in the target object could be overwritten by subsequent objects.

  [ properties ] : Object

  Only properties within the specified names list will be received from the source object.

  Returns

  Object

  The extended object (target).

  since 4.1.2

  fixDomain() → BooleanCKEDITOR.tools#fixDomain

  See source

  Tries to fix the document.domain of the current document to match the parent window domain, avoiding "Same Origin" policy issues. This is an Internet Explorer only requirement.

  Returns

  Boolean

  true if the current domain is already good or if it has been fixed successfully.

  genKey( subKey ) → StringCKEDITOR.tools#genKey

  See source

  Generates a combined key from a series of params.

  var key = CKEDITOR.tools.genKey( 'key1', 'key2', 'key3' );
  alert( key ); // 'key1-key2-key3'.
  

  Parameters

  subKey : String

  One or more strings used as subkeys.

  Returns

  String

  since 4.10.0

  getAbsoluteRectPosition( window, rect ) → CKEDITORCKEDITOR.tools#getAbsoluteRectPosition

  See source

  Converts relative positions inside a DOM rectangle into absolute ones using the given window as context. "Absolute" here means in relation to the upper-left corner of the topmost viewport.

  Parameters

  window : CKEDITOR

  The window containing an element for which the rectangle is passed.

  rect : CKEDITOR

  A rectangle with a relative position.

  Returns

  CKEDITOR

  A rectangle with an absolute position.

  since 4.5.6

  getCookie( name ) → StringCKEDITOR.tools#getCookie

  See source

  Returns the value of the cookie with a given name or null if the cookie is not found.

  Parameters

  name : String

  Returns

  String

  since 4.5.6

  getCsrfToken() → StringCKEDITOR.tools#getCsrfToken

  See source

  Returns the CSRF token value. The value is a hash stored in document.cookie under the ckCsrfToken key. The CSRF token can be used to secure the communication between the web browser and the server, i.e. for the file upload feature in the editor.

  Returns

  String

  since 4.5.0

  getIndex( array, compareFunction ) → NumberCKEDITOR.tools#getIndex

  See source

  Finds the index of the first element in an array for which the compareFunction returns true.

  CKEDITOR.tools.getIndex( [ 1, 2, 4, 3, 5 ], function( el ) {
      return el >= 3;
  } ); // 2
  

  Parameters

  array : Array

  Array to search in.

  compareFunction : Function

  Compare function.

  Returns

  Number

  The index of the first matching element or -1 if none matches.

  since 4.7.3

  getMouseButton( evt ) → BooleanCKEDITOR.tools#getMouseButton

  See source

  Detects which mouse button generated a given DOM event.

  Parameters

  evt : event | Event

  DOM event. Since 4.11.3 a native MouseEvent instance can be passed.

  Returns

  Boolean

  Returns a number indicating the mouse button or false if the mouse button cannot be determined.

  getNextId() → StringCKEDITOR.tools#getNextId

  See source

  Gets a unique ID for CKEditor interface elements. It returns a string with the "cke_" prefix and a consecutive number.

  alert( CKEDITOR.tools.getNextId() ); // (e.g.) 'cke_1'
  alert( CKEDITOR.tools.getNextId() ); // 'cke_2'
  

  Returns

  String

  A unique ID.

  getNextNumber() → NumberCKEDITOR.tools#getNextNumber

  See source

  Gets a unique number for this CKEDITOR execution session. It returns consecutive numbers starting from 1.

  alert( CKEDITOR.tools.getNextNumber() ); // (e.g.) 1
  alert( CKEDITOR.tools.getNextNumber() ); // 2
  

  Returns

  Number

  A unique number.

  since 4.15.0

  getStyledSpans( property, source ) → ArrayCKEDITOR.tools#getStyledSpans

  See source

  Finds all span elements styled with the given property in the editor contents.

  Parameters

  property : String

  CSS property which will be used in query.

  source : element

  The element to be searched.

  Returns

  Array

  Returns an array of CKEDITOR.dom.elements.

  getUniqueId() → StringCKEDITOR.tools#getUniqueId

  See source

  Gets a universally unique ID. It returns a random string compliant with ISO/IEC 11578:1996, without dashes, with the "e" prefix to make sure that the ID does not start with a number.

  Returns

  String

  A global unique ID.

  htmlDecode( The ) → StringCKEDITOR.tools#htmlDecode

  See source

  Decodes HTML entities that browsers tend to encode when used in text nodes.

  alert( CKEDITOR.tools.htmlDecode( '&lt;a &amp; b &gt;' ) ); // '<a & b >'
  

  Read more about chosen entities in the research.

  Parameters

  The : String

  string to be decoded.

  Returns

  String

  The decoded string.

  htmlDecodeAttr( text ) → StringCKEDITOR.tools#htmlDecodeAttr

  See source

  Decodes HTML entities that browsers tend to encode when used in attributes.

  alert( CKEDITOR.tools.htmlDecodeAttr( '&lt;a &quot; b&gt;' ) ); // '<a " b>'
  

  Since CKEditor 4.5.0 this method simply executes htmlDecode which covers all necessary entities.

  Parameters

  text : String

  The text to be decoded.

  Returns

  String

  The decoded text.

  htmlEncode( text ) → StringCKEDITOR.tools#htmlEncode

  See source

  Replaces special HTML characters in a string with their relative HTML entity values.

  alert( CKEDITOR.tools.htmlEncode( 'A > B & C < D' ) ); // 'A &gt; B &amp; C &lt; D'
  

  Parameters

  text : String

  The string to be encoded.

  Returns

  String

  The encoded string.

  htmlEncodeAttr( The ) → StringCKEDITOR.tools#htmlEncodeAttr

  See source

  Replaces special HTML characters in HTMLElement attribute with their relative HTML entity values.

  alert( CKEDITOR.tools.htmlEncodeAttr( '<a " b >' ) ); // '&lt;a &quot; b &gt;'
  

  Parameters

  The : String

  attribute value to be encoded.

  Returns

  String

  The encoded value.

  indexOf( array, value ) → NumberCKEDITOR.tools#indexOf

  See source

  Returns the index of an element in an array.

  var letters = [ 'a', 'b', 0, 'c', false ];
  alert( CKEDITOR.tools.indexOf( letters, '0' ) );        // -1 because 0 !== '0'
  alert( CKEDITOR.tools.indexOf( letters, false ) );      // 4 because 0 !== false
  

  Parameters

  array : Array

  The array to be searched.

  value : Object | Function

  The element to be found. This can be an evaluation function which receives a single parameter call for each entry in the array, returning true if the entry matches.

  Returns

  Number

  The (zero-based) index of the first entry that matches the entry, or -1 if not found.

  isArray( object ) → BooleanCKEDITOR.tools#isArray

  See source

  Checks if an object is an Array.

  alert( CKEDITOR.tools.isArray( [] ) );      // true
  alert( CKEDITOR.tools.isArray( 'Test' ) );  // false
  

  Parameters

  object : Object

  The object to be checked.

  Returns

  Boolean

  true if the object is an Array, otherwise false.

  isEmpty( object ) → BooleanCKEDITOR.tools#isEmpty

  See source

  Whether the object contains no properties of its own.

  Parameters

  object : Object

  Returns

  Boolean

  since 4.8.0

  keystrokeToArray( lang, keystroke ) → ObjectCKEDITOR.tools#keystrokeToArray

  See source

  Converts a keystroke to its string representation.

  var lang = editor.lang.common.keyboard;
  var shortcut = CKEDITOR.tools.keystrokeToArray( lang, CKEDITOR.CTRL + 88 );
  console.log( shortcut.display ); // [ 'CTRL', 'X' ], on Mac [ '⌘', 'X' ].
  console.log( shortcut.aria ); // [ 'CTRL', 'X' ], on Mac [ 'COMMAND', 'X' ].
  

  Parameters

  lang : Object

  A language object with the key name translation.

  keystroke : Number

  The keystroke to convert.

  Returns

  Object

  Properties

  display : String[]

  An array of strings that should be used for visible labels. For Mac devices it uses ⌥ for Alt, ⇧ for Shift and ⌘ for Command.

  aria : String[]

  An array of strings that should be used for ARIA descriptions. It does not use special characters such as ⌥, ⇧ or ⌘.

  since 4.6.0

  keystrokeToString( lang, keystroke ) → ObjectCKEDITOR.tools#keystrokeToString

  See source

  Converts a keystroke to its string representation. Returns exactly the same members as keystrokeToArray, but the returned object contains strings of keys joined with "+" rather than an array of keystrokes.

  var lang = editor.lang.common.keyboard;
  var shortcut = CKEDITOR.tools.keystrokeToString( lang, CKEDITOR.CTRL + 88 );
  console.log( shortcut.display ); // 'Ctrl + X', on Mac '⌘ + X'.
  console.log( shortcut.aria ); // 'Ctrl + X', on Mac 'Cmd + X'.
  

  Parameters

  lang : Object

  A language object with the key name translation.

  keystroke : Number

  The keystroke to convert.

  Returns

  Object

  See keystrokeToArray.

  Properties

  display : String

  aria : String

  ltrim( str ) → StringCKEDITOR.tools#ltrim

  See source

  Removes spaces from the start (left) of a string. The following characters are removed: space, tab, line break, line feed.

  alert( CKEDITOR.tools.ltrim( '  example ' ); // 'example '
  

  Parameters

  str : String

  The text from which the spaces will be removed.

  Returns

  String

  The modified string excluding the removed spaces.

  normalizeCssText( styleText, [ nativeNormalize ] ) → StringCKEDITOR.tools#normalizeCssText

  See source

  Normalizes CSS data in order to avoid differences in the style attribute.

  Parameters

  styleText : String

  The style data to be normalized.

  [ nativeNormalize ] : Boolean

  Parse the data using the browser.

  Defaults to false

  Returns

  String

  The normalized value.

  deprecated 4.16.0

  normalizeHex( styleText ) → StringCKEDITOR.tools#normalizeHex

  See source

  Normalizes hexadecimal notation so that the color string is always 6 characters long and lowercase.

  Note: This method is deprecated, instead use CKEDITOR.tools.color to create color and CKEDITOR.tools.color.getHex method to get its hexadecimal representation. Since it returns uppercase string, use toLowerCase() to get lowercase representation:

  var color = new CKEDITOR.tools.color( '#FFF' ); // Create color instance.
  console.log( color.getHex().toLowerCase() ); // #ffffff
  

  Parameters

  styleText : String

  The style data (or just a string containing hex colors) to be converted.

  Returns

  String

  The style data with hex colors normalized.

  since 4.13.0

  normalizeMouseButton( button, [ reverse ] ) → NumberCKEDITOR.tools#normalizeMouseButton

  See source

  Normalizes mouse buttons across browsers.

  Only Internet Explorer 8 and Internet Explorer 9 in Quirks Mode or Compatibility View have different button mappings than other browsers:

  +--------------+--------------------------+----------------+
  | Mouse button | IE 8 / IE 9 CM / IE 9 QM | Other browsers |
  +--------------+--------------------------+----------------+
  | Left         |             1            |        0       |
  +--------------+--------------------------+----------------+
  | Middle       |             4            |        1       |
  +--------------+--------------------------+----------------+
  | Right        |             2            |        2       |
  +--------------+--------------------------+----------------+
  

  The normalization is conducted only in browsers that use non-standard button mappings, returning the passed parameter in every other browser. Therefore values for IE < 9 are mapped to values used in the rest of the browsers. For example, the code below will return the following results in IE8:

  console.log( CKEDITOR.tools.normalizeMouseButton( 1 ) ); // 0
  console.log( CKEDITOR.tools.normalizeMouseButton( 4 ) ); // 1
  console.log( CKEDITOR.tools.normalizeMouseButton( 2 ) ); // 2
  

  In other browsers it will simply return the passed values.

  With the reversed parameter set to true, values from the rest of the browsers are mapped to IE < 9 values in IE < 9 browsers. This means that IE8 will return the following results:

  console.log( CKEDITOR.tools.normalizeMouseButton( 0, true ) ); // 1
  console.log( CKEDITOR.tools.normalizeMouseButton( 1, true ) ); // 4
  console.log( CKEDITOR.tools.normalizeMouseButton( 2, true ) ); // 2
  

  In other browsers it will simply return the passed values.

  Parameters

  button : Number

  Mouse button identifier.

  [ reverse ] : Boolean

  If set to true, the conversion is reversed: values returned by other browsers are converted to IE8 values.

  Defaults to false

  Returns

  Number

  Normalized mouse button identifier.

  since 4.1.0

  objectCompare( left, right, [ onlyLeft ] ) → BooleanCKEDITOR.tools#objectCompare

  See source

  Compares two objects.

  Note: This method performs shallow, non-strict comparison.

  Parameters

  left : Object

  right : Object

  [ onlyLeft ] : Boolean

  Check only the properties that are present in the left object.

  Returns

  Boolean

  Whether objects are identical.

  since 4.1.0 deprecated 4.12.0

  objectKeys( obj ) → ArrayCKEDITOR.tools#objectKeys

  See source

  Returns an array of passed object keys.

  console.log( CKEDITOR.tools.object.keys( { foo: 1, bar: false } );
  // -> [ 'foo', 'bar' ]
  

  Parameters

  obj : Object

  Returns

  Array

  Object's keys.

  override( originalFunction, functionBuilder ) → FunctionCKEDITOR.tools#override

  See source

  Creates a function override.

  var obj = {
      myFunction: function( name ) {
          alert( 'Name: ' + name );
      }
  };
  
  obj.myFunction = CKEDITOR.tools.override( obj.myFunction, function( myFunctionOriginal ) {
      return function( name ) {
          alert( 'Overriden name: ' + name );
          myFunctionOriginal.call( this, name );
      };
  } );
  

  Parameters

  originalFunction : Function

  The function to be overridden.

  functionBuilder : Function

  A function that returns the new function. The original function reference will be passed to this function.

  Returns

  Function

  The new function.

  parseCssText( styleText, [ normalize ], [ nativeNormalize ] ) → ObjectCKEDITOR.tools#parseCssText

  See source

  Turns inline style text properties into one hash.

  Parameters

  styleText : String

  The style data to be parsed.

  [ normalize ] : Boolean

  Normalize properties and values (e.g. trim spaces, convert to lower case).

  Defaults to false

  [ nativeNormalize ] : Boolean

  Parse the data using the browser.

  Defaults to false

  Returns

  Object

  The object containing parsed properties.

  prototypedCopy( source ) → ObjectCKEDITOR.tools#prototypedCopy

  See source

  Creates an object which is an instance of a class whose prototype is a predefined object. All properties defined in the source object are automatically inherited by the resulting object, including future changes to it.

  Parameters

  source : Object

  The source object to be used as the prototype for the final object.

  Returns

  Object

  The resulting copy.

  removeFunction( ref )CKEDITOR.tools#removeFunction

  See source

  Removes the function reference created with addFunction.

  Parameters

  ref : Number

  The function reference created with addFunction.

  repeat( str, times ) → StringCKEDITOR.tools#repeat

  See source

  String specified by str repeats times times.

  Parameters

  str : String

  times : Number

  Returns

  String

  rtrim( str ) → StringCKEDITOR.tools#rtrim

  See source

  Removes spaces from the end (right) of a string. The following characters are removed: space, tab, line break, line feed.

  alert( CKEDITOR.tools.ltrim( '  example ' ); // '  example'
  

  Parameters

  str : String

  The text from which spaces will be removed.

  Returns

  String

  The modified string excluding the removed spaces.

  search( array, value ) → ObjectCKEDITOR.tools#search

  See source

  Returns the index of an element in an array.

  var obj = { prop: true };
  var letters = [ 'a', 'b', 0, obj, false ];
  
  alert( CKEDITOR.tools.indexOf( letters, '0' ) ); // null
  alert( CKEDITOR.tools.indexOf( letters, function( value ) {
      // Return true when passed value has property 'prop'.
      return value && 'prop' in value;
  } ) );                                          // obj
  

  Parameters

  array : Array

  The array to be searched.

  value : Object | Function

  The element to be found. Can be an evaluation function which receives a single parameter call for each entry in the array, returning true if the entry matches.

  Returns

  Object

  Object The value that was found in an array.

  since 4.5.6

  setCookie( name, value )CKEDITOR.tools#setCookie

  See source

  Sets the value of the cookie with a given name.

  Parameters

  name : String

  value : String

  setTimeout( func, [ milliseconds ], [ scope ], [ args ], [ ownerWindow ] ) → ObjectCKEDITOR.tools#setTimeout

  See source

  Executes a function after a specified delay.

  CKEDITOR.tools.setTimeout( function() {
      alert( 'Executed after 2 seconds' );
  }, 2000 );
  

  Parameters

  func : Function

  The function to be executed.

  [ milliseconds ] : Number

  The amount of time (in milliseconds) to wait to fire the function execution.

  Defaults to 0

  [ scope ] : Object

  The object to store the function execution scope (the this object).

  Defaults to window

  [ args ] : Object | Array

  A single object, or an array of objects, to pass as argument to the function.

  [ ownerWindow ] : Object

  The window that will be used to set the timeout.

  Defaults to window

  Returns

  Object

  A value that can be used to cancel the function execution.

  since 4.10.0

  throttle( minInterval, output, [ contextObj ] ) → throttleCKEDITOR.tools#throttle

  See source

  Creates a throttle buffer instance.

  See the input method's documentation for example listings.

  Parameters

  minInterval : Number

  The minimum interval between output calls in milliseconds.

  output : Function

  The function that will be executed as output.

  [ contextObj ] : Object

  The object used as context to the listener call (the this object).

  Returns

  throttle

  since 4.5.0

  transformPlainTextToHtml( text, enterMode ) → StringCKEDITOR.tools#transformPlainTextToHtml

  See source

  Transforms text to valid HTML: creates paragraphs, replaces tabs with non-breaking spaces etc.

  Parameters

  text : String

  Text to transform.

  enterMode : Number

  Editor Enter mode.

  Returns

  String

  HTML generated from the text.

  trim( str ) → StringCKEDITOR.tools#trim

  See source

  Removes spaces from the start and the end of a string. The following characters are removed: space, tab, line break, line feed.

  alert( CKEDITOR.tools.trim( '  example ' ); // 'example'
  

  Parameters

  str : String

  The text from which the spaces will be removed.

  Returns

  String

  The modified string without the boundary spaces.

  tryThese( fn ) → MixedCKEDITOR.tools#tryThese

  See source

  Returns the first successfully executed return value of a function that does not throw any exception.

  Parameters

  fn : Function

  Returns

  Mixed

  since 4.1.0

  writeCssText( styles, [ sort ] ) → StringCKEDITOR.tools#writeCssText

  See source

  Serializes the style name => value hash to a style text.

  var styleObj = CKEDITOR.tools.parseCssText( 'color: red; border: none' );
  console.log( styleObj.color ); // -> 'red'
  CKEDITOR.tools.writeCssText( styleObj ); // -> 'color:red; border:none'
  CKEDITOR.tools.writeCssText( styleObj, true ); // -> 'border:none; color:red'
  

  Parameters

  styles : Object

  The object contaning style properties.

  [ sort ] : Boolean

  Whether to sort CSS properties.

  Returns

  String

  The serialized style text.

  since 4.15.1 deprecated 4.16.0 private

  _isValidColorFormat( colorCode ) → BooleanCKEDITOR.tools#_isValidColorFormat

  See source

  Validates color string correctness. Works for:

  • hexadecimal notation,
  • RGB or RGBA notation,
  • HSL or HSLA notation,
  • HTML color name.

  Note: This method is deprecated, instead use use CKEDITOR.tools.color to create color class and check if passed color string is valid.

  Note: This method is intended mostly for the input validations. It performs no logical check e.g.: are the values in RGB format correct or does the passed color name actually exists?

  See the examples below:

  CKEDITOR.tools._isValidColorFormat( '123456' ); // true
  CKEDITOR.tools._isValidColorFormat( '#4A2' ); // true
  CKEDITOR.tools._isValidColorFormat( 'rgb( 40, 40, 150 )' ); // true
  CKEDITOR.tools._isValidColorFormat( 'hsla( 180, 50%, 50%, 0.2 )' ); // true
  
  CKEDITOR.tools._isValidColorFormat( '333333;' ); // false
  CKEDITOR.tools._isValidColorFormat( '<833AF2>' ); // false
  
  // But also:
  CKEDITOR.tools._isValidColorFormat( 'ckeditor' ); // true
  CKEDITOR.tools._isValidColorFormat( '1234' ); // true
  CKEDITOR.tools._isValidColorFormat( 'hsrgb( 100 )' ); // true
  

  Parameters

  colorCode : String

  String to be validated.

  Returns

  Boolean

  Whether the input string contains only allowed characters.