Debian Codegraph @

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

raw
1 // Copyright 2007 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 This file contains a class to provide a unified mechanism for
17 * CLICK and enter KEYDOWN events. This provides better accessibility by
18 * providing the given functionality to a keyboard user which is otherwise
19 * would be available only via a mouse click.
20 *
21 * If there is an existing CLICK listener or planning to be added as below -
22 *
23 * <code>this.eventHandler_.listen(el, CLICK, this.onClick_);<code>
24 *
25 * it can be replaced with an ACTION listener as follows:
26 *
27 * <code>this.eventHandler_.listen(
28 * new goog.events.ActionHandler(el),
29 * ACTION,
30 * this.onAction_);<code>
31 *
32 */
33
34 goog.provide('goog.events.ActionEvent');
35 goog.provide('goog.events.ActionHandler');
36 goog.provide('goog.events.ActionHandler.EventType');
37 goog.provide('goog.events.BeforeActionEvent');
38
39 goog.require('goog.events');
40 goog.require('goog.events.BrowserEvent');
41 goog.require('goog.events.EventTarget');
42 goog.require('goog.events.EventType');
43 goog.require('goog.events.KeyCodes');
44 goog.require('goog.userAgent');
45
46
47
48 /**
49 * A wrapper around an element that you want to listen to ACTION events on.
50 * @param {Element|Document} element The element or document to listen on.
51 * @constructor
52 * @extends {goog.events.EventTarget}
53 * @final
54 */
55 goog.events.ActionHandler = function(element) {
56 goog.events.EventTarget.call(this);
57
58 /**
59 * This is the element that we will listen to events on.
60 * @type {Element|Document}
61 * @private
62 */
63 this.element_ = element;
64
65 goog.events.listen(
66 element, goog.events.ActionHandler.KEY_EVENT_TYPE_, this.handleKeyDown_,
67 false, this);
68 goog.events.listen(
69 element, goog.events.EventType.CLICK, this.handleClick_, false, this);
70 };
71 goog.inherits(goog.events.ActionHandler, goog.events.EventTarget);
72
73
74 /**
75 * Enum type for the events fired by the action handler
76 * @enum {string}
77 */
78 goog.events.ActionHandler.EventType = {
79 ACTION: 'action',
80 BEFOREACTION: 'beforeaction'
81 };
82
83
84 /**
85 * Key event type to listen for.
86 * @type {string}
87 * @private
88 */
89 goog.events.ActionHandler.KEY_EVENT_TYPE_ = goog.userAgent.GECKO ?
90 goog.events.EventType.KEYPRESS :
91 goog.events.EventType.KEYDOWN;
92
93
94 /**
95 * Handles key press events.
96 * @param {!goog.events.BrowserEvent} e The key press event.
97 * @private
98 */
99 goog.events.ActionHandler.prototype.handleKeyDown_ = function(e) {
100 if (e.keyCode == goog.events.KeyCodes.ENTER ||
101 goog.userAgent.WEBKIT && e.keyCode == goog.events.KeyCodes.MAC_ENTER) {
102 this.dispatchEvents_(e);
103 }
104 };
105
106
107 /**
108 * Handles mouse events.
109 * @param {!goog.events.BrowserEvent} e The click event.
110 * @private
111 */
112 goog.events.ActionHandler.prototype.handleClick_ = function(e) {
113 this.dispatchEvents_(e);
114 };
115
116
117 /**
118 * Dispatches BeforeAction and Action events to the element
119 * @param {!goog.events.BrowserEvent} e The event causing dispatches.
120 * @private
121 */
122 goog.events.ActionHandler.prototype.dispatchEvents_ = function(e) {
123 var beforeActionEvent = new goog.events.BeforeActionEvent(e);
124
125 // Allow application specific logic here before the ACTION event.
126 // For example, Gmail uses this event to restore keyboard focus
127 if (!this.dispatchEvent(beforeActionEvent)) {
128 // If the listener swallowed the BEFOREACTION event, don't dispatch the
129 // ACTION event.
130 return;
131 }
132
133
134 // Wrap up original event and send it off
135 var actionEvent = new goog.events.ActionEvent(e);
136 try {
137 this.dispatchEvent(actionEvent);
138 } finally {
139 // Stop propagating the event
140 e.stopPropagation();
141 }
142 };
143
144
145 /** @override */
146 goog.events.ActionHandler.prototype.disposeInternal = function() {
147 goog.events.ActionHandler.superClass_.disposeInternal.call(this);
148 goog.events.unlisten(
149 this.element_, goog.events.ActionHandler.KEY_EVENT_TYPE_,
150 this.handleKeyDown_, false, this);
151 goog.events.unlisten(
152 this.element_, goog.events.EventType.CLICK, this.handleClick_, false,
153 this);
154 delete this.element_;
155 };
156
157
158
159 /**
160 * This class is used for the goog.events.ActionHandler.EventType.ACTION event.
161 * @param {!goog.events.BrowserEvent} browserEvent Browser event object.
162 * @constructor
163 * @extends {goog.events.BrowserEvent}
164 * @final
165 */
166 goog.events.ActionEvent = function(browserEvent) {
167 goog.events.BrowserEvent.call(this, browserEvent.getBrowserEvent());
168 this.type = goog.events.ActionHandler.EventType.ACTION;
169 };
170 goog.inherits(goog.events.ActionEvent, goog.events.BrowserEvent);
171
172
173
174 /**
175 * This class is used for the goog.events.ActionHandler.EventType.BEFOREACTION
176 * event. BEFOREACTION gives a chance to the application so the keyboard focus
177 * can be restored back, if required.
178 * @param {!goog.events.BrowserEvent} browserEvent Browser event object.
179 * @constructor
180 * @extends {goog.events.BrowserEvent}
181 * @final
182 */
183 goog.events.BeforeActionEvent = function(browserEvent) {
184 goog.events.BrowserEvent.call(this, browserEvent.getBrowserEvent());
185 this.type = goog.events.ActionHandler.EventType.BEFOREACTION;
186 };
187 goog.inherits(goog.events.BeforeActionEvent, goog.events.BrowserEvent);