Debian Codegraph @

closure-library/closure/goog/ui/selectionmodel.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 Single-selection model implemenation.
17 *
18 * TODO(attila): Add keyboard & mouse event hooks?
19 * TODO(attila): Add multiple selection?
20 *
21 * @author [email protected] (Attila Bodis)
22 */
23
24
25 goog.provide('goog.ui.SelectionModel');
26
27 goog.require('goog.array');
28 goog.require('goog.events.EventTarget');
29 goog.require('goog.events.EventType');
30
31
32
33 /**
34 * Single-selection model. Dispatches a {@link goog.events.EventType.SELECT}
35 * event when a selection is made.
36 * @param {Array<Object>=} opt_items Array of items; defaults to empty.
37 * @extends {goog.events.EventTarget}
38 * @constructor
39 */
40 goog.ui.SelectionModel = function(opt_items) {
41 goog.events.EventTarget.call(this);
42
43 /**
44 * Array of items controlled by the selection model. If the items support
45 * the {@code setSelected(Boolean)} interface, they will be (de)selected
46 * as needed.
47 * @type {!Array<Object>}
48 * @private
49 */
50 this.items_ = [];
51 this.addItems(opt_items);
52 };
53 goog.inherits(goog.ui.SelectionModel, goog.events.EventTarget);
54 goog.tagUnsealableClass(goog.ui.SelectionModel);
55
56
57 /**
58 * The currently selected item (null if none).
59 * @type {Object}
60 * @private
61 */
62 goog.ui.SelectionModel.prototype.selectedItem_ = null;
63
64
65 /**
66 * Selection handler function. Called with two arguments (the item to be
67 * selected or deselected, and a Boolean indicating whether the item is to
68 * be selected or deselected).
69 * @type {Function}
70 * @private
71 */
72 goog.ui.SelectionModel.prototype.selectionHandler_ = null;
73
74
75 /**
76 * Returns the selection handler function used by the selection model to change
77 * the internal selection state of items under its control.
78 * @return {Function} Selection handler function (null if none).
79 */
80 goog.ui.SelectionModel.prototype.getSelectionHandler = function() {
81 return this.selectionHandler_;
82 };
83
84
85 /**
86 * Sets the selection handler function to be used by the selection model to
87 * change the internal selection state of items under its control. The
88 * function must take two arguments: an item and a Boolean to indicate whether
89 * the item is to be selected or deselected. Selection handler functions are
90 * only needed if the items in the selection model don't natively support the
91 * {@code setSelected(Boolean)} interface.
92 * @param {Function} handler Selection handler function.
93 */
94 goog.ui.SelectionModel.prototype.setSelectionHandler = function(handler) {
95 this.selectionHandler_ = handler;
96 };
97
98
99 /**
100 * Returns the number of items controlled by the selection model.
101 * @return {number} Number of items.
102 */
103 goog.ui.SelectionModel.prototype.getItemCount = function() {
104 return this.items_.length;
105 };
106
107
108 /**
109 * Returns the 0-based index of the given item within the selection model, or
110 * -1 if no such item is found.
111 * @param {Object|undefined} item Item to look for.
112 * @return {number} Index of the given item (-1 if none).
113 */
114 goog.ui.SelectionModel.prototype.indexOfItem = function(item) {
115 return item ? goog.array.indexOf(this.items_, item) : -1;
116 };
117
118
119 /**
120 * @return {Object|undefined} The first item, or undefined if there are no items
121 * in the model.
122 */
123 goog.ui.SelectionModel.prototype.getFirst = function() {
124 return this.items_[0];
125 };
126
127
128 /**
129 * @return {Object|undefined} The last item, or undefined if there are no items
130 * in the model.
131 */
132 goog.ui.SelectionModel.prototype.getLast = function() {
133 return this.items_[this.items_.length - 1];
134 };
135
136
137 /**
138 * Returns the item at the given 0-based index.
139 * @param {number} index Index of the item to return.
140 * @return {Object} Item at the given index (null if none).
141 */
142 goog.ui.SelectionModel.prototype.getItemAt = function(index) {
143 return this.items_[index] || null;
144 };
145
146
147 /**
148 * Bulk-adds items to the selection model. This is more efficient than calling
149 * {@link #addItem} for each new item.
150 * @param {Array<Object>|undefined} items New items to add.
151 */
152 goog.ui.SelectionModel.prototype.addItems = function(items) {
153 if (items) {
154 // New items shouldn't be selected.
155 goog.array.forEach(
156 items, function(item) { this.selectItem_(item, false); }, this);
157 goog.array.extend(this.items_, items);
158 }
159 };
160
161
162 /**
163 * Adds an item at the end of the list.
164 * @param {Object} item Item to add.
165 */
166 goog.ui.SelectionModel.prototype.addItem = function(item) {
167 this.addItemAt(item, this.getItemCount());
168 };
169
170
171 /**
172 * Adds an item at the given index.
173 * @param {Object} item Item to add.
174 * @param {number} index Index at which to add the new item.
175 */
176 goog.ui.SelectionModel.prototype.addItemAt = function(item, index) {
177 if (item) {
178 // New items must not be selected.
179 this.selectItem_(item, false);
180 goog.array.insertAt(this.items_, item, index);
181 }
182 };
183
184
185 /**
186 * Removes the given item (if it exists). Dispatches a {@code SELECT} event if
187 * the removed item was the currently selected item.
188 * @param {Object} item Item to remove.
189 */
190 goog.ui.SelectionModel.prototype.removeItem = function(item) {
191 if (item && goog.array.remove(this.items_, item)) {
192 if (item == this.selectedItem_) {
193 this.selectedItem_ = null;
194 this.dispatchEvent(goog.events.EventType.SELECT);
195 }
196 }
197 };
198
199
200 /**
201 * Removes the item at the given index.
202 * @param {number} index Index of the item to remove.
203 */
204 goog.ui.SelectionModel.prototype.removeItemAt = function(index) {
205 this.removeItem(this.getItemAt(index));
206 };
207
208
209 /**
210 * @return {Object} The currently selected item, or null if none.
211 */
212 goog.ui.SelectionModel.prototype.getSelectedItem = function() {
213 return this.selectedItem_;
214 };
215
216
217 /**
218 * @return {!Array<Object>} All items in the selection model.
219 */
220 goog.ui.SelectionModel.prototype.getItems = function() {
221 return goog.array.clone(this.items_);
222 };
223
224
225 /**
226 * Selects the given item, deselecting any previously selected item, and
227 * dispatches a {@code SELECT} event.
228 * @param {Object} item Item to select (null to clear the selection).
229 */
230 goog.ui.SelectionModel.prototype.setSelectedItem = function(item) {
231 if (item != this.selectedItem_) {
232 this.selectItem_(this.selectedItem_, false);
233 this.selectedItem_ = item;
234 this.selectItem_(item, true);
235 }
236
237 // Always dispatch a SELECT event; let listeners decide what to do if the
238 // selected item hasn't changed.
239 this.dispatchEvent(goog.events.EventType.SELECT);
240 };
241
242
243 /**
244 * @return {number} The 0-based index of the currently selected item, or -1
245 * if none.
246 */
247 goog.ui.SelectionModel.prototype.getSelectedIndex = function() {
248 return this.indexOfItem(this.selectedItem_);
249 };
250
251
252 /**
253 * Selects the item at the given index, deselecting any previously selected
254 * item, and dispatches a {@code SELECT} event.
255 * @param {number} index Index to select (-1 to clear the selection).
256 */
257 goog.ui.SelectionModel.prototype.setSelectedIndex = function(index) {
258 this.setSelectedItem(this.getItemAt(index));
259 };
260
261
262 /**
263 * Clears the selection model by removing all items from the selection.
264 */
265 goog.ui.SelectionModel.prototype.clear = function() {
266 goog.array.clear(this.items_);
267 this.selectedItem_ = null;
268 };
269
270
271 /** @override */
272 goog.ui.SelectionModel.prototype.disposeInternal = function() {
273 goog.ui.SelectionModel.superClass_.disposeInternal.call(this);
274 delete this.items_;
275 this.selectedItem_ = null;
276 };
277
278
279 /**
280 * Private helper; selects or deselects the given item based on the value of
281 * the {@code select} argument. If a selection handler has been registered
282 * (via {@link #setSelectionHandler}, calls it to update the internal selection
283 * state of the item. Otherwise, attempts to call {@code setSelected(Boolean)}
284 * on the item itself, provided the object supports that interface.
285 * @param {Object} item Item to select or deselect.
286 * @param {boolean} select If true, the object will be selected; if false, it
287 * will be deselected.
288 * @private
289 */
290 goog.ui.SelectionModel.prototype.selectItem_ = function(item, select) {
291 if (item) {
292 if (typeof this.selectionHandler_ == 'function') {
293 // Use the registered selection handler function.
294 this.selectionHandler_(item, select);
295 } else if (typeof item.setSelected == 'function') {
296 // Call setSelected() on the item, if it supports it.
297 item.setSelected(select);
298 }
299 }
300 };