# 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 |
20 | goog.provide('goog.events.Listener');
21 |
22 | goog.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 | */
38 | goog.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 | */
110 | goog.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 | */
118 | goog.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 | */
125 | goog.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 | };