CKEDITOR.plugins.clipboard

Properties

• since 4.5.0 readonly

  isCustomCopyCutSupported : BooleanCKEDITOR.plugins.clipboard#isCustomCopyCutSupported

  See source

  It returns true if the environment allows setting the data on copy or cut manually. This value is false in: * Internet Explorer — because this browser shows the security dialog window when the script tries to set clipboard data. * Older iOS (below version 13) — because custom data is not saved to clipboard there.

• since 4.5.0 readonly

  isCustomDataTypesSupported : BooleanCKEDITOR.plugins.clipboard#isCustomDataTypesSupported

  See source

  True if the environment supports MIME types and custom data types in dataTransfer/cliboardData getData/setData methods.

• since 4.5.0 readonly

  isFileApiSupported : BooleanCKEDITOR.plugins.clipboard#isFileApiSupported

  See source

  True if the environment supports File API.

• since 4.5.0 readonly

  mainPasteEvent : StringCKEDITOR.plugins.clipboard#mainPasteEvent

  See source

  Main native paste event editable should listen to.

  Note: Safari does not like the CKEDITOR.editor.beforePaste event — it sometimes does not handle Ctrl+C properly. This is probably caused by some race condition between events. Chrome, Firefox and Edge work well with both events, so it is better to use CKEDITOR.editor.paste which will handle pasting from e.g. browsers' menu bars. IE7/8 does not like the CKEDITOR.editor.paste event for which it is throwing random errors.

• since 4.5.0 private

  dragData : dataTransferCKEDITOR.plugins.clipboard#dragData

  See source

  Global object storing the data transfer of the current drag and drop operation. Do not use it directly, use initDragDataTransfer and resetDragDataTransfer.

  Note: This object is global (meaning that it is not related to a single editor instance) in order to handle drag and drop from one editor into another.

• since 4.5.0 private

  dragRange : rangeCKEDITOR.plugins.clipboard#dragRange

  See source

  Range object to save the drag range and remove its content after the drop.

Methods

