]>
Commit | Line | Data |
---|---|---|
c63493c8 IB |
1 | /** |
2 | * @license Copyright (c) 2003-2017, 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 to 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 needs 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 | * var cmd = this; | |
58 | * // Asynchronous operation below. | |
59 | * CKEDITOR.ajax.loadXml( 'data.xml', function() { | |
60 | * editor.fire( 'afterCommandExec', { | |
61 | * name: 'loadoptions', | |
62 | * command: cmd | |
63 | * } ); | |
64 | * } ); | |
65 | * }, | |
66 | * async: true // The command needs some time to complete after the exec function returns. | |
67 | * } ); | |
68 | * | |
69 | * @property {Boolean} [async=false] | |
70 | */ | |
71 | ||
72 | /** | |
73 | * Whether the command should give focus to the editor before execution. | |
74 | * | |
75 | * editorInstance.addCommand( 'maximize', { | |
76 | * exec: function( editor ) { | |
77 | * // ... | |
78 | * }, | |
79 | * editorFocus: false // The command does not require focusing the editing document. | |
80 | * } ); | |
81 | * | |
82 | * See also {@link CKEDITOR.command#editorFocus}. | |
83 | * | |
84 | * @property {Boolean} [editorFocus=true] | |
85 | */ | |
86 | ||
87 | ||
88 | /** | |
89 | * Whether the command state should be set to {@link CKEDITOR#TRISTATE_DISABLED} on startup. | |
90 | * | |
91 | * editorInstance.addCommand( 'unlink', { | |
92 | * exec: function( editor ) { | |
93 | * // ... | |
94 | * }, | |
95 | * startDisabled: true // The command is unavailable until the selection is inside a link. | |
96 | * } ); | |
97 | * | |
98 | * @property {Boolean} [startDisabled=false] | |
99 | */ | |
100 | ||
101 | /** | |
102 | * Indicates that this command is sensitive to the selection context. | |
103 | * If `true`, the {@link CKEDITOR.command#method-refresh} method will be | |
104 | * called for this command on selection changes, with a single parameter | |
105 | * representing the current elements path. | |
106 | * | |
107 | * @property {Boolean} [contextSensitive=true] | |
108 | */ | |
109 | ||
110 | /** | |
111 | * Defined by the command definition, a function to determine the command state. It will be invoked | |
112 | * when the editor has its `states` or `selection` changed. | |
113 | * | |
114 | * **Note:** The function provided must be calling {@link CKEDITOR.command#setState} in all circumstances | |
115 | * if it is intended to update the command state. | |
116 | * | |
117 | * @method refresh | |
118 | * @param {CKEDITOR.editor} editor | |
119 | * @param {CKEDITOR.dom.elementPath} path | |
120 | */ | |
121 | ||
122 | /** | |
123 | * Sets the element name used to reflect the command state on selection changes. | |
124 | * If the selection is in a place where the element is not allowed, the command | |
125 | * will be disabled. | |
126 | * Setting this property overrides {@link #contextSensitive} to `true`. | |
127 | * | |
128 | * @property {Boolean} [context=true] | |
129 | */ | |
130 | ||
131 | /** | |
132 | * The editor modes within which the command can be executed. The execution | |
133 | * will have no action if the current mode is not listed in this property. | |
134 | * | |
135 | * editorInstance.addCommand( 'link', { | |
136 | * exec: function( editor ) { | |
137 | * // ... | |
138 | * }, | |
139 | * modes: { wysiwyg:1 } // The command is available in wysiwyg mode only. | |
140 | * } ); | |
141 | * | |
142 | * See also {@link CKEDITOR.command#modes}. | |
143 | * | |
144 | * @property {Object} [modes={ wysiwyg:1 }] | |
145 | */ | |
146 | ||
147 | /** | |
148 | * Whether the command should be enabled in the {@link CKEDITOR.editor#setReadOnly read-only mode}. | |
149 | * | |
150 | * @since 4.0 | |
151 | * @property {Boolean} [readOnly=false] | |
152 | */ | |
153 | ||
154 | /** | |
155 | * A property that should be set when a command has no keystroke assigned by {@link CKEDITOR.editor#setKeystroke}, but | |
156 | * the keystroke is still supported. For example: `cut`, `copy` and `paste` commands are handled that way. | |
157 | * This property is used when displaying keystroke information in tooltips and context menus. It is used by | |
158 | * {@link CKEDITOR.editor#getCommandKeystroke}. | |
159 | * | |
160 | * @since 4.6.0 | |
161 | * @property {Number} fakeKeystroke | |
162 | */ |