diff options
Diffstat (limited to 'sources/core/keystrokehandler.js')
-rw-r--r-- | sources/core/keystrokehandler.js | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/sources/core/keystrokehandler.js b/sources/core/keystrokehandler.js new file mode 100644 index 0000000..c84089b --- /dev/null +++ b/sources/core/keystrokehandler.js | |||
@@ -0,0 +1,169 @@ | |||
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 | * Controls keystrokes typing in an editor instance. | ||
8 | * | ||
9 | * @class | ||
10 | * @constructor Creates a keystrokeHandler class instance. | ||
11 | * @param {CKEDITOR.editor} editor The editor instance. | ||
12 | */ | ||
13 | CKEDITOR.keystrokeHandler = function( editor ) { | ||
14 | if ( editor.keystrokeHandler ) | ||
15 | return editor.keystrokeHandler; | ||
16 | |||
17 | /** | ||
18 | * A list of keystrokes associated with commands. Each entry points to the | ||
19 | * command to be executed. | ||
20 | * | ||
21 | * Since CKEditor 4 there is no need to modify this property directly during the runtime. | ||
22 | * Use {@link CKEDITOR.editor#setKeystroke} instead. | ||
23 | */ | ||
24 | this.keystrokes = {}; | ||
25 | |||
26 | /** | ||
27 | * A list of keystrokes that should be blocked if not defined in | ||
28 | * {@link #keystrokes}. In this way it is possible to block the default | ||
29 | * browser behavior for those keystrokes. | ||
30 | */ | ||
31 | this.blockedKeystrokes = {}; | ||
32 | |||
33 | this._ = { | ||
34 | editor: editor | ||
35 | }; | ||
36 | |||
37 | return this; | ||
38 | }; | ||
39 | |||
40 | ( function() { | ||
41 | var cancel; | ||
42 | |||
43 | var onKeyDown = function( event ) { | ||
44 | // The DOM event object is passed by the "data" property. | ||
45 | event = event.data; | ||
46 | |||
47 | var keyCombination = event.getKeystroke(); | ||
48 | var command = this.keystrokes[ keyCombination ]; | ||
49 | var editor = this._.editor; | ||
50 | |||
51 | cancel = ( editor.fire( 'key', { keyCode: keyCombination, domEvent: event } ) === false ); | ||
52 | |||
53 | if ( !cancel ) { | ||
54 | if ( command ) { | ||
55 | var data = { from: 'keystrokeHandler' }; | ||
56 | cancel = ( editor.execCommand( command, data ) !== false ); | ||
57 | } | ||
58 | |||
59 | if ( !cancel ) | ||
60 | cancel = !!this.blockedKeystrokes[ keyCombination ]; | ||
61 | } | ||
62 | |||
63 | if ( cancel ) | ||
64 | event.preventDefault( true ); | ||
65 | |||
66 | return !cancel; | ||
67 | }; | ||
68 | |||
69 | var onKeyPress = function( event ) { | ||
70 | if ( cancel ) { | ||
71 | cancel = false; | ||
72 | event.data.preventDefault( true ); | ||
73 | } | ||
74 | }; | ||
75 | |||
76 | CKEDITOR.keystrokeHandler.prototype = { | ||
77 | /** | ||
78 | * Attaches this keystroke handle to a DOM object. Keystrokes typed | ||
79 | * over this object will be handled by this keystrokeHandler. | ||
80 | * | ||
81 | * @param {CKEDITOR.dom.domObject} domObject The DOM object to attach to. | ||
82 | */ | ||
83 | attach: function( domObject ) { | ||
84 | // For most browsers, it is enough to listen to the keydown event | ||
85 | // only. | ||
86 | domObject.on( 'keydown', onKeyDown, this ); | ||
87 | |||
88 | // Some browsers instead, don't cancel key events in the keydown, but in the | ||
89 | // keypress. So we must do a longer trip in those cases. | ||
90 | if ( CKEDITOR.env.gecko && CKEDITOR.env.mac ) | ||
91 | domObject.on( 'keypress', onKeyPress, this ); | ||
92 | } | ||
93 | }; | ||
94 | } )(); | ||
95 | |||
96 | /** | ||
97 | * A list associating keystrokes with editor commands. Each element in the list | ||
98 | * is an array where the first item is the keystroke, and the second is the | ||
99 | * name of the command to be executed. | ||
100 | * | ||
101 | * This setting should be used to define (as well as to overwrite or remove) keystrokes | ||
102 | * set by plugins (like `link` and `basicstyles`). If you want to set a keystroke | ||
103 | * for your plugin or during the runtime, use {@link CKEDITOR.editor#setKeystroke} instead. | ||
104 | * | ||
105 | * Since default keystrokes are set by the {@link CKEDITOR.editor#setKeystroke} | ||
106 | * method, by default `config.keystrokes` is an empty array. | ||
107 | * | ||
108 | * See {@link CKEDITOR.editor#setKeystroke} documentation for more details | ||
109 | * regarding the start up order. | ||
110 | * | ||
111 | * // Change default Ctrl+L keystroke for 'link' command to Ctrl+Shift+L. | ||
112 | * config.keystrokes = [ | ||
113 | * ... | ||
114 | * [ CKEDITOR.CTRL + CKEDITOR.SHIFT + 76, 'link' ], // Ctrl+Shift+L | ||
115 | * ... | ||
116 | * ]; | ||
117 | * | ||
118 | * To reset a particular keystroke, the following approach can be used: | ||
119 | * | ||
120 | * // Disable default Ctrl+L keystroke which executes the 'link' command by default. | ||
121 | * config.keystrokes = [ | ||
122 | * ... | ||
123 | * [ CKEDITOR.CTRL + 76, null ], // Ctrl+L | ||
124 | * ... | ||
125 | * ]; | ||
126 | * | ||
127 | * In order to reset all default keystrokes, a {@link CKEDITOR#instanceReady} callback should be | ||
128 | * used. This is since editor defaults are merged rather than overwritten by | ||
129 | * user keystrokes. | ||
130 | * | ||
131 | * **Note**: This can be potentially harmful for the editor. Avoid this unless you are | ||
132 | * aware of the consequences. | ||
133 | * | ||
134 | * // Reset all default keystrokes. | ||
135 | * config.on.instanceReady = function() { | ||
136 | * this.keystrokeHandler.keystrokes = []; | ||
137 | * }; | ||
138 | * | ||
139 | * @cfg {Array} [keystrokes=[]] | ||
140 | * @member CKEDITOR.config | ||
141 | */ | ||
142 | |||
143 | /** | ||
144 | * Fired when any keyboard key (or a combination thereof) is pressed in the editing area. | ||
145 | * | ||
146 | * editor.on( 'key', function( evt ) { | ||
147 | * if ( evt.data.keyCode == CKEDITOR.CTRL + 90 ) { | ||
148 | * // Do something... | ||
149 | * | ||
150 | * // Cancel the event, so other listeners will not be executed and | ||
151 | * // the keydown's default behavior will be prevented. | ||
152 | * evt.cancel(); | ||
153 | * } | ||
154 | * } ); | ||
155 | * | ||
156 | * Usually you will want to use the {@link CKEDITOR.editor#setKeystroke} method or | ||
157 | * the {@link CKEDITOR.config#keystrokes} option to attach a keystroke to some {@link CKEDITOR.command command}. | ||
158 | * Key event listeners are usuful when some action should be executed conditionally, based | ||
159 | * for example on precise selection location. | ||
160 | * | ||
161 | * @event key | ||
162 | * @member CKEDITOR.editor | ||
163 | * @param data | ||
164 | * @param {Number} data.keyCode A number representing the key code (or a combination thereof). | ||
165 | * It is the sum of the current key code and the {@link CKEDITOR#CTRL}, {@link CKEDITOR#SHIFT} | ||
166 | * and {@link CKEDITOR#ALT} constants, if those are pressed. | ||
167 | * @param {CKEDITOR.dom.event} data.domEvent A `keydown` DOM event instance. Available since CKEditor 4.4.1. | ||
168 | * @param {CKEDITOR.editor} editor This editor instance. | ||
169 | */ | ||