Debian Codegraph @

closure-library/closure/goog/events/pastehandler.js

raw
1 // Copyright 2009 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Provides a 'paste' event detector that works consistently
17 * across different browsers.
18 *
19 * IE5, IE6, IE7, Safari3.0 and FF3.0 all fire 'paste' events on textareas.
20 * FF2 doesn't. This class uses 'paste' events when they are available
21 * and uses heuristics to detect the 'paste' event when they are not available.
22 *
23 * Known issue: will not detect paste events in FF2 if you pasted exactly the
24 * same existing text.
25 * Known issue: Opera + Mac doesn't work properly because of the meta key. We
26 * can probably fix that. TODO(user): {@link KeyboardShortcutHandler} does not
27 * work either very well with opera + mac. fix that.
28 *
29 * @see ../demos/pastehandler.html
30 */
31
32 goog.provide('goog.events.PasteHandler');
33 goog.provide('goog.events.PasteHandler.EventType');
34 goog.provide('goog.events.PasteHandler.State');
35
36 goog.require('goog.Timer');
37 goog.require('goog.async.ConditionalDelay');
38 goog.require('goog.events.BrowserEvent');
39 goog.require('goog.events.EventHandler');
40 goog.require('goog.events.EventTarget');
41 goog.require('goog.events.EventType');
42 goog.require('goog.events.KeyCodes');
43 goog.require('goog.log');
44 goog.require('goog.userAgent');
45
46
47
48 /**
49 * A paste event detector. Gets an {@code element} as parameter and fires
50 * {@code goog.events.PasteHandler.EventType.PASTE} events when text is
51 * pasted in the {@code element}. Uses heuristics to detect paste events in FF2.
52 * See more details of the heuristic on {@link #handleEvent_}.
53 *
54 * @param {Element} element The textarea element we are listening on.
55 * @constructor
56 * @extends {goog.events.EventTarget}
57 */
58 goog.events.PasteHandler = function(element) {
59 goog.events.EventTarget.call(this);
60
61 /**
62 * The element that you want to listen for paste events on.
63 * @type {Element}
64 * @private
65 */
66 this.element_ = element;
67
68 /**
69 * The last known value of the element. Kept to check if things changed. See
70 * more details on {@link #handleEvent_}.
71 * @type {string}
72 * @private
73 */
74 this.oldValue_ = this.element_.value;
75
76 /**
77 * Handler for events.
78 * @type {goog.events.EventHandler<!goog.events.PasteHandler>}
79 * @private
80 */
81 this.eventHandler_ = new goog.events.EventHandler(this);
82
83 /**
84 * The last time an event occurred on the element. Kept to check whether the
85 * last event was generated by two input events or by multiple fast key events
86 * that got swallowed. See more details on {@link #handleEvent_}.
87 * @type {number}
88 * @private
89 */
90 this.lastTime_ = goog.now();
91
92 if (goog.events.PasteHandler.SUPPORTS_NATIVE_PASTE_EVENT) {
93 // Most modern browsers support the paste event.
94 this.eventHandler_.listen(
95 element, goog.events.EventType.PASTE, this.dispatch_);
96 } else {
97 // But FF2 and Opera doesn't. we listen for a series of events to try to
98 // find out if a paste occurred. We enumerate and cover all known ways to
99 // paste text on textareas. See more details on {@link #handleEvent_}.
100 var events = [
101 goog.events.EventType.KEYDOWN, goog.events.EventType.BLUR,
102 goog.events.EventType.FOCUS, goog.events.EventType.MOUSEOVER, 'input'
103 ];
104 this.eventHandler_.listen(element, events, this.handleEvent_);
105 }
106
107 /**
108 * ConditionalDelay used to poll for changes in the text element once users
109 * paste text. Browsers fire paste events BEFORE the text is actually present
110 * in the element.value property.
111 * @type {goog.async.ConditionalDelay}
112 * @private
113 */
114 this.delay_ =
115 new goog.async.ConditionalDelay(goog.bind(this.checkUpdatedText_, this));
116
117 };
118 goog.inherits(goog.events.PasteHandler, goog.events.EventTarget);
119
120
121 /**
122 * The types of events fired by this class.
123 * @enum {string}
124 */
125 goog.events.PasteHandler.EventType = {
126 /**
127 * Dispatched as soon as the paste event is detected, but before the pasted
128 * text has been added to the text element we're listening to.
129 */
130 PASTE: 'paste',
131
132 /**
133 * Dispatched after detecting a change to the value of text element
134 * (within 200msec of receiving the PASTE event).
135 */
136 AFTER_PASTE: 'after_paste'
137 };
138
139
140 /**
141 * The mandatory delay we expect between two {@code input} events, used to
142 * differentiated between non key paste events and key events.
143 * @type {number}
144 */
145 goog.events.PasteHandler.MANDATORY_MS_BETWEEN_INPUT_EVENTS_TIE_BREAKER = 400;
146
147
148 /**
149 * Whether current UA supoprts the native "paste" event type.
150 * @const {boolean}
151 */
152 goog.events.PasteHandler.SUPPORTS_NATIVE_PASTE_EVENT = goog.userAgent.WEBKIT ||
153 goog.userAgent.IE || goog.userAgent.EDGE ||
154 (goog.userAgent.GECKO && goog.userAgent.isVersionOrHigher('1.9'));
155
156
157 /**
158 * The period between each time we check whether the pasted text appears in the
159 * text element or not.
160 * @type {number}
161 * @private
162 */
163 goog.events.PasteHandler.PASTE_POLLING_PERIOD_MS_ = 50;
164
165
166 /**
167 * The maximum amount of time we want to poll for changes.
168 * @type {number}
169 * @private
170 */
171 goog.events.PasteHandler.PASTE_POLLING_TIMEOUT_MS_ = 200;
172
173
174 /**
175 * The states that this class can be found, on the paste detection algorithm.
176 * @enum {string}
177 */
178 goog.events.PasteHandler.State = {
179 INIT: 'init',
180 FOCUSED: 'focused',
181 TYPING: 'typing'
182 };
183
184
185 /**
186 * The initial state of the paste detection algorithm.
187 * @type {goog.events.PasteHandler.State}
188 * @private
189 */
190 goog.events.PasteHandler.prototype.state_ = goog.events.PasteHandler.State.INIT;
191
192
193 /**
194 * The previous event that caused us to be on the current state.
195 * @type {?string}
196 * @private
197 */
198 goog.events.PasteHandler.prototype.previousEvent_;
199
200
201 /**
202 * A logger, used to help us debug the algorithm.
203 * @type {goog.log.Logger}
204 * @private
205 */
206 goog.events.PasteHandler.prototype.logger_ =
207 goog.log.getLogger('goog.events.PasteHandler');
208
209
210 /** @override */
211 goog.events.PasteHandler.prototype.disposeInternal = function() {
212 goog.events.PasteHandler.superClass_.disposeInternal.call(this);
213 this.eventHandler_.dispose();
214 this.eventHandler_ = null;
215 this.delay_.dispose();
216 this.delay_ = null;
217 };
218
219
220 /**
221 * Returns the current state of the paste detection algorithm. Used mostly for
222 * testing.
223 * @return {goog.events.PasteHandler.State} The current state of the class.
224 */
225 goog.events.PasteHandler.prototype.getState = function() {
226 return this.state_;
227 };
228
229
230 /**
231 * Returns the event handler.
232 * @return {goog.events.EventHandler<T>} The event handler.
233 * @protected
234 * @this {T}
235 * @template T
236 */
237 goog.events.PasteHandler.prototype.getEventHandler = function() {
238 return this.eventHandler_;
239 };
240
241
242 /**
243 * Checks whether the element.value property was updated, and if so, dispatches
244 * the event that let clients know that the text is available.
245 * @return {boolean} Whether the polling should stop or not, based on whether
246 * we found a text change or not.
247 * @private
248 */
249 goog.events.PasteHandler.prototype.checkUpdatedText_ = function() {
250 if (this.oldValue_ == this.element_.value) {
251 return false;
252 }
253 goog.log.info(this.logger_, 'detected textchange after paste');
254 this.dispatchEvent(goog.events.PasteHandler.EventType.AFTER_PASTE);
255 return true;
256 };
257
258
259 /**
260 * Dispatches the paste event.
261 * @param {goog.events.BrowserEvent} e The underlying browser event.
262 * @private
263 */
264 goog.events.PasteHandler.prototype.dispatch_ = function(e) {
265 var event = new goog.events.BrowserEvent(e.getBrowserEvent());
266 event.type = goog.events.PasteHandler.EventType.PASTE;
267 this.dispatchEvent(event);
268
269 // Starts polling for updates in the element.value property so we can tell
270 // when do dispatch the AFTER_PASTE event. (We do an initial check after an
271 // async delay of 0 msec since some browsers update the text right away and
272 // our poller will always wait one period before checking).
273 goog.Timer.callOnce(function() {
274 if (!this.checkUpdatedText_()) {
275 this.delay_.start(
276 goog.events.PasteHandler.PASTE_POLLING_PERIOD_MS_,
277 goog.events.PasteHandler.PASTE_POLLING_TIMEOUT_MS_);
278 }
279 }, 0, this);
280 };
281
282
283 /**
284 * The main event handler which implements a state machine.
285 *
286 * To handle FF2, we enumerate and cover all the known ways a user can paste:
287 *
288 * 1) ctrl+v, shift+insert, cmd+v
289 * 2) right click -> paste
290 * 3) edit menu -> paste
291 * 4) drag and drop
292 * 5) middle click
293 *
294 * (1) is easy and can be detected by listening for key events and finding out
295 * which keys are pressed. (2), (3), (4) and (5) do not generate a key event,
296 * so we need to listen for more than that. (2-5) all generate 'input' events,
297 * but so does key events. So we need to have some sort of 'how did the input
298 * event was generated' history algorithm.
299 *
300 * (2) is an interesting case in Opera on a Mac: since Macs does not have two
301 * buttons, right clicking involves pressing the CTRL key. Even more interesting
302 * is the fact that opera does NOT set the e.ctrlKey bit. Instead, it sets
303 * e.keyCode = 0.
304 * {@link http://www.quirksmode.org/js/keys.html}
305 *
306 * (1) is also an interesting case in Opera on a Mac: Opera is the only browser
307 * covered by this class that can detect the cmd key (FF2 can't apparently). And
308 * it fires e.keyCode = 17, which is the CTRL key code.
309 * {@link http://www.quirksmode.org/js/keys.html}
310 *
311 * NOTE(user, pbarry): There is an interesting thing about (5): on Linux, (5)
312 * pastes the last thing that you highlighted, not the last thing that you
313 * ctrl+c'ed. This code will still generate a {@code PASTE} event though.
314 *
315 * We enumerate all the possible steps a user can take to paste text and we
316 * implemented the transition between the steps in a state machine. The
317 * following is the design of the state machine:
318 *
319 * matching paths:
320 *
321 * (1) happens on INIT -> FOCUSED -> TYPING -> [e.ctrlKey & e.keyCode = 'v']
322 * (2-3) happens on INIT -> FOCUSED -> [input event happened]
323 * (4) happens on INIT -> [mouseover && text changed]
324 *
325 * non matching paths:
326 *
327 * user is typing normally
328 * INIT -> FOCUS -> TYPING -> INPUT -> INIT
329 *
330 * @param {goog.events.BrowserEvent} e The underlying browser event.
331 * @private
332 */
333 goog.events.PasteHandler.prototype.handleEvent_ = function(e) {
334 // transition between states happen at each browser event, and depend on the
335 // current state, the event that led to this state, and the event input.
336 switch (this.state_) {
337 case goog.events.PasteHandler.State.INIT: {
338 this.handleUnderInit_(e);
339 break;
340 }
341 case goog.events.PasteHandler.State.FOCUSED: {
342 this.handleUnderFocused_(e);
343 break;
344 }
345 case goog.events.PasteHandler.State.TYPING: {
346 this.handleUnderTyping_(e);
347 break;
348 }
349 default: {
350 goog.log.error(this.logger_, 'invalid ' + this.state_ + ' state');
351 }
352 }
353 this.lastTime_ = goog.now();
354 this.oldValue_ = this.element_.value;
355 goog.log.info(this.logger_, e.type + ' -> ' + this.state_);
356 this.previousEvent_ = e.type;
357 };
358
359
360 /**
361 * {@code goog.events.PasteHandler.EventType.INIT} is the first initial state
362 * the textarea is found. You can only leave this state by setting focus on the
363 * textarea, which is how users will input text. You can also paste things using
364 * drag and drop, which will not generate a {@code goog.events.EventType.FOCUS}
365 * event, but will generate a {@code goog.events.EventType.MOUSEOVER}.
366 *
367 * For browsers that support the 'paste' event, we match it and stay on the same
368 * state.
369 *
370 * @param {goog.events.BrowserEvent} e The underlying browser event.
371 * @private
372 */
373 goog.events.PasteHandler.prototype.handleUnderInit_ = function(e) {
374 switch (e.type) {
375 case goog.events.EventType.BLUR: {
376 this.state_ = goog.events.PasteHandler.State.INIT;
377 break;
378 }
379 case goog.events.EventType.FOCUS: {
380 this.state_ = goog.events.PasteHandler.State.FOCUSED;
381 break;
382 }
383 case goog.events.EventType.MOUSEOVER: {
384 this.state_ = goog.events.PasteHandler.State.INIT;
385 if (this.element_.value != this.oldValue_) {
386 goog.log.info(this.logger_, 'paste by dragdrop while on init!');
387 this.dispatch_(e);
388 }
389 break;
390 }
391 default: {
392 goog.log.error(
393 this.logger_, 'unexpected event ' + e.type + 'during init');
394 }
395 }
396 };
397
398
399 /**
400 * {@code goog.events.PasteHandler.EventType.FOCUSED} is typically the second
401 * state the textarea will be, which is followed by the {@code INIT} state. On
402 * this state, users can paste in three different ways: edit -> paste,
403 * right click -> paste and drag and drop.
404 *
405 * The latter will generate a {@code goog.events.EventType.MOUSEOVER} event,
406 * which we match by making sure the textarea text changed. The first two will
407 * generate an 'input', which we match by making sure it was NOT generated by a
408 * key event (which also generates an 'input' event).
409 *
410 * Unfortunately, in Firefox, if you type fast, some KEYDOWN events are
411 * swallowed but an INPUT event may still happen. That means we need to
412 * differentiate between two consecutive INPUT events being generated either by
413 * swallowed key events OR by a valid edit -> paste -> edit -> paste action. We
414 * do this by checking a minimum time between the two events. This heuristic
415 * seems to work well, but it is obviously a heuristic :).
416 *
417 * @param {goog.events.BrowserEvent} e The underlying browser event.
418 * @private
419 */
420 goog.events.PasteHandler.prototype.handleUnderFocused_ = function(e) {
421 switch (e.type) {
422 case 'input': {
423 // there are two different events that happen in practice that involves
424 // consecutive 'input' events. we use a heuristic to differentiate
425 // between the one that generates a valid paste action and the one that
426 // doesn't.
427 // @see testTypingReallyFastDispatchesTwoInputEventsBeforeTheKEYDOWNEvent
428 // and
429 // @see testRightClickRightClickAlsoDispatchesTwoConsecutiveInputEvents
430 // Notice that an 'input' event may be also triggered by a 'middle click'
431 // paste event, which is described in
432 // @see testMiddleClickWithoutFocusTriggersPasteEvent
433 var minimumMilisecondsBetweenInputEvents = this.lastTime_ +
434 goog.events.PasteHandler
435 .MANDATORY_MS_BETWEEN_INPUT_EVENTS_TIE_BREAKER;
436 if (goog.now() > minimumMilisecondsBetweenInputEvents ||
437 this.previousEvent_ == goog.events.EventType.FOCUS) {
438 goog.log.info(this.logger_, 'paste by textchange while focused!');
439 this.dispatch_(e);
440 }
441 break;
442 }
443 case goog.events.EventType.BLUR: {
444 this.state_ = goog.events.PasteHandler.State.INIT;
445 break;
446 }
447 case goog.events.EventType.KEYDOWN: {
448 goog.log.info(this.logger_, 'key down ... looking for ctrl+v');
449 // Opera + MAC does not set e.ctrlKey. Instead, it gives me e.keyCode = 0.
450 // http://www.quirksmode.org/js/keys.html
451 if (goog.userAgent.MAC && goog.userAgent.OPERA && e.keyCode == 0 ||
452 goog.userAgent.MAC && goog.userAgent.OPERA && e.keyCode == 17) {
453 break;
454 }
455 this.state_ = goog.events.PasteHandler.State.TYPING;
456 break;
457 }
458 case goog.events.EventType.MOUSEOVER: {
459 if (this.element_.value != this.oldValue_) {
460 goog.log.info(this.logger_, 'paste by dragdrop while focused!');
461 this.dispatch_(e);
462 }
463 break;
464 }
465 default: {
466 goog.log.error(
467 this.logger_, 'unexpected event ' + e.type + ' during focused');
468 }
469 }
470 };
471
472
473 /**
474 * {@code goog.events.PasteHandler.EventType.TYPING} is the third state
475 * this class can be. It exists because each KEYPRESS event will ALSO generate
476 * an INPUT event (because the textarea value changes), and we need to
477 * differentiate between an INPUT event generated by a key event and an INPUT
478 * event generated by edit -> paste actions.
479 *
480 * This is the state that we match the ctrl+v pattern.
481 *
482 * @param {goog.events.BrowserEvent} e The underlying browser event.
483 * @private
484 */
485 goog.events.PasteHandler.prototype.handleUnderTyping_ = function(e) {
486 switch (e.type) {
487 case 'input': {
488 this.state_ = goog.events.PasteHandler.State.FOCUSED;
489 break;
490 }
491 case goog.events.EventType.BLUR: {
492 this.state_ = goog.events.PasteHandler.State.INIT;
493 break;
494 }
495 case goog.events.EventType.KEYDOWN: {
496 if (e.ctrlKey && e.keyCode == goog.events.KeyCodes.V ||
497 e.shiftKey && e.keyCode == goog.events.KeyCodes.INSERT ||
498 e.metaKey && e.keyCode == goog.events.KeyCodes.V) {
499 goog.log.info(this.logger_, 'paste by ctrl+v while keypressed!');
500 this.dispatch_(e);
501 }
502 break;
503 }
504 case goog.events.EventType.MOUSEOVER: {
505 if (this.element_.value != this.oldValue_) {
506 goog.log.info(this.logger_, 'paste by dragdrop while keypressed!');
507 this.dispatch_(e);
508 }
509 break;
510 }
511 default: {
512 goog.log.error(
513 this.logger_, 'unexpected event ' + e.type + ' during keypressed');
514 }
515 }
516 };