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