Browse Source

API docs.

Piotrek Koszuliński 9 years ago
parent
commit
589e8c6eb1

+ 68 - 8
packages/ckeditor5-clipboard/src/clipboard.js

@@ -16,9 +16,9 @@ import HtmlDataProcessor from '../engine/dataprocessor/htmldataprocessor.js';
  * The clipboard feature. Currently, it's only responsible for intercepting the `paste` event and
  * passing the pasted content through the clipboard pipeline.
  *
- * ## Clipboard Pipeline
+ * ## Clipboard input pipeline
  *
- * The feature creates the clipboard pipeline which allows for processing clipboard content
+ * The feature creates the clipboard input pipeline which allows for processing clipboard content
  * before it gets inserted into the editor. The pipeline consists of two events on which
  * the features can listen in order to modify or totally override the default behavior.
  *
@@ -27,9 +27,9 @@ import HtmlDataProcessor from '../engine/dataprocessor/htmldataprocessor.js';
  * The default action is to:
  *
  * 1. get HTML or plain text from the clipboard,
- * 2. fire {@link engine.view.Document#clipboardInput} with the clipboard data parsed to
- * a {@link engine.view.DocumentFragment view document fragment},
- * 3. prevent the default action of the native `paste` event.
+ * 2. prevent the default action of the native `paste` event,
+ * 3. fire {@link engine.view.Document#clipboardInput} with the clipboard data parsed to
+ * a {@link engine.view.DocumentFragment view document fragment}.
  *
  * This action is performed by a low priority listener, so it can be overridden by a normal one.
  * You'd only need to do this when a deeper change in pasting behavior was needed. For example,
@@ -60,6 +60,30 @@ import HtmlDataProcessor from '../engine/dataprocessor/htmldataprocessor.js';
  *			}
  *		} );
  *
+ * ## Clipboard output pipeline
+ *
+ * The output pipeline is the equivalent of the input pipeline but for the copy and cut operations.
+ * It allows to process the content which will be then put into the clipboard or overriding the whole process.
+ *
+ * ### On {@link engine.view.Document#copy} and {@link engine.view.Document#cut}
+ *
+ * The default action is to:
+ *
+ * 1. {@link engine.controller.DataController#getSelectedContent get selected content} from the editor,
+ * 2. prevent the default action of the native `copy` or `cut` event,
+ * 3. fire {@link engine.view.Document#clipboardOutput} with a clone of the selected content
+ * converted to a {@link engine.view.DocumentFragment view document fragment},
+ * 4. in case of cut operation, delete the selected content.
+ *
+ * ### On {@link engine.view.Document#clipboardOutput}
+ *
+ * The default action is to put the content (`data.content`, represented by a {@link engine.view.DocumentFragment})
+ * to the clipboard as HTML.
+ *
+ * This action is performed by a low priority listener, so it can be overridden by a normal one.
+ *
+ * At this stage the copied/cut content can be processed by the features.
+ *
  * @memberOf clipboard
  * @extends core.Feature
  */
@@ -127,6 +151,12 @@ export default class Clipboard extends Feature {
 			data.preventDefault();
 
 			editingView.fire( 'clipboardOutput', { dataTransfer, content } );
+
+			if ( evt.name == 'cut' ) {
+				doc.enqueueChanges( () => {
+					editor.data.deleteContent( doc.selection, doc.batch(), { merge: true } );
+				} );
+			}
 		};
 
 		this.listenTo( editingView, 'copy', onCopyCut, { priority: 'low' } );
@@ -161,12 +191,42 @@ export default class Clipboard extends Feature {
  * Data transfer instance.
  *
  * @readonly
- * @member {clipboard.DataTransfer} engine.view.observer.ClipboardEventData#dataTransfer
+ * @member {clipboard.DataTransfer} engine.view.observer.ClipboardInputEventData#dataTransfer
  */
 
 /**
  * Content to be inserted into the editor. It can be modified by the event listeners.
- * Read more about the clipboard pipeline in {@link clipboard.Clipboard}.
+ * Read more about the clipboard pipelines in {@link clipboard.Clipboard}.
+ *
+ * @member {engine.view.DocumentFragment} engine.view.observer.ClipboardInputEventData#content
+ */
+
+/**
+ * Fired on {@link envine.view.Document#copy} and {@link envine.view.Document#cut} with a copy of selected content.
+ * The content can be processed before it ends up in the clipboard. It's part of the {@link clipboard.Clipboard "clipboard pipeline"}.
+ *
+ * @see clipboard.ClipboardObserver
+ * @see clipboard.Clipboard
+ * @event engine.view.Document#clipboardOutput
+ * @param {engine.view.observer.ClipboardOutputEventData} data Event data.
+ */
+
+/**
+ * The value of the {@link engine.view.Document#clipboardOutput} event.
+ *
+ * @class engine.view.observer.ClipboardOutputEventData
+ */
+
+/**
+ * Data transfer instance.
+ *
+ * @readonly
+ * @member {clipboard.DataTransfer} engine.view.observer.ClipboardOutputEventData#dataTransfer
+ */
+
+/**
+ * Content to be put into the clipboard. It can be modified by the event listeners.
+ * Read more about the clipboard pipelines in {@link clipboard.Clipboard}.
  *
- * @member {engine.view.DocumentFragment} engine.view.observer.ClipboardEventData#content
+ * @member {engine.view.DocumentFragment} engine.view.observer.ClipboardOutputEventData#content
  */

+ 29 - 1
packages/ckeditor5-clipboard/src/clipboardobserver.js

@@ -44,7 +44,35 @@ export default class ClipboardObserver extends DomEventObserver {
  */
 
 /**
- * The value of the {@link engine.view.Document#paste} event.
+ * Fired when user copied content from one of the editables.
+ *
+ * Introduced by {@link clipboard.ClipboardObserver}.
+ *
+ * Note that this event is not available by default. To make it available {@link clipboard.ClipboardObserver} needs to be added
+ * to {@link engine.view.Document} by the {@link engine.view.Document#addObserver} method.
+ * It's done by the {@link clipboard.Clipboard} feature. If it's not loaded, it must be done manually.
+ *
+ * @see clipboard.ClipboardObserver
+ * @event engine.view.Document#copy
+ * @param {engine.view.observer.ClipboardEventData} data Event data.
+ */
+
+/**
+ * Fired when user cut content from one of the editables.
+ *
+ * Introduced by {@link clipboard.ClipboardObserver}.
+ *
+ * Note that this event is not available by default. To make it available {@link clipboard.ClipboardObserver} needs to be added
+ * to {@link engine.view.Document} by the {@link engine.view.Document#addObserver} method.
+ * It's done by the {@link clipboard.Clipboard} feature. If it's not loaded, it must be done manually.
+ *
+ * @see clipboard.ClipboardObserver
+ * @event engine.view.Document#cut
+ * @param {engine.view.observer.ClipboardEventData} data Event data.
+ */
+
+/**
+ * The value of the {@link engine.view.Document#paste}, {@link engine.view.Document#copy} and {@link engine.view.Document#cut} events.
  *
  * In order to access clipboard data use {@link #dataTransfer}.
  *

+ 6 - 0
packages/ckeditor5-clipboard/src/datatransfer.js

@@ -31,6 +31,12 @@ export default class DataTransfer {
 		return this._native.getData( type );
 	}
 
+	/**
+	 * Sets data in the data transfer.
+	 *
+	 * @param {String} type The mime type. E.g. `text/html` or `text/plain`.
+	 * @param {String} data
+	 */
 	setData( type, data ) {
 		this._native.setData( type, data );
 	}