diff options
Diffstat (limited to 'sources/core/commanddefinition.js')
-rw-r--r-- | sources/core/commanddefinition.js | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/sources/core/commanddefinition.js b/sources/core/commanddefinition.js new file mode 100644 index 0000000..10a040f --- /dev/null +++ b/sources/core/commanddefinition.js | |||
@@ -0,0 +1,162 @@ | |||
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 | */ | ||