• since 4.19.0

  addFileMatcher( editor, matcher )CKEDITOR.plugins.clipboard#addFileMatcher

  See source

  Adds a file matcher verifying whether a file should be supported via clipboard operations.

  In case of pasting or dragging and dropping unsupported files, the clipboard plugin will show a notification informing a user that a given file type is not supported.

  CKEDITOR.plugins.clipboard.addFileMatcher( editor, function( file ) {
      var supportedImageTypes = [ 'image/png', 'image/jpeg', 'image/gif' ];
      return CKEDITOR.tools.indexOf( supportedImageTypes, file.type ) !== -1;
  } );
  

  Note: This feature will not cancel the paste event in case of an unsupported file. It is the integrator's responsibility to properly handle incorrect files (e.g. by verifying if the file should be indeed uploaded via upload integrations).

  Parameters

  editor : editor

  The editor instance.

  matcher : Function

  File matcher.

  since 4.9.0

  addPasteButton( editor, name, definition )CKEDITOR.plugins.clipboard#addPasteButton

  See source

  Adds a new paste button to the editor.

  This method should be called for buttons that should display the Paste Dialog fallback in mobile environments. See the rationale for more details.

  Parameters

  editor : editor

  The editor instance.

  name : String

  Name of the button.

  definition : Object

  Definition of the button.

  since 4.5.2

  canClipboardApiBeTrusted( dataTransfer, editor ) → BooleanCKEDITOR.plugins.clipboard#canClipboardApiBeTrusted

  See source

  Returns true if it is expected that a browser provides HTML data through the Clipboard API. If not, this method returns false and as a result CKEditor will use the paste bin. Read more in the Clipboard Integration guide.

  Parameters

  dataTransfer : Object

  editor : Object

  Returns

  Boolean

  since 4.5.0

  getDropTarget( editor ) → domObjectCKEDITOR.plugins.clipboard#getDropTarget

  See source

  Returns the element that should be used as the target for the drop event.

  Parameters

  editor : editor

  The editor instance.

  Returns

  domObject

  the element that should be used as the target for the drop event.

  since 4.5.0

  getRangeAtDropPosition( domEvent, editor ) → rangeCKEDITOR.plugins.clipboard#getRangeAtDropPosition

  See source

  Gets the range from the drop event.

  Parameters

  domEvent : Object

  A native DOM drop event object.

  editor : editor

  The source editor instance.

  Returns

  range

  range at drop position.

  since 4.5.0

  initDragDataTransfer( [ evt ], [ sourceEditor ] )CKEDITOR.plugins.clipboard#initDragDataTransfer

  See source

  This function tries to link the evt.data.dataTransfer property of the CKEDITOR.editor.dragstart, CKEDITOR.editor.dragend and CKEDITOR.editor.drop events to a single CKEDITOR.plugins.clipboard.dataTransfer object.

  This method is automatically used by the core of the drag and drop functionality and usually does not have to be called manually when using the drag and drop events.

  This method behaves differently depending on whether the drag and drop events were fired artificially (to represent a non-native drag and drop) or whether they were caused by the native drag and drop.

  If the native event is not available, then it will create a new CKEDITOR.plugins.clipboard.dataTransfer instance (if it does not exist already) and will link it to this and all following event objects until the resetDragDataTransfer method is called. It means that all three drag and drop events must be fired in order to ensure that the data transfer is bound correctly.

  If the native event is available, then the CKEDITOR.plugins.clipboard.dataTransfer is identified by its ID and a new instance is assigned to the evt.data.dataTransfer only if the ID changed or the resetDragDataTransfer method was called.

  Parameters

  [ evt ] : event

  A drop event object.

  [ sourceEditor ] : editor

  The source editor instance.

  since 4.5.0

  initPasteDataTransfer( [ evt ], [ sourceEditor ] ) → dataTransferCKEDITOR.plugins.clipboard#initPasteDataTransfer

  See source

  Initializes and links data transfer objects based on the paste event. If the data transfer object was already initialized on this event, the function will return that object. In IE it is not possible to link copy/cut and paste events so the method always returns a new object. The same happens if there is no paste event passed to the method.

  Parameters

  [ evt ] : event

  A paste event object.

  [ sourceEditor ] : editor

  The source editor instance.

  Returns

  dataTransfer

  The data transfer object.

  since 4.5.0

  preventDefaultDropOnElement( element )CKEDITOR.plugins.clipboard#preventDefaultDropOnElement

  See source

  Prevents dropping on the specified element.

  Parameters

  element : element

  The element on which dropping should be disabled.

  since 4.5.0

  resetDragDataTransfer()CKEDITOR.plugins.clipboard#resetDragDataTransfer

  See source

  Removes the global dragData so the next call to initDragDataTransfer always creates a new instance of CKEDITOR.plugins.clipboard.dataTransfer.

  since 4.5.0 private

  fixSplitNodesAfterDrop( dragRange, dropRange, preDragStartContainerChildCount, preDragEndContainerChildCount )CKEDITOR.plugins.clipboard#fixSplitNodesAfterDrop

  See source

  IE 8 & 9 split text node on drop so the first node contains the text before the drop position and the second contains the rest. If you drag the content from the same node you will be not be able to get it (the range becomes invalid), so you need to join them back.

  Note that the first node in IE 8 & 9 is the original node object but with shortened content.

  Before:
    --- Text Node A ----------------------------------
                                               /\
                                          Drag position
  
  After (IE 8 & 9):
    --- Text Node A -----  --- Text Node B -----------
                         /\                    /\
                    Drop position        Drag position
                                           (invalid)
  
  After (other browsers):
    --- Text Node A ----------------------------------
                         /\                    /\
                    Drop position        Drag position
  

  Note: This function is in the public scope for tests usage only.

  Parameters

  dragRange : range

  The drag range.

  dropRange : range

  The drop range.

  preDragStartContainerChildCount : Number

  The number of children of the drag range start container before the drop.

  preDragEndContainerChildCount : Number

  The number of children of the drag range end container before the drop.

  since 4.5.0 private

  internalDrop( dragRange, dropRange, dataTransfer, editor )CKEDITOR.plugins.clipboard#internalDrop

  See source

  Internal drag and drop (drag and drop in the same editor instance).

  Note: This function is in the public scope for tests usage only.

  Parameters

  dragRange : range

  The first range to compare.

  dropRange : range

  The second range to compare.

  dataTransfer : dataTransfer

  editor : editor

  since 4.5.0 private

  isDropRangeAffectedByDragRange( dragRange, dropRange ) → BooleanCKEDITOR.plugins.clipboard#isDropRangeAffectedByDragRange

  See source

  Checks whether turning the drag range into bookmarks will invalidate the drop range. This usually happens when the drop range shares the container with the drag range and is located after the drag range, but there are countless edge cases.

  This function is stricly related to internalDrop which toggles order in which it creates bookmarks for both ranges based on a value returned by this method. In some cases this method returns a value which is not necessarily true in terms of what it was meant to check, but it is convenient, because we know how it is interpreted in internalDrop, so the correct behavior of the entire algorithm is assured.

  Note: This function is in the public scope for tests usage only.

  Parameters

  dragRange : range

  The first range to compare.

  dropRange : range

  The second range to compare.

  Returns

  Boolean

  true if the first range is before the second range.