]>
Commit | Line | Data |
---|---|---|
1 | /** | |
2 | * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved. | |
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 | */ |