Debian Codegraph @

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

raw
1 // Copyright 2009 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 Tristate checkbox widget.
17 *
18 * @see ../demos/checkbox.html
19 */
20
21 goog.provide('goog.ui.Checkbox');
22 goog.provide('goog.ui.Checkbox.State');
23
24 goog.require('goog.a11y.aria');
25 goog.require('goog.a11y.aria.State');
26 goog.require('goog.events.EventType');
27 goog.require('goog.events.KeyCodes');
28 goog.require('goog.string');
29 goog.require('goog.ui.CheckboxRenderer');
30 goog.require('goog.ui.Component');
31 goog.require('goog.ui.Control');
32 goog.require('goog.ui.registry');
33
34
35
36 /**
37 * 3-state checkbox widget. Fires CHECK or UNCHECK events before toggled and
38 * CHANGE event after toggled by user.
39 * The checkbox can also be enabled/disabled and get focused and highlighted.
40 *
41 * @param {goog.ui.Checkbox.State=} opt_checked Checked state to set.
42 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper, used for
43 * document interaction.
44 * @param {goog.ui.CheckboxRenderer=} opt_renderer Renderer used to render or
45 * decorate the checkbox; defaults to {@link goog.ui.CheckboxRenderer}.
46 * @constructor
47 * @extends {goog.ui.Control}
48 */
49 goog.ui.Checkbox = function(opt_checked, opt_domHelper, opt_renderer) {
50 var renderer = opt_renderer || goog.ui.CheckboxRenderer.getInstance();
51 goog.ui.Control.call(this, null, renderer, opt_domHelper);
52 // The checkbox maintains its own tri-state CHECKED state.
53 // The control class maintains DISABLED, ACTIVE, and FOCUSED (which enable tab
54 // navigation, and keyHandling with SPACE).
55
56 /**
57 * Checked state of the checkbox.
58 * @type {goog.ui.Checkbox.State}
59 * @private
60 */
61 this.checked_ =
62 goog.isDef(opt_checked) ? opt_checked : goog.ui.Checkbox.State.UNCHECKED;
63 };
64 goog.inherits(goog.ui.Checkbox, goog.ui.Control);
65 goog.tagUnsealableClass(goog.ui.Checkbox);
66
67
68 /**
69 * Possible checkbox states.
70 * @enum {?boolean}
71 */
72 goog.ui.Checkbox.State = {
73 CHECKED: true,
74 UNCHECKED: false,
75 UNDETERMINED: null
76 };
77
78
79 /**
80 * Label element bound to the checkbox.
81 * @type {Element}
82 * @private
83 */
84 goog.ui.Checkbox.prototype.label_ = null;
85
86
87 /**
88 * @return {goog.ui.Checkbox.State} Checked state of the checkbox.
89 */
90 goog.ui.Checkbox.prototype.getChecked = function() {
91 return this.checked_;
92 };
93
94
95 /**
96 * @return {boolean} Whether the checkbox is checked.
97 * @override
98 */
99 goog.ui.Checkbox.prototype.isChecked = function() {
100 return this.checked_ == goog.ui.Checkbox.State.CHECKED;
101 };
102
103
104 /**
105 * @return {boolean} Whether the checkbox is not checked.
106 */
107 goog.ui.Checkbox.prototype.isUnchecked = function() {
108 return this.checked_ == goog.ui.Checkbox.State.UNCHECKED;
109 };
110
111
112 /**
113 * @return {boolean} Whether the checkbox is in partially checked state.
114 */
115 goog.ui.Checkbox.prototype.isUndetermined = function() {
116 return this.checked_ == goog.ui.Checkbox.State.UNDETERMINED;
117 };
118
119
120 /**
121 * Sets the checked state of the checkbox.
122 * @param {?boolean} checked The checked state to set.
123 * @override
124 */
125 goog.ui.Checkbox.prototype.setChecked = function(checked) {
126 if (checked != this.checked_) {
127 this.checked_ = /** @type {goog.ui.Checkbox.State} */ (checked);
128 this.getRenderer().setCheckboxState(this.getElement(), this.checked_);
129 }
130 };
131
132
133 /**
134 * Sets the checked state for the checkbox. Unlike {@link #setChecked},
135 * doesn't update the checkbox's DOM. Considered protected; to be called
136 * only by renderer code during element decoration.
137 * @param {goog.ui.Checkbox.State} checked New checkbox state.
138 */
139 goog.ui.Checkbox.prototype.setCheckedInternal = function(checked) {
140 this.checked_ = checked;
141 };
142
143
144 /**
145 * Binds an HTML element to the checkbox which if clicked toggles the checkbox.
146 * Behaves the same way as the 'label' HTML tag. The label element has to be the
147 * direct or non-direct ancestor of the checkbox element because it will get the
148 * focus when keyboard support is implemented.
149 * Note: Control#enterDocument also sets aria-label on the element but
150 * Checkbox#enterDocument sets aria-labeledby on the same element which
151 * overrides the aria-label in all modern screen readers.
152 *
153 * @param {?Element} label The label control to set. If null, only the checkbox
154 * reacts to clicks.
155 */
156 goog.ui.Checkbox.prototype.setLabel = function(label) {
157 if (this.isInDocument()) {
158 var wasFocused = this.isFocused();
159 this.exitDocument();
160 this.label_ = label;
161 this.enterDocument();
162 if (wasFocused) {
163 this.getElementStrict().focus();
164 }
165 } else {
166 this.label_ = label;
167 }
168 };
169
170
171 /**
172 * Toggles the checkbox. State transitions:
173 * <ul>
174 * <li>unchecked -> checked
175 * <li>undetermined -> checked
176 * <li>checked -> unchecked
177 * </ul>
178 */
179 goog.ui.Checkbox.prototype.toggle = function() {
180 this.setChecked(
181 this.checked_ ? goog.ui.Checkbox.State.UNCHECKED :
182 goog.ui.Checkbox.State.CHECKED);
183 };
184
185
186 /** @override */
187 goog.ui.Checkbox.prototype.enterDocument = function() {
188 goog.ui.Checkbox.base(this, 'enterDocument');
189 if (this.isHandleMouseEvents()) {
190 var handler = this.getHandler();
191 // Listen to the label, if it was set.
192 if (this.label_) {
193 // Any mouse events that happen to the associated label should have the
194 // same effect on the checkbox as if they were happening to the checkbox
195 // itself.
196 handler
197 .listen(
198 this.label_, goog.events.EventType.CLICK,
199 this.handleClickOrSpace_)
200 .listen(
201 this.label_, goog.events.EventType.MOUSEOVER,
202 this.handleMouseOver)
203 .listen(
204 this.label_, goog.events.EventType.MOUSEOUT, this.handleMouseOut)
205 .listen(
206 this.label_, goog.events.EventType.MOUSEDOWN,
207 this.handleMouseDown)
208 .listen(
209 this.label_, goog.events.EventType.MOUSEUP, this.handleMouseUp);
210 }
211 // Checkbox needs to explicitly listen for click event.
212 handler.listen(
213 this.getElement(), goog.events.EventType.CLICK,
214 this.handleClickOrSpace_);
215 }
216
217 // Set aria label.
218 var checkboxElement = this.getElementStrict();
219 if (this.label_ && checkboxElement != this.label_ &&
220 goog.string.isEmptyOrWhitespace(
221 goog.a11y.aria.getLabel(checkboxElement))) {
222 if (!this.label_.id) {
223 this.label_.id = this.makeId('lbl');
224 }
225 goog.a11y.aria.setState(
226 checkboxElement, goog.a11y.aria.State.LABELLEDBY, this.label_.id);
227 }
228 };
229
230
231 /**
232 * Fix for tabindex not being updated so that disabled checkbox is not
233 * focusable. In particular this fails in Chrome.
234 * Note: in general tabIndex=-1 will prevent from keyboard focus but enables
235 * mouse focus, however in this case the control class prevents mouse focus.
236 * @override
237 */
238 goog.ui.Checkbox.prototype.setEnabled = function(enabled) {
239 goog.ui.Checkbox.base(this, 'setEnabled', enabled);
240 var el = this.getElement();
241 if (el) {
242 el.tabIndex = this.isEnabled() ? 0 : -1;
243 }
244 };
245
246
247 /**
248 * Handles the click event.
249 * @param {!goog.events.BrowserEvent} e The event.
250 * @private
251 */
252 goog.ui.Checkbox.prototype.handleClickOrSpace_ = function(e) {
253 e.stopPropagation();
254 var eventType = this.checked_ ? goog.ui.Component.EventType.UNCHECK :
255 goog.ui.Component.EventType.CHECK;
256 if (this.isEnabled() && !e.target.href && this.dispatchEvent(eventType)) {
257 e.preventDefault(); // Prevent scrolling in Chrome if SPACE is pressed.
258 this.toggle();
259 this.dispatchEvent(goog.ui.Component.EventType.CHANGE);
260 }
261 };
262
263
264 /** @override */
265 goog.ui.Checkbox.prototype.handleKeyEventInternal = function(e) {
266 if (e.keyCode == goog.events.KeyCodes.SPACE) {
267 this.performActionInternal(e);
268 this.handleClickOrSpace_(e);
269 }
270 return false;
271 };
272
273
274 /**
275 * Register this control so it can be created from markup.
276 */
277 goog.ui.registry.setDecoratorByClassName(
278 goog.ui.CheckboxRenderer.CSS_CLASS,
279 function() { return new goog.ui.Checkbox(); });