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};