X-Git-Url: https://jasonwoof.com/gitweb/?a=blobdiff_plain;ds=sidebyside;f=_source%2Fcore%2Fcommand.js;h=c0868f0f922ae219f6e548705ee3139a2e942988;hb=refs%2Ftags%2Fv3.5.3;hp=0a8d0988635a2d77f0172d73da18a13dfef32f32;hpb=c6e377a02b54abc07129d72b632763c727476a15;p=ckeditor.git
diff --git a/_source/core/command.js b/_source/core/command.js
index 0a8d098..c0868f0 100644
--- a/_source/core/command.js
+++ b/_source/core/command.js
@@ -1,12 +1,46 @@
/*
-Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved.
+Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/
+/**
+ * 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 )
{
if ( this.state == CKEDITOR.TRISTATE_DISABLED )
@@ -20,9 +54,56 @@ CKEDITOR.command = function( editor, commandDefinition )
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 },
- editorFocus : true,
+
+ /**
+ * 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 : 1,
+
+ /**
+ * 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
});
@@ -32,17 +113,45 @@ CKEDITOR.command = function( editor, commandDefinition )
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()
{
if ( this.state == CKEDITOR.TRISTATE_DISABLED )
this.setState( ( !this.preserveState || ( typeof this.previousState == 'undefined' ) ) ? CKEDITOR.TRISTATE_OFF : this.previousState );
},
+ /**
+ * 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()
{
this.setState( CKEDITOR.TRISTATE_DISABLED );
},
+ /**
+ * 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 )
{
// Do nothing if there is no state change.
@@ -61,6 +170,12 @@ CKEDITOR.command.prototype =
return true;
},
+ /**
+ * Toggles the on/off (active/inactive) state of the command. This is
+ * mainly used internally by context sensitive commands.
+ * @example
+ * command.toggleState();
+ */
toggleState : function()
{
if ( this.state == CKEDITOR.TRISTATE_OFF )
@@ -71,3 +186,24 @@ CKEDITOR.command.prototype =
};
CKEDITOR.event.implementOn( CKEDITOR.command.prototype, true );
+
+/**
+ * Indicates the previous command state.
+ * @name CKEDITOR.command.prototype.previousState
+ * @type Number
+ * @see #state
+ * @example
+ * alert( command.previousState );
+ */
+
+/**
+ * Fired when the command state changes.
+ * @name CKEDITOR.command#state
+ * @event
+ * @example
+ * command.on( 'state' , function( e )
+ * {
+ * // Alerts the new state.
+ * alert( this.state );
+ * });
+ */