b49a893a39baa5518c664e6faa8c1909003d1dc1
[ckeditor.git] / _source / plugins / keystrokes / plugin.js
1 /*
2 Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
3 For licensing, see LICENSE.html or http://ckeditor.com/license
4 */
5
6 // Register a plugin named "sample".
7 CKEDITOR.plugins.add( 'keystrokes',
8 {
9 beforeInit : function( editor )
10 {
11 /**
12 * Controls keystrokes typing in this editor instance.
13 * @name CKEDITOR.editor.prototype.keystrokeHandler
14 * @type CKEDITOR.keystrokeHandler
15 * @example
16 */
17 editor.keystrokeHandler = new CKEDITOR.keystrokeHandler( editor );
18
19 editor.specialKeys = {};
20 },
21
22 init : function( editor )
23 {
24 var keystrokesConfig = editor.config.keystrokes,
25 blockedConfig = editor.config.blockedKeystrokes;
26
27 var keystrokes = editor.keystrokeHandler.keystrokes,
28 blockedKeystrokes = editor.keystrokeHandler.blockedKeystrokes;
29
30 for ( var i = 0 ; i < keystrokesConfig.length ; i++ )
31 keystrokes[ keystrokesConfig[i][0] ] = keystrokesConfig[i][1];
32
33 for ( i = 0 ; i < blockedConfig.length ; i++ )
34 blockedKeystrokes[ blockedConfig[i] ] = 1;
35 }
36 });
37
38 /**
39 * Controls keystrokes typing in an editor instance.
40 * @constructor
41 * @param {CKEDITOR.editor} editor The editor instance.
42 * @example
43 */
44 CKEDITOR.keystrokeHandler = function( editor )
45 {
46 if ( editor.keystrokeHandler )
47 return editor.keystrokeHandler;
48
49 /**
50 * List of keystrokes associated to commands. Each entry points to the
51 * command to be executed.
52 * @type Object
53 * @example
54 */
55 this.keystrokes = {};
56
57 /**
58 * List of keystrokes that should be blocked if not defined at
59 * {@link keystrokes}. In this way it is possible to block the default
60 * browser behavior for those keystrokes.
61 * @type Object
62 * @example
63 */
64 this.blockedKeystrokes = {};
65
66 this._ =
67 {
68 editor : editor
69 };
70
71 return this;
72 };
73
74 (function()
75 {
76 var cancel;
77
78 var onKeyDown = function( event )
79 {
80 // The DOM event object is passed by the "data" property.
81 event = event.data;
82
83 var keyCombination = event.getKeystroke();
84 var command = this.keystrokes[ keyCombination ];
85 var editor = this._.editor;
86
87 cancel = ( editor.fire( 'key', { keyCode : keyCombination } ) === true );
88
89 if ( !cancel )
90 {
91 if ( command )
92 {
93 var data = { from : 'keystrokeHandler' };
94 cancel = ( editor.execCommand( command, data ) !== false );
95 }
96
97 if ( !cancel )
98 {
99 var handler = editor.specialKeys[ keyCombination ];
100 cancel = ( handler && handler( editor ) === true );
101
102 if ( !cancel )
103 cancel = !!this.blockedKeystrokes[ keyCombination ];
104 }
105 }
106
107 if ( cancel )
108 event.preventDefault( true );
109
110 return !cancel;
111 };
112
113 var onKeyPress = function( event )
114 {
115 if ( cancel )
116 {
117 cancel = false;
118 event.data.preventDefault( true );
119 }
120 };
121
122 CKEDITOR.keystrokeHandler.prototype =
123 {
124 /**
125 * Attaches this keystroke handle to a DOM object. Keystrokes typed
126 ** over this object will get handled by this keystrokeHandler.
127 * @param {CKEDITOR.dom.domObject} domObject The DOM object to attach
128 * to.
129 * @example
130 */
131 attach : function( domObject )
132 {
133 // For most browsers, it is enough to listen to the keydown event
134 // only.
135 domObject.on( 'keydown', onKeyDown, this );
136
137 // Some browsers instead, don't cancel key events in the keydown, but in the
138 // keypress. So we must do a longer trip in those cases.
139 if ( CKEDITOR.env.opera || ( CKEDITOR.env.gecko && CKEDITOR.env.mac ) )
140 domObject.on( 'keypress', onKeyPress, this );
141 }
142 };
143 })();
144
145 /**
146 * A list of keystrokes to be blocked if not defined in the {@link CKEDITOR.config.keystrokes}
147 * setting. In this way it is possible to block the default browser behavior
148 * for those keystrokes.
149 * @type Array
150 * @default (see example)
151 * @example
152 * // This is actually the default value.
153 * config.blockedKeystrokes =
154 * [
155 * CKEDITOR.CTRL + 66 &#47;*B*&#47;,
156 * CKEDITOR.CTRL + 73 &#47;*I*&#47;,
157 * CKEDITOR.CTRL + 85 &#47;*U*&#47;
158 * ];
159 */
160 CKEDITOR.config.blockedKeystrokes =
161 [
162 CKEDITOR.CTRL + 66 /*B*/,
163 CKEDITOR.CTRL + 73 /*I*/,
164 CKEDITOR.CTRL + 85 /*U*/
165 ];
166
167 /**
168 * A list associating keystrokes to editor commands. Each element in the list
169 * is an array where the first item is the keystroke, and the second is the
170 * name of the command to be executed.
171 * @type Array
172 * @default (see example)
173 * @example
174 * // This is actually the default value.
175 * config.keystrokes =
176 * [
177 * [ CKEDITOR.ALT + 121 &#47;*F10*&#47;, 'toolbarFocus' ],
178 * [ CKEDITOR.ALT + 122 &#47;*F11*&#47;, 'elementsPathFocus' ],
179 *
180 * [ CKEDITOR.SHIFT + 121 &#47;*F10*&#47;, 'contextMenu' ],
181 *
182 * [ CKEDITOR.CTRL + 90 &#47;*Z*&#47;, 'undo' ],
183 * [ CKEDITOR.CTRL + 89 &#47;*Y*&#47;, 'redo' ],
184 * [ CKEDITOR.CTRL + CKEDITOR.SHIFT + 90 &#47;*Z*&#47;, 'redo' ],
185 *
186 * [ CKEDITOR.CTRL + 76 &#47;*L*&#47;, 'link' ],
187 *
188 * [ CKEDITOR.CTRL + 66 &#47;*B*&#47;, 'bold' ],
189 * [ CKEDITOR.CTRL + 73 &#47;*I*&#47;, 'italic' ],
190 * [ CKEDITOR.CTRL + 85 &#47;*U*&#47;, 'underline' ],
191 *
192 * [ CKEDITOR.ALT + 109 &#47;*-*&#47;, 'toolbarCollapse' ]
193 * ];
194 */
195 CKEDITOR.config.keystrokes =
196 [
197 [ CKEDITOR.ALT + 121 /*F10*/, 'toolbarFocus' ],
198 [ CKEDITOR.ALT + 122 /*F11*/, 'elementsPathFocus' ],
199
200 [ CKEDITOR.SHIFT + 121 /*F10*/, 'contextMenu' ],
201 [ CKEDITOR.CTRL + CKEDITOR.SHIFT + 121 /*F10*/, 'contextMenu' ],
202
203 [ CKEDITOR.CTRL + 90 /*Z*/, 'undo' ],
204 [ CKEDITOR.CTRL + 89 /*Y*/, 'redo' ],
205 [ CKEDITOR.CTRL + CKEDITOR.SHIFT + 90 /*Z*/, 'redo' ],
206
207 [ CKEDITOR.CTRL + 76 /*L*/, 'link' ],
208
209 [ CKEDITOR.CTRL + 66 /*B*/, 'bold' ],
210 [ CKEDITOR.CTRL + 73 /*I*/, 'italic' ],
211 [ CKEDITOR.CTRL + 85 /*U*/, 'underline' ],
212
213 [ CKEDITOR.ALT + ( CKEDITOR.env.ie || CKEDITOR.env.webkit ? 189 : 109 ) /*-*/, 'toolbarCollapse' ],
214 [ CKEDITOR.ALT + 48 /*0*/, 'a11yHelp' ]
215 ];
216
217 /**
218 * Fired when any keyboard key (or combination) is pressed into the editing area.
219 * @name CKEDITOR.editor#key
220 * @event
221 * @param {Number} data.keyCode A number representing the key code (or
222 * combination). It is the sum of the current key code and the
223 * {@link CKEDITOR.CTRL}, {@link CKEDITOR.SHIFT} and {@link CKEDITOR.ALT}
224 * constants, if those are pressed.
225 */