[perso/Immae/Projets/packagist/connexionswing-ckeditor-component.git] / sources / core / commanddefinition.js

/**
 * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
 * For licensing, see LICENSE.md or http://ckeditor.com/license
 */

/**
 * @fileOverview Defines the "virtual" {@link CKEDITOR.commandDefinition} class,
 *		which contains the defintion of a command. This file is for
 *		documentation purposes only.
 */

/**
 * Virtual class that illustrates the features of command objects to be
 * passed to the {@link CKEDITOR.editor#addCommand} function.
 *
 * @class CKEDITOR.commandDefinition
 * @abstract
 */

/**
 * The function to be fired when the commend is executed.
 *
 *		editorInstance.addCommand( 'sample', {
 *			exec: function( editor ) {
 *				alert( 'Executing a command for the editor name "' + editor.name + '"!' );
 *			}
 *		} );
 *
 * @method exec
 * @param {CKEDITOR.editor} editor The editor within which run the command.
 * @param {Object} [data] Additional data to be used to execute the command.
 * @returns {Boolean} Whether the command has been successfully executed.
 * Defaults to `true`, if nothing is returned.
 */

/**
 * Whether the command need to be hooked into the redo/undo system.
 *
 *		editorInstance.addCommand( 'alertName', {
 *			exec: function( editor ) {
 *				alert( editor.name );
 *			},
 *			canUndo: false // No support for undo/redo.
 *		} );
 *
 * @property {Boolean} [canUndo=true]
 */

/**
 * Whether the command is asynchronous, which means that the
 * {@link CKEDITOR.editor#event-afterCommandExec} event will be fired by the
 * command itself manually, and that the return value of this command is not to
 * be returned by the {@link #exec} function.
 *
 * 		editorInstance.addCommand( 'loadOptions', {
 * 			exec: function( editor ) {
 * 				// Asynchronous operation below.
 * 				CKEDITOR.ajax.loadXml( 'data.xml', function() {
 * 					editor.fire( 'afterCommandExec' );
 * 				} );
 * 			},
 * 			async: true // The command need some time to complete after exec function returns.
 * 		} );
 *
 * @property {Boolean} [async=false]
 */

/**
 * Whether the command should give focus to the editor before execution.
 *
 *		editorInstance.addCommand( 'maximize', {
 *				exec: function( editor ) {
 *				// ...
 *			},
 *			editorFocus: false // The command doesn't require focusing the editing document.
 *		} );
 *
 * See also {@link CKEDITOR.command#editorFocus}.
 *
 * @property {Boolean} [editorFocus=true]
 */


/**
 * Whether the command state should be set to {@link CKEDITOR#TRISTATE_DISABLED} on startup.
 *
 *		editorInstance.addCommand( 'unlink', {
 *			exec: function( editor ) {
 *				// ...
 *			},
 *			startDisabled: true // Command is unavailable until selection is inside a link.
 *		} );
 *
 * @property {Boolean} [startDisabled=false]
 */

/**
 * Indicates that this command is sensible to the selection context.
 * If `true`, the {@link CKEDITOR.command#method-refresh} method will be
 * called for this command on selection changes, with a single parameter
 * representing the current elements path.
 *
 * @property {Boolean} [contextSensitive=true]
 */

/**
 * Defined by command definition a function to determinate the command state, it will be invoked
 * when editor has it's `states` or `selection` changed.
 *
 * **Note:** The function provided must be calling {@link CKEDITOR.command#setState} in all circumstance,
 * if it is intended to update the command state.
 *
 * @method refresh
 * @param {CKEDITOR.editor} editor
 * @param {CKEDITOR.dom.elementPath} path
 */

/**
 * Sets the element name used to reflect the command state on selection changes.
 * If the selection is in a place where the element is not allowed, the command
 * will be disabled.
 * Setting this property overrides {@link #contextSensitive} to `true`.
 *
 * @property {Boolean} [context=true]
 */

/**
 * The editor modes within which the command can be executed. The execution
 * will have no action if the current mode is not listed in this property.
 *
 *		editorInstance.addCommand( 'link', {
 *			exec: function( editor ) {
 *				// ...
 *			},
 *			modes: { wysiwyg:1 } // Command is available in wysiwyg mode only.
 *		} );
 *
 * See also {@link CKEDITOR.command#modes}.
 *
 * @property {Object} [modes={ wysiwyg:1 }]
 */

/**
 * Whether the command should be enabled in the {@link CKEDITOR.editor#setReadOnly read-only mode}.
 *
 * @since 4.0
 * @property {Boolean} [readOnly=false]
 */
