Report an issue
Class

CKEDITOR.plugins.clipboard

class singleton

Filtering

Properties

  • since 4.5.0 readonly

    isCustomCopyCutSupported : Boolean

    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 : Boolean

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

  • since 4.5.0 readonly

    isFileApiSupported : Boolean

    True if the environment supports File API.

  • since 4.5.0 readonly

    mainPasteEvent : String

    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 : dataTransfer

    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 : range

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

Methods

  • since 4.19.0

    addFileMatcher( editor, matcher )

    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 )

    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 ) → Boolean

    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 ) → domObject

    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 ) → range

    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 ] )

    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 ] ) → dataTransfer

    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 )

    Prevents dropping on the specified element.

    Parameters

    element : element

    The element on which dropping should be disabled.

  • since 4.5.0

    resetDragDataTransfer()

    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 )

    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 )

    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 ) → Boolean

    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.