c0868f0f922ae219f6e548705ee3139a2e942988
[ckeditor.git] / _source / core / command.js
1 /*
2 Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
3 For licensing, see LICENSE.html or http://ckeditor.com/license
4 */
5
6 /**
7 * Creates a command class instance.
8 * @class Represents a command that can be executed on an editor instance.
9 * @param {CKEDITOR.editor} editor The editor instance this command will be
10 * related to.
11 * @param {CKEDITOR.commandDefinition} commandDefinition The command
12 * definition.
13 * @augments CKEDITOR.event
14 * @example
15 * var command = new CKEDITOR.command( editor,
16 * {
17 * exec : function( editor )
18 * {
19 * alert( editor.document.getBody().getHtml() );
20 * }
21 * });
22 */
23 CKEDITOR.command = function( editor, commandDefinition )
24 {
25 /**
26 * Lists UI items that are associated to this command. This list can be
27 * used to interact with the UI on command execution (by the execution code
28 * itself, for example).
29 * @type Array
30 * @example
31 * alert( 'Number of UI items associated to this command: ' + command.<b>uiItems</b>.length );
32 */
33 this.uiItems = [];
34
35 /**
36 * Executes the command.
37 * @param {Object} [data] Any data to pass to the command. Depends on the
38 * command implementation and requirements.
39 * @returns {Boolean} A boolean indicating that the command has been
40 * successfully executed.
41 * @example
42 * command.<b>exec()</b>; // The command gets executed.
43 */
44 this.exec = function( data )
45 {
46 if ( this.state == CKEDITOR.TRISTATE_DISABLED )
47 return false;
48
49 if ( this.editorFocus ) // Give editor focus if necessary (#4355).
50 editor.focus();
51
52 return ( commandDefinition.exec.call( this, editor, data ) !== false );
53 };
54
55 CKEDITOR.tools.extend( this, commandDefinition,
56 // Defaults
57 /** @lends CKEDITOR.command.prototype */
58 {
59 /**
60 * The editor modes within which the command can be executed. The
61 * execution will have no action if the current mode is not listed
62 * in this property.
63 * @type Object
64 * @default { wysiwyg : 1 }
65 * @see CKEDITOR.editor.prototype.mode
66 * @example
67 * // Enable the command in both WYSIWYG and Source modes.
68 * command.<b>modes</b> = { wysiwyg : 1, source : 1 };
69 * @example
70 * // Enable the command in Source mode only.
71 * command.<b>modes</b> = { source : 1 };
72 */
73 modes : { wysiwyg : 1 },
74
75 /**
76 * Indicates that the editor will get the focus before executing
77 * the command.
78 * @type Boolean
79 * @default true
80 * @example
81 * // Do not force the editor to have focus when executing the command.
82 * command.<b>editorFocus</b> = false;
83 */
84 editorFocus : 1,
85
86 /**
87 * Indicates the editor state. Possible values are:
88 * <ul>
89 * <li>{@link CKEDITOR.TRISTATE_DISABLED}: the command is
90 * disabled. It's execution will have no effect. Same as
91 * {@link disable}.</li>
92 * <li>{@link CKEDITOR.TRISTATE_ON}: the command is enabled
93 * and currently active in the editor (for context sensitive commands,
94 * for example).</li>
95 * <li>{@link CKEDITOR.TRISTATE_OFF}: the command is enabled
96 * and currently inactive in the editor (for context sensitive
97 * commands, for example).</li>
98 * </ul>
99 * Do not set this property directly, using the {@link #setState}
100 * method instead.
101 * @type Number
102 * @default {@link CKEDITOR.TRISTATE_OFF}
103 * @example
104 * if ( command.<b>state</b> == CKEDITOR.TRISTATE_DISABLED )
105 * alert( 'This command is disabled' );
106 */
107 state : CKEDITOR.TRISTATE_OFF
108 });
109
110 // Call the CKEDITOR.event constructor to initialize this instance.
111 CKEDITOR.event.call( this );
112 };
113
114 CKEDITOR.command.prototype =
115 {
116 /**
117 * Enables the command for execution. The command state (see
118 * {@link CKEDITOR.command.prototype.state}) available before disabling it
119 * is restored.
120 * @example
121 * command.<b>enable()</b>;
122 * command.exec(); // Execute the command.
123 */
124 enable : function()
125 {
126 if ( this.state == CKEDITOR.TRISTATE_DISABLED )
127 this.setState( ( !this.preserveState || ( typeof this.previousState == 'undefined' ) ) ? CKEDITOR.TRISTATE_OFF : this.previousState );
128 },
129
130 /**
131 * Disables the command for execution. The command state (see
132 * {@link CKEDITOR.command.prototype.state}) will be set to
133 * {@link CKEDITOR.TRISTATE_DISABLED}.
134 * @example
135 * command.<b>disable()</b>;
136 * command.exec(); // "false" - Nothing happens.
137 */
138 disable : function()
139 {
140 this.setState( CKEDITOR.TRISTATE_DISABLED );
141 },
142
143 /**
144 * Sets the command state.
145 * @param {Number} newState The new state. See {@link #state}.
146 * @returns {Boolean} Returns "true" if the command state changed.
147 * @example
148 * command.<b>setState( CKEDITOR.TRISTATE_ON )</b>;
149 * command.exec(); // Execute the command.
150 * command.<b>setState( CKEDITOR.TRISTATE_DISABLED )</b>;
151 * command.exec(); // "false" - Nothing happens.
152 * command.<b>setState( CKEDITOR.TRISTATE_OFF )</b>;
153 * command.exec(); // Execute the command.
154 */
155 setState : function( newState )
156 {
157 // Do nothing if there is no state change.
158 if ( this.state == newState )
159 return false;
160
161 this.previousState = this.state;
162
163 // Set the new state.
164 this.state = newState;
165
166 // Fire the "state" event, so other parts of the code can react to the
167 // change.
168 this.fire( 'state' );
169
170 return true;
171 },
172
173 /**
174 * Toggles the on/off (active/inactive) state of the command. This is
175 * mainly used internally by context sensitive commands.
176 * @example
177 * command.<b>toggleState()</b>;
178 */
179 toggleState : function()
180 {
181 if ( this.state == CKEDITOR.TRISTATE_OFF )
182 this.setState( CKEDITOR.TRISTATE_ON );
183 else if ( this.state == CKEDITOR.TRISTATE_ON )
184 this.setState( CKEDITOR.TRISTATE_OFF );
185 }
186 };
187
188 CKEDITOR.event.implementOn( CKEDITOR.command.prototype, true );
189
190 /**
191 * Indicates the previous command state.
192 * @name CKEDITOR.command.prototype.previousState
193 * @type Number
194 * @see #state
195 * @example
196 * alert( command.<b>previousState</b> );
197 */
198
199 /**
200 * Fired when the command state changes.
201 * @name CKEDITOR.command#state
202 * @event
203 * @example
204 * command.on( <b>'state'</b> , function( e )
205 * {
206 * // Alerts the new state.
207 * alert( this.state );
208 * });
209 */