CKEditor 4
Report an issue
Class

CKEDITOR.plugins.clipboard

class singleton

Filtering

Properties

  • isCustomCopyCutSupported : Boolean

    since 4.5 readonly

    True if the environment allows to set data on copy or cut manually. This value is false in IE, because this browser shows the security dialog window when the script tries to set clipboard data and on iOS, because custom data is not saved to clipboard there.

  • isCustomDataTypesSupported : Boolean

    since 4.5 readonly

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

  • isFileApiSupported : Boolean

    since 4.5 readonly

    True if the environment supports File API.

  • mainPasteEvent : String

    since 4.5 readonly

    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.

  • dragData : dataTransfer

    since 4.5 private

    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.

  • dragRange : range

    since 4.5 private

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

Methods

  • addPasteButton( editor, name, definition )

    since 4.9.0

    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.

  • canClipboardApiBeTrusted( dataTransfer, editor ) → Boolean

    since 4.5.2

    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

  • getDropTarget( editor ) → domObject

    since 4.5

    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.

  • getRangeAtDropPosition( domEvent, editor ) → range

    since 4.5

    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.

  • initDragDataTransfer( [ evt ], [ sourceEditor ] )

    since 4.5

    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.

  • initPasteDataTransfer( [ evt ], [ sourceEditor ] ) → dataTransfer

    since 4.5

    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.

  • preventDefaultDropOnElement( element )

    since 4.5

    Prevents dropping on the specified element.

    Parameters

    element : element

    The element on which dropping should be disabled.

  • resetDragDataTransfer()

    since 4.5

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

  • fixSplitNodesAfterDrop( dragRange, dropRange, preDragStartContainerChildCount, preDragEndContainerChildCount )

    since 4.5 private

    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.

  • internalDrop( dragRange, dropRange, dataTransfer, editor )

    since 4.5 private

    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

  • isDropRangeAffectedByDragRange( dragRange, dropRange ) → Boolean

    since 4.5 private

    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.