Debian Codegraph @

closure-library/closure/goog/ui/button.js

raw
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 A button control. This implementation extends {@link
17 * goog.ui.Control}.
18 *
19 * @author [email protected] (Attila Bodis)
20 * @see ../demos/button.html
21 */
22
23 goog.provide('goog.ui.Button');
24 goog.provide('goog.ui.Button.Side');
25
26 goog.require('goog.events.EventType');
27 goog.require('goog.events.KeyCodes');
28 goog.require('goog.events.KeyHandler');
29 goog.require('goog.ui.ButtonRenderer');
30 goog.require('goog.ui.ButtonSide');
31 goog.require('goog.ui.Component');
32 goog.require('goog.ui.Control');
33 goog.require('goog.ui.NativeButtonRenderer');
34 goog.require('goog.ui.registry');
35
36
37
38 /**
39 * A button control, rendered as a native browser button by default.
40 *
41 * @param {goog.ui.ControlContent=} opt_content Text caption or existing DOM
42 * structure to display as the button's caption (if any).
43 * @param {goog.ui.ButtonRenderer=} opt_renderer Renderer used to render or
44 * decorate the button; defaults to {@link goog.ui.NativeButtonRenderer}.
45 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper, used for
46 * document interaction.
47 * @constructor
48 * @extends {goog.ui.Control}
49 */
50 goog.ui.Button = function(opt_content, opt_renderer, opt_domHelper) {
51 goog.ui.Control.call(
52 this, opt_content,
53 opt_renderer || goog.ui.NativeButtonRenderer.getInstance(),
54 opt_domHelper);
55 };
56 goog.inherits(goog.ui.Button, goog.ui.Control);
57 goog.tagUnsealableClass(goog.ui.Button);
58
59
60 /**
61 * Constants for button sides, see {@link goog.ui.Button.prototype.setCollapsed}
62 * for details. Aliased from goog.ui.ButtonSide to support legacy users without
63 * creating a circular dependency in {@link goog.ui.ButtonRenderer}.
64 * @enum {number}
65 * @deprecated use {@link goog.ui.ButtonSide} instead.
66 */
67 goog.ui.Button.Side = goog.ui.ButtonSide;
68
69
70 /**
71 * Value associated with the button.
72 * @type {*}
73 * @private
74 */
75 goog.ui.Button.prototype.value_;
76
77
78 /**
79 * Tooltip text for the button, displayed on hover.
80 * @type {string|undefined}
81 * @private
82 */
83 goog.ui.Button.prototype.tooltip_;
84
85
86 // goog.ui.Button API implementation.
87
88
89 /**
90 * Returns the value associated with the button.
91 * @return {*} Button value (undefined if none).
92 */
93 goog.ui.Button.prototype.getValue = function() {
94 return this.value_;
95 };
96
97
98 /**
99 * Sets the value associated with the button, and updates its DOM.
100 * @param {*} value New button value.
101 */
102 goog.ui.Button.prototype.setValue = function(value) {
103 this.value_ = value;
104 var renderer = /** @type {!goog.ui.ButtonRenderer} */ (this.getRenderer());
105 renderer.setValue(this.getElement(), /** @type {string} */ (value));
106 };
107
108
109 /**
110 * Sets the value associated with the button. Unlike {@link #setValue},
111 * doesn't update the button's DOM. Considered protected; to be called only
112 * by renderer code during element decoration.
113 * @param {*} value New button value.
114 * @protected
115 */
116 goog.ui.Button.prototype.setValueInternal = function(value) {
117 this.value_ = value;
118 };
119
120
121 /**
122 * Returns the tooltip for the button.
123 * @return {string|undefined} Tooltip text (undefined if none).
124 */
125 goog.ui.Button.prototype.getTooltip = function() {
126 return this.tooltip_;
127 };
128
129
130 /**
131 * Sets the tooltip for the button, and updates its DOM.
132 * @param {string} tooltip New tooltip text.
133 */
134 goog.ui.Button.prototype.setTooltip = function(tooltip) {
135 this.tooltip_ = tooltip;
136 this.getRenderer().setTooltip(this.getElement(), tooltip);
137 };
138
139
140 /**
141 * Sets the tooltip for the button. Unlike {@link #setTooltip}, doesn't update
142 * the button's DOM. Considered protected; to be called only by renderer code
143 * during element decoration.
144 * @param {string} tooltip New tooltip text.
145 * @protected
146 */
147 goog.ui.Button.prototype.setTooltipInternal = function(tooltip) {
148 this.tooltip_ = tooltip;
149 };
150
151
152 /**
153 * Collapses the border on one or both sides of the button, allowing it to be
154 * combined with the adjancent button(s), forming a single UI componenet with
155 * multiple targets.
156 * @param {number} sides Bitmap of one or more {@link goog.ui.ButtonSide}s for
157 * which borders should be collapsed.
158 */
159 goog.ui.Button.prototype.setCollapsed = function(sides) {
160 this.getRenderer().setCollapsed(this, sides);
161 };
162
163
164 // goog.ui.Control & goog.ui.Component API implementation.
165
166
167 /** @override */
168 goog.ui.Button.prototype.disposeInternal = function() {
169 goog.ui.Button.superClass_.disposeInternal.call(this);
170 delete this.value_;
171 delete this.tooltip_;
172 };
173
174
175 /** @override */
176 goog.ui.Button.prototype.enterDocument = function() {
177 goog.ui.Button.superClass_.enterDocument.call(this);
178 if (this.isSupportedState(goog.ui.Component.State.FOCUSED)) {
179 var keyTarget = this.getKeyEventTarget();
180 if (keyTarget) {
181 this.getHandler().listen(
182 keyTarget, goog.events.EventType.KEYUP, this.handleKeyEventInternal);
183 }
184 }
185 };
186
187
188 /**
189 * Attempts to handle a keyboard event; returns true if the event was handled,
190 * false otherwise. If the button is enabled and the Enter/Space key was
191 * pressed, handles the event by dispatching an {@code ACTION} event,
192 * and returns true. Overrides {@link goog.ui.Control#handleKeyEventInternal}.
193 * @param {goog.events.KeyEvent} e Key event to handle.
194 * @return {boolean} Whether the key event was handled.
195 * @protected
196 * @override
197 */
198 goog.ui.Button.prototype.handleKeyEventInternal = function(e) {
199 if (e.keyCode == goog.events.KeyCodes.ENTER &&
200 e.type == goog.events.KeyHandler.EventType.KEY ||
201 e.keyCode == goog.events.KeyCodes.SPACE &&
202 e.type == goog.events.EventType.KEYUP) {
203 return this.performActionInternal(e);
204 }
205 // Return true for space keypress (even though the event is handled on keyup)
206 // as preventDefault needs to be called up keypress to take effect in IE and
207 // WebKit.
208 return e.keyCode == goog.events.KeyCodes.SPACE;
209 };
210
211
212 // Register a decorator factory function for goog.ui.Buttons.
213 goog.ui.registry.setDecoratorByClassName(
214 goog.ui.ButtonRenderer.CSS_CLASS,
215 function() { return new goog.ui.Button(null); });