Debian Codegraph @

jupyter-widgets-controls/lib/lumino/currentselection.js

raw
1 // Copyright (c) Jupyter Development Team.
2 // Distributed under the terms of the Modified BSD License.
3 /**
4 * A variety of convenience methods for maintaining a current selection
5 */
6 import { ArrayExt } from '@lumino/algorithm';
7 import { Signal } from '@lumino/signaling';
8 export class Selection {
9 constructor(sequence, options = {}) {
10 this._array = null;
11 this._value = null;
12 this._previousValue = null;
13 this._selectionChanged = new Signal(this);
14 this._array = sequence;
15 this._insertBehavior = options.insertBehavior || 'select-item-if-needed';
16 this._removeBehavior = options.removeBehavior || 'select-item-after';
17 }
18 /**
19 * A signal emitted when the current item is changed.
20 *
21 * #### Notes
22 * This signal is emitted when the currently selected item is changed either
23 * through user or programmatic interaction.
24 *
25 * Notably, this signal is not emitted when the index of the current item
26 * changes due to other items being inserted, removed, or moved, but the
27 * current item remains the same. It is only emitted when the actual current
28 * item is changed.
29 */
30 get selectionChanged() {
31 return this._selectionChanged;
32 }
33 /**
34 * Adjust for setting an item.
35 *
36 * This should be called *after* the set.
37 *
38 * @param index - The index set.
39 * @param oldValue - The old value at the index.
40 */
41 adjustSelectionForSet(index) {
42 // We just need to send a signal if the currentValue changed.
43 // Get the current index and value.
44 const pi = this.index;
45 const pv = this.value;
46 // Exit early if this doesn't affect the selection
47 if (index !== pi) {
48 return;
49 }
50 this._updateSelectedValue();
51 const cv = this.value;
52 // The previous item is now null, since it is no longer in the array.
53 this._previousValue = null;
54 // Send signal if there was a change
55 if (pv !== cv) {
56 // Emit the current changed signal.
57 this._selectionChanged.emit({
58 previousIndex: pi,
59 previousValue: pv,
60 currentIndex: pi,
61 currentValue: cv,
62 });
63 }
64 }
65 /**
66 * Get the currently selected item.
67 *
68 * #### Notes
69 * This will be `null` if no item is selected.
70 */
71 get value() {
72 return this._value;
73 }
74 /**
75 * Set the currently selected item.
76 *
77 * #### Notes
78 * If the item does not exist in the vector, the currentValue will be set to
79 * `null`. This selects the first entry equal to the desired item.
80 */
81 set value(value) {
82 if (value === null || this._array === null) {
83 this.index = null;
84 }
85 else {
86 this.index = ArrayExt.firstIndexOf(this._array, value);
87 }
88 }
89 /**
90 * Get the index of the currently selected item.
91 *
92 * #### Notes
93 * This will be `null` if no item is selected.
94 */
95 get index() {
96 return this._index;
97 }
98 /**
99 * Set the index of the currently selected tab.
100 *
101 * @param index - The index to select.
102 *
103 * #### Notes
104 * If the value is out of range, the index will be set to `null`, which
105 * indicates no item is selected.
106 */
107 set index(index) {
108 // Coerce the value to an index.
109 let i;
110 if (index !== null && this._array !== null) {
111 i = Math.floor(index);
112 if (i < 0 || i >= this._array.length) {
113 i = null;
114 }
115 }
116 else {
117 i = null;
118 }
119 // Bail early if the index will not change.
120 if (this._index === i) {
121 return;
122 }
123 // Look up the previous index and item.
124 const pi = this._index;
125 const pv = this._value;
126 // Update the state
127 this._index = i;
128 this._updateSelectedValue();
129 this._previousValue = pv;
130 // Emit the current changed signal.
131 this._selectionChanged.emit({
132 previousIndex: pi,
133 previousValue: pv,
134 currentIndex: i,
135 currentValue: this._value,
136 });
137 }
138 /**
139 * Get the selection behavior when inserting a tab.
140 */
141 get insertBehavior() {
142 return this._insertBehavior;
143 }
144 /**
145 * Set the selection behavior when inserting a tab.
146 */
147 set insertBehavior(value) {
148 this._insertBehavior = value;
149 }
150 /**
151 * Get the selection behavior when removing a tab.
152 */
153 get removeBehavior() {
154 return this._removeBehavior;
155 }
156 /**
157 * Set the selection behavior when removing a tab.
158 */
159 set removeBehavior(value) {
160 this._removeBehavior = value;
161 }
162 /**
163 * Adjust the current index for a tab insert operation.
164 *
165 * @param i - The new index of the inserted item.
166 * @param j - The inserted item.
167 *
168 * #### Notes
169 * This method accounts for the tab bar's insertion behavior when adjusting
170 * the current index and emitting the changed signal. This should be called
171 * after the insertion.
172 */
173 adjustSelectionForInsert(i, item) {
174 // Lookup commonly used variables.
175 const cv = this._value;
176 const ci = this._index;
177 const bh = this._insertBehavior;
178 // Handle the behavior where the new item is always selected,
179 // or the behavior where the new item is selected if needed.
180 if (bh === 'select-item' ||
181 (bh === 'select-item-if-needed' && ci === null)) {
182 this._index = i;
183 this._value = item;
184 this._previousValue = cv;
185 this._selectionChanged.emit({
186 previousIndex: ci,
187 previousValue: cv,
188 currentIndex: i,
189 currentValue: item,
190 });
191 return;
192 }
193 // Otherwise, silently adjust the current index if needed.
194 if (ci !== null && ci >= i) {
195 this._index++;
196 }
197 }
198 /**
199 * Clear the selection and history.
200 */
201 clearSelection() {
202 // Get the current index and item.
203 const pi = this._index;
204 const pv = this._value;
205 // Reset the current index and previous item.
206 this._index = null;
207 this._value = null;
208 this._previousValue = null;
209 // If no item was selected, there's nothing else to do.
210 if (pi === null) {
211 return;
212 }
213 // Emit the current changed signal.
214 this._selectionChanged.emit({
215 previousIndex: pi,
216 previousValue: pv,
217 currentIndex: this._index,
218 currentValue: this._value,
219 });
220 }
221 /**
222 * Adjust the current index for an item remove operation.
223 *
224 * @param i - The former index of the removed item.
225 * @param item - The removed item.
226 *
227 * #### Notes
228 * This method accounts for the remove behavior when adjusting the current
229 * index and emitting the changed signal. It should be called after the item
230 * is removed.
231 */
232 adjustSelectionForRemove(i, item) {
233 // If we have no selection, there is nothing to do
234 if (this._index === null) {
235 return;
236 }
237 // Lookup commonly used variables.
238 const ci = this._index;
239 const bh = this._removeBehavior;
240 // Silently adjust the index if the current item is not removed.
241 if (ci !== i) {
242 if (ci > i) {
243 this._index--;
244 }
245 return;
246 }
247 // No item gets selected if the vector is empty.
248 if (!this._array || this._array.length === 0) {
249 // Reset the current index and previous item.
250 this._index = null;
251 this._value = null;
252 this._previousValue = null;
253 this._selectionChanged.emit({
254 previousIndex: i,
255 previousValue: item,
256 currentIndex: this._index,
257 currentValue: this._value,
258 });
259 return;
260 }
261 // Handle behavior where the next sibling item is selected.
262 if (bh === 'select-item-after') {
263 this._index = Math.min(i, this._array.length - 1);
264 this._updateSelectedValue();
265 this._previousValue = null;
266 this._selectionChanged.emit({
267 previousIndex: i,
268 previousValue: item,
269 currentIndex: this._index,
270 currentValue: this._value,
271 });
272 return;
273 }
274 // Handle behavior where the previous sibling item is selected.
275 if (bh === 'select-item-before') {
276 this._index = Math.max(0, i - 1);
277 this._updateSelectedValue();
278 this._previousValue = null;
279 this._selectionChanged.emit({
280 previousIndex: i,
281 previousValue: item,
282 currentIndex: this._index,
283 currentValue: this._value,
284 });
285 return;
286 }
287 // Handle behavior where the previous history item is selected.
288 if (bh === 'select-previous-item') {
289 if (this._previousValue) {
290 this.value = this._previousValue;
291 }
292 else {
293 this._index = Math.min(i, this._array.length - 1);
294 this._updateSelectedValue();
295 }
296 this._previousValue = null;
297 this._selectionChanged.emit({
298 previousIndex: i,
299 previousValue: item,
300 currentIndex: this._index,
301 currentValue: this.value,
302 });
303 return;
304 }
305 // Otherwise, no item gets selected.
306 this._index = null;
307 this._value = null;
308 this._previousValue = null;
309 this._selectionChanged.emit({
310 previousIndex: i,
311 previousValue: item,
312 currentIndex: this._index,
313 currentValue: this._value,
314 });
315 }
316 /**
317 * Set the current value based on the current index.
318 */
319 _updateSelectedValue() {
320 const i = this._index;
321 this._value = i !== null && this._array ? this._array[i] : null;
322 }
323 }
324 //# sourceMappingURL=currentselection.js.map