Commit	Line	Data
3b35bd27 IB	1	/**
3b35bd27 IB	2	* @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
7adcb81e IB	3	* For licensing, see LICENSE.md or http://ckeditor.com/license
	4	*/
	5
	6	/**
	7	* @fileOverview Defines the "virtual" {@link CKEDITOR.commandDefinition} class,
	8	* which contains the defintion of a command. This file is for
	9	* documentation purposes only.
	10	*/
	11
	12	/**
	13	* Virtual class that illustrates the features of command objects to be
	14	* passed to the {@link CKEDITOR.editor#addCommand} function.
	15	*
	16	* @class CKEDITOR.commandDefinition
	17	* @abstract
	18	*/
	19
	20	/**
	21	* The function to be fired when the commend is executed.
	22	*
	23	* editorInstance.addCommand( 'sample', {
	24	* exec: function( editor ) {
	25	* alert( 'Executing a command for the editor name "' + editor.name + '"!' );
	26	* }
	27	* } );
	28	*
	29	* @method exec
	30	* @param {CKEDITOR.editor} editor The editor within which run the command.
	31	* @param {Object} [data] Additional data to be used to execute the command.
	32	* @returns {Boolean} Whether the command has been successfully executed.
	33	* Defaults to `true`, if nothing is returned.
	34	*/
	35
	36	/**
	37	* Whether the command need to be hooked into the redo/undo system.
	38	*
	39	* editorInstance.addCommand( 'alertName', {
	40	* exec: function( editor ) {
	41	* alert( editor.name );
	42	* },
	43	* canUndo: false // No support for undo/redo.
	44	* } );
	45	*
	46	* @property {Boolean} [canUndo=true]
	47	*/
	48
	49	/**
	50	* Whether the command is asynchronous, which means that the
	51	* {@link CKEDITOR.editor#event-afterCommandExec} event will be fired by the
	52	* command itself manually, and that the return value of this command is not to
	53	* be returned by the {@link #exec} function.
	54	*
	55	* editorInstance.addCommand( 'loadOptions', {
	56	* exec: function( editor ) {
	57	* // Asynchronous operation below.
	58	* CKEDITOR.ajax.loadXml( 'data.xml', function() {
	59	* editor.fire( 'afterCommandExec' );
	60	* } );
	61	* },
	62	* async: true // The command need some time to complete after exec function returns.
	63	* } );
	64	*
	65	* @property {Boolean} [async=false]
	66	*/
67
68	/**
69	* Whether the command should give focus to the editor before execution.
70	*
71	* editorInstance.addCommand( 'maximize', {
72	* exec: function( editor ) {
73	* // ...
74	* },
75	* editorFocus: false // The command doesn't require focusing the editing document.
76	* } );
77	*
78	* See also {@link CKEDITOR.command#editorFocus}.
79	*
80	* @property {Boolean} [editorFocus=true]
81	*/
82
83
84	/**
85	* Whether the command state should be set to {@link CKEDITOR#TRISTATE_DISABLED} on startup.
86	*
87	* editorInstance.addCommand( 'unlink', {
88	* exec: function( editor ) {
89	* // ...
90	* },
91	* startDisabled: true // Command is unavailable until selection is inside a link.
92	* } );
93	*
94	* @property {Boolean} [startDisabled=false]
95	*/
96
97	/**
98	* Indicates that this command is sensible to the selection context.
99	* If `true`, the {@link CKEDITOR.command#method-refresh} method will be
100	* called for this command on selection changes, with a single parameter
101	* representing the current elements path.
102	*
103	* @property {Boolean} [contextSensitive=true]
104	*/
105
106	/**
107	* Defined by command definition a function to determinate the command state, it will be invoked
108	* when editor has it's `states` or `selection` changed.
109	*
110	* Note: The function provided must be calling {@link CKEDITOR.command#setState} in all circumstance,
111	* if it is intended to update the command state.
112	*
113	* @method refresh
114	* @param {CKEDITOR.editor} editor
115	* @param {CKEDITOR.dom.elementPath} path
116	*/
117
118	/**
119	* Sets the element name used to reflect the command state on selection changes.
120	* If the selection is in a place where the element is not allowed, the command
121	* will be disabled.
122	* Setting this property overrides {@link #contextSensitive} to `true`.
123	*
124	* @property {Boolean} [context=true]
125	*/
126
127	/**
128	* The editor modes within which the command can be executed. The execution
129	* will have no action if the current mode is not listed in this property.
130	*
131	* editorInstance.addCommand( 'link', {
132	* exec: function( editor ) {
133	* // ...
134	* },
135	* modes: { wysiwyg:1 } // Command is available in wysiwyg mode only.
136	* } );
137	*
138	* See also {@link CKEDITOR.command#modes}.
139	*
140	* @property {Object} [modes={ wysiwyg:1 }]
141	*/
142
143	/**
144	* Whether the command should be enabled in the {@link CKEDITOR.editor#setReadOnly read-only mode}.
145	*
146	* @since 4.0
147	* @property {Boolean} [readOnly=false]
148	*/