lib/goog/events/listener.js

1// Copyright 2005 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 Listener object.
17 * @see ../demos/events.html
18 */
19
20goog.provide('goog.events.Listener');
21
22goog.require('goog.events.ListenableKey');
23
24
25
26/**
27 * Simple class that stores information about a listener
28 * @param {!Function} listener Callback function.
29 * @param {Function} proxy Wrapper for the listener that patches the event.
30 * @param {EventTarget|goog.events.Listenable} src Source object for
31 *     the event.
32 * @param {string} type Event type.
33 * @param {boolean} capture Whether in capture or bubble phase.
34 * @param {Object=} opt_handler Object in whose context to execute the callback.
35 * @implements {goog.events.ListenableKey}
36 * @constructor
37 */
38goog.events.Listener = function(
39    listener, proxy, src, type, capture, opt_handler) {
40  if (goog.events.Listener.ENABLE_MONITORING) {
41    this.creationStack = new Error().stack;
42  }
43
44  /**
45   * Callback function.
46   * @type {Function}
47   */
48  this.listener = listener;
49
50  /**
51   * A wrapper over the original listener. This is used solely to
52   * handle native browser events (it is used to simulate the capture
53   * phase and to patch the event object).
54   * @type {Function}
55   */
56  this.proxy = proxy;
57
58  /**
59   * Object or node that callback is listening to
60   * @type {EventTarget|goog.events.Listenable}
61   */
62  this.src = src;
63
64  /**
65   * The event type.
66   * @const {string}
67   */
68  this.type = type;
69
70  /**
71   * Whether the listener is being called in the capture or bubble phase
72   * @const {boolean}
73   */
74  this.capture = !!capture;
75
76  /**
77   * Optional object whose context to execute the listener in
78   * @type {Object|undefined}
79   */
80  this.handler = opt_handler;
81
82  /**
83   * The key of the listener.
84   * @const {number}
85   * @override
86   */
87  this.key = goog.events.ListenableKey.reserveKey();
88
89  /**
90   * Whether to remove the listener after it has been called.
91   * @type {boolean}
92   */
93  this.callOnce = false;
94
95  /**
96   * Whether the listener has been removed.
97   * @type {boolean}
98   */
99  this.removed = false;
100};
101
102
103/**
104 * @define {boolean} Whether to enable the monitoring of the
105 *     goog.events.Listener instances. Switching on the monitoring is only
106 *     recommended for debugging because it has a significant impact on
107 *     performance and memory usage. If switched off, the monitoring code
108 *     compiles down to 0 bytes.
109 */
110goog.define('goog.events.Listener.ENABLE_MONITORING', false);
111
112
113/**
114 * If monitoring the goog.events.Listener instances is enabled, stores the
115 * creation stack trace of the Disposable instance.
116 * @type {string}
117 */
118goog.events.Listener.prototype.creationStack;
119
120
121/**
122 * Marks this listener as removed. This also remove references held by
123 * this listener object (such as listener and event source).
124 */
125goog.events.Listener.prototype.markAsRemoved = function() {
126  this.removed = true;
127  this.listener = null;
128  this.proxy = null;
129  this.src = null;
130  this.handler = null;
131};