]>
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 | * 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 | */ |