Debian Codegraph @

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

raw
1 // Copyright 2008 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 Default renderer for {@link goog.ui.Button}s.
17 *
18 * @author [email protected] (Attila Bodis)
19 */
20
21 goog.provide('goog.ui.ButtonRenderer');
22
23 goog.require('goog.a11y.aria');
24 goog.require('goog.a11y.aria.Role');
25 goog.require('goog.a11y.aria.State');
26 goog.require('goog.asserts');
27 goog.require('goog.ui.ButtonSide');
28 goog.require('goog.ui.Component');
29 goog.require('goog.ui.ControlRenderer');
30
31 goog.forwardDeclare('goog.ui.Button'); // circular
32
33
34
35 /**
36 * Default renderer for {@link goog.ui.Button}s. Extends the superclass with
37 * the following button-specific API methods:
38 * <ul>
39 * <li>{@code getValue} - returns the button element's value
40 * <li>{@code setValue} - updates the button element to reflect its new value
41 * <li>{@code getTooltip} - returns the button element's tooltip text
42 * <li>{@code setTooltip} - updates the button element's tooltip text
43 * <li>{@code setCollapsed} - removes one or both of the button element's
44 * borders
45 * </ul>
46 * For alternate renderers, see {@link goog.ui.NativeButtonRenderer},
47 * {@link goog.ui.CustomButtonRenderer}, and {@link goog.ui.FlatButtonRenderer}.
48 * @constructor
49 * @extends {goog.ui.ControlRenderer}
50 */
51 goog.ui.ButtonRenderer = function() {
52 goog.ui.ControlRenderer.call(this);
53 };
54 goog.inherits(goog.ui.ButtonRenderer, goog.ui.ControlRenderer);
55 goog.addSingletonGetter(goog.ui.ButtonRenderer);
56
57
58 /**
59 * Default CSS class to be applied to the root element of components rendered
60 * by this renderer.
61 * @type {string}
62 */
63 goog.ui.ButtonRenderer.CSS_CLASS = goog.getCssName('goog-button');
64
65
66 /**
67 * Returns the ARIA role to be applied to buttons.
68 * @return {goog.a11y.aria.Role|undefined} ARIA role.
69 * @override
70 */
71 goog.ui.ButtonRenderer.prototype.getAriaRole = function() {
72 return goog.a11y.aria.Role.BUTTON;
73 };
74
75
76 /**
77 * Updates the button's ARIA (accessibility) state if the button is being
78 * treated as a checkbox. Also makes sure that attributes which aren't
79 * supported by buttons aren't being added.
80 * @param {Element} element Element whose ARIA state is to be updated.
81 * @param {goog.ui.Component.State} state Component state being enabled or
82 * disabled.
83 * @param {boolean} enable Whether the state is being enabled or disabled.
84 * @protected
85 * @override
86 */
87 goog.ui.ButtonRenderer.prototype.updateAriaState = function(
88 element, state, enable) {
89 switch (state) {
90 // If button has CHECKED or SELECTED state, assign aria-pressed
91 case goog.ui.Component.State.SELECTED:
92 case goog.ui.Component.State.CHECKED:
93 goog.asserts.assert(element, 'The button DOM element cannot be null.');
94 goog.a11y.aria.setState(element, goog.a11y.aria.State.PRESSED, enable);
95 break;
96 default:
97 case goog.ui.Component.State.OPENED:
98 case goog.ui.Component.State.DISABLED:
99 goog.ui.ButtonRenderer.base(
100 this, 'updateAriaState', element, state, enable);
101 break;
102 }
103 };
104
105
106 /** @override */
107 goog.ui.ButtonRenderer.prototype.createDom = function(button) {
108 var element = goog.ui.ButtonRenderer.base(this, 'createDom', button);
109 this.setTooltip(element, button.getTooltip());
110
111 var value = button.getValue();
112 if (value) {
113 this.setValue(element, value);
114 }
115
116 // If this is a toggle button, set ARIA state
117 if (button.isSupportedState(goog.ui.Component.State.CHECKED)) {
118 this.updateAriaState(
119 element, goog.ui.Component.State.CHECKED, button.isChecked());
120 }
121
122 return element;
123 };
124
125
126 /** @override */
127 goog.ui.ButtonRenderer.prototype.decorate = function(button, element) {
128 // The superclass implementation takes care of common attributes; we only
129 // need to set the value and the tooltip.
130 element =
131 goog.ui.ButtonRenderer.superClass_.decorate.call(this, button, element);
132
133 button.setValueInternal(this.getValue(element));
134 button.setTooltipInternal(this.getTooltip(element));
135
136 // If this is a toggle button, set ARIA state
137 if (button.isSupportedState(goog.ui.Component.State.CHECKED)) {
138 this.updateAriaState(
139 element, goog.ui.Component.State.CHECKED, button.isChecked());
140 }
141
142 return element;
143 };
144
145
146 /**
147 * Takes a button's root element, and returns the value associated with it.
148 * No-op in the base class.
149 * @param {Element} element The button's root element.
150 * @return {string|undefined} The button's value (undefined if none).
151 */
152 goog.ui.ButtonRenderer.prototype.getValue = goog.nullFunction;
153
154
155 /**
156 * Takes a button's root element and a value, and updates the element to reflect
157 * the new value. No-op in the base class.
158 * @param {Element} element The button's root element.
159 * @param {string} value New value.
160 */
161 goog.ui.ButtonRenderer.prototype.setValue = goog.nullFunction;
162
163
164 /**
165 * Takes a button's root element, and returns its tooltip text.
166 * @param {Element} element The button's root element.
167 * @return {string|undefined} The tooltip text.
168 */
169 goog.ui.ButtonRenderer.prototype.getTooltip = function(element) {
170 return element.title;
171 };
172
173
174 /**
175 * Takes a button's root element and a tooltip string, and updates the element
176 * with the new tooltip.
177 * @param {Element} element The button's root element.
178 * @param {string} tooltip New tooltip text.
179 * @protected
180 */
181 goog.ui.ButtonRenderer.prototype.setTooltip = function(element, tooltip) {
182 if (element) {
183 // Don't set a title attribute if there isn't a tooltip. Blank title
184 // attributes can be interpreted incorrectly by screen readers.
185 if (tooltip) {
186 element.title = tooltip;
187 } else {
188 element.removeAttribute('title');
189 }
190 }
191 };
192
193
194 /**
195 * Collapses the border on one or both sides of the button, allowing it to be
196 * combined with the adjacent button(s), forming a single UI componenet with
197 * multiple targets.
198 * @param {goog.ui.Button} button Button to update.
199 * @param {number} sides Bitmap of one or more {@link goog.ui.ButtonSide}s for
200 * which borders should be collapsed.
201 * @protected
202 */
203 goog.ui.ButtonRenderer.prototype.setCollapsed = function(button, sides) {
204 var isRtl = button.isRightToLeft();
205 var collapseLeftClassName =
206 goog.getCssName(this.getStructuralCssClass(), 'collapse-left');
207 var collapseRightClassName =
208 goog.getCssName(this.getStructuralCssClass(), 'collapse-right');
209
210 button.enableClassName(
211 isRtl ? collapseRightClassName : collapseLeftClassName,
212 !!(sides & goog.ui.ButtonSide.START));
213 button.enableClassName(
214 isRtl ? collapseLeftClassName : collapseRightClassName,
215 !!(sides & goog.ui.ButtonSide.END));
216 };
217
218
219 /** @override */
220 goog.ui.ButtonRenderer.prototype.getCssClass = function() {
221 return goog.ui.ButtonRenderer.CSS_CLASS;
222 };