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);
188

189