Index: /CKEditor/trunk/_source/core/command.js
===================================================================
--- /CKEditor/trunk/_source/core/command.js (revision 5980)
+++ /CKEditor/trunk/_source/core/command.js (revision 5981)
@@ -4,8 +4,42 @@
*/
+/**
+ * Creates a command class instance.
+ * @class Represents a command that can be executed on an editor instance.
+ * @param {CKEDITOR.editor} editor The editor instance this command will be
+ * related to.
+ * @param {CKEDITOR.commandDefinition} commandDefinition The command
+ * definition.
+ * @augments CKEDITOR.event
+ * @example
+ * var command = new CKEDITOR.command( editor,
+ * {
+ * exec : function( editor )
+ * {
+ * alert( editor.document.getBody().getHtml() );
+ * }
+ * });
+ */
CKEDITOR.command = function( editor, commandDefinition )
{
+ /**
+ * Lists UI items that are associated to this command. This list can be
+ * used to interact with the UI on command execution (by the execution code
+ * itself, for example).
+ * @type Array
+ * @example
+ * alert( 'Number of UI items associated to this command: ' + command.uiItems.length );
+ */
this.uiItems = [];
+ /**
+ * Executes the command.
+ * @param {Object} [data] Any data to pass to the command. Depends on the
+ * command implementation and requirements.
+ * @returns {Boolean} A boolean indicating that the command has been
+ * successfully executed.
+ * @example
+ * command.exec(); // The command gets executed.
+ */
this.exec = function( data )
{
@@ -21,7 +55,54 @@
CKEDITOR.tools.extend( this, commandDefinition,
// Defaults
+ /** @lends CKEDITOR.command.prototype */
{
+ /**
+ * 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.
+ * @type Object
+ * @default { wysiwyg : 1 }
+ * @see CKEDITOR.editor.prototype.mode
+ * @example
+ * // Enable the command in both WYSIWYG and Source modes.
+ * command.modes = { wysiwyg : 1, source : 1 };
+ * @example
+ * // Enable the command in Source mode only.
+ * command.modes = { source : 1 };
+ */
modes : { wysiwyg : 1 },
+
+ /**
+ * Indicates that the editor will get the focus before executing
+ * the command.
+ * @type Boolean
+ * @default true
+ * @example
+ * // Do not force the editor to have focus when executing the command.
+ * command.editorFocus = false;
+ */
editorFocus : true,
+
+ /**
+ * Indicates the editor state. Possible values are:
+ *
+ * - {@link CKEDITOR.TRISTATE_DISABLED}: the command is
+ * disabled. It's execution will have no effect. Same as
+ * {@link disable}.
+ * - {@link CKEDITOR.TRISTATE_ON}: the command is enabled
+ * and currently active in the editor (for context sensitive commands,
+ * for example).
+ * - {@link CKEDITOR.TRISTATE_OFF}: the command is enabled
+ * and currently inactive in the editor (for context sensitive
+ * commands, for example).
+ *
+ * Do not set this property directly, using the {@link #setState}
+ * method instead.
+ * @type Number
+ * @default {@link CKEDITOR.TRISTATE_OFF}
+ * @example
+ * if ( command.state == CKEDITOR.TRISTATE_DISABLED )
+ * alert( 'This command is disabled' );
+ */
state : CKEDITOR.TRISTATE_OFF
});
@@ -33,4 +114,12 @@
CKEDITOR.command.prototype =
{
+ /**
+ * Enables the command for execution. The command state (see
+ * {@link CKEDITOR.command.prototype.state}) available before disabling it
+ * is restored.
+ * @example
+ * command.enable();
+ * command.exec(); // Execute the command.
+ */
enable : function()
{
@@ -39,4 +128,12 @@
},
+ /**
+ * Disables the command for execution. The command state (see
+ * {@link CKEDITOR.command.prototype.state}) will be set to
+ * {@link CKEDITOR.TRISTATE_DISABLED}.
+ * @example
+ * command.disable();
+ * command.exec(); // "false" - Nothing happens.
+ */
disable : function()
{
@@ -44,4 +141,16 @@
},
+ /**
+ * Sets the command state.
+ * @param {Number} newState The new state. See {@link #state}.
+ * @returns {Boolean} Returns "true" if the command state changed.
+ * @example
+ * command.setState( CKEDITOR.TRISTATE_ON );
+ * command.exec(); // Execute the command.
+ * command.setState( CKEDITOR.TRISTATE_DISABLED );
+ * command.exec(); // "false" - Nothing happens.
+ * command.setState( CKEDITOR.TRISTATE_OFF );
+ * command.exec(); // Execute the command.
+ */
setState : function( newState )
{
@@ -62,4 +171,10 @@
},
+ /**
+ * Toggles the on/off (active/inactive) state of the command. This is
+ * mainly used internally by context sensitive commands.
+ * @example
+ * command.toggleState();
+ */
toggleState : function()
{
@@ -72,2 +187,22 @@
CKEDITOR.event.implementOn( CKEDITOR.command.prototype, true );
+
+/**
+ * Indicates the preivous command state.
+ * @name CKEDITOR.command.prototype.previousState
+ * @type Number
+ * @see #state
+ * @example
+ * alert( command.previousState );
+ */
+
+/**
+ * Fired when the command state changes.
+ * @name CKEDITOR.command.prototype#state
+ * @event
+ * command.on( 'state' , function( e )
+ * {
+ * // Alerts the new state.
+ * alert( this.state );
+ * });
+ */