Debian Codegraph @

packages/datagrid/src/selectionmodel.ts

raw
1 // Copyright (c) Jupyter Development Team.
2 // Distributed under the terms of the Modified BSD License.
3 /*-----------------------------------------------------------------------------
4 | Copyright (c) 2014-2019, PhosphorJS Contributors
5 |
6 | Distributed under the terms of the BSD 3-Clause License.
7 |
8 | The full license is in the file LICENSE, distributed with this software.
9 |----------------------------------------------------------------------------*/
10 import { some } from '@lumino/algorithm';
11
12 import { ISignal, Signal } from '@lumino/signaling';
13
14 import { DataModel } from './datamodel';
15
16 /**
17 * A base class for creating data grid selection models.
18 *
19 * #### Notes
20 * If the predefined selection models are insufficient for a particular
21 * use case, a custom model can be defined which derives from this class.
22 */
23 export abstract class SelectionModel {
24 /**
25 * Construct a new selection model.
26 *
27 * @param options - The options for initializing the model.
28 */
29 constructor(options: SelectionModel.IOptions) {
30 this.dataModel = options.dataModel;
31 this._selectionMode = options.selectionMode || 'cell';
32 this.dataModel.changed.connect(this.onDataModelChanged, this);
33 }
34
35 /**
36 * Whether the selection model is empty.
37 *
38 * #### Notes
39 * An empty selection model will yield an empty `selections` iterator.
40 */
41 abstract readonly isEmpty: boolean;
42
43 /**
44 * The row index of the cursor.
45 *
46 * This is `-1` if the selection model is empty.
47 */
48 abstract readonly cursorRow: number;
49
50 /**
51 * The column index of the cursor.
52 *
53 * This is `-1` if the selection model is empty.
54 */
55 abstract readonly cursorColumn: number;
56
57 /**
58 * Move cursor down/up/left/right while making sure it remains
59 * within the bounds of selected rectangles
60 *
61 * @param direction - The direction of the movement.
62 */
63 abstract moveCursorWithinSelections(
64 direction: SelectionModel.CursorMoveDirection
65 ): void;
66
67 /**
68 * Get the current selection in the selection model.
69 *
70 * @returns The current selection or `null`.
71 *
72 * #### Notes
73 * This is the selection which holds the cursor.
74 */
75 abstract currentSelection(): SelectionModel.Selection | null;
76
77 /**
78 * Get an iterator of the selections in the model.
79 *
80 * @returns A new iterator of the selections in the model.
81 *
82 * #### Notes
83 * The data grid will render the selections in order.
84 */
85 abstract selections(): IterableIterator<SelectionModel.Selection>;
86
87 /**
88 * Select the specified cells.
89 *
90 * @param args - The arguments for the selection.
91 */
92 abstract select(args: SelectionModel.SelectArgs): void;
93
94 /**
95 * Clear all selections in the selection model.
96 */
97 abstract clear(): void;
98
99 /**
100 * A signal emitted when the selection model has changed.
101 */
102 get changed(): ISignal<this, void> {
103 return this._changed;
104 }
105
106 /**
107 * The data model associated with the selection model.
108 */
109 readonly dataModel: DataModel;
110
111 /**
112 * Get the selection mode for the model.
113 */
114 get selectionMode(): SelectionModel.SelectionMode {
115 return this._selectionMode;
116 }
117
118 /**
119 * Set the selection mode for the model.
120 *
121 * #### Notes
122 * This will clear the selection model.
123 */
124 set selectionMode(value: SelectionModel.SelectionMode) {
125 // Bail early if the mode does not change.
126 if (this._selectionMode === value) {
127 return;
128 }
129
130 // Update the internal mode.
131 this._selectionMode = value;
132
133 // Clear the current selections.
134 this.clear();
135 }
136
137 /**
138 * Test whether any selection intersects a row.
139 *
140 * @param index - The row index of interest.
141 *
142 * @returns Whether any selection intersects the row.
143 *
144 * #### Notes
145 * This method may be reimplemented in a subclass.
146 */
147 isRowSelected(index: number): boolean {
148 return some(this.selections(), s => Private.containsRow(s, index));
149 }
150
151 /**
152 * Test whether any selection intersects a column.
153 *
154 * @param index - The column index of interest.
155 *
156 * @returns Whether any selection intersects the column.
157 *
158 * #### Notes
159 * This method may be reimplemented in a subclass.
160 */
161 isColumnSelected(index: number): boolean {
162 return some(this.selections(), s => Private.containsColumn(s, index));
163 }
164
165 /**
166 * Test whether any selection intersects a cell.
167 *
168 * @param row - The row index of interest.
169 *
170 * @param column - The column index of interest.
171 *
172 * @returns Whether any selection intersects the cell.
173 *
174 * #### Notes
175 * This method may be reimplemented in a subclass.
176 */
177 isCellSelected(row: number, column: number): boolean {
178 return some(this.selections(), s => Private.containsCell(s, row, column));
179 }
180
181 /**
182 * A signal handler for the data model `changed` signal.
183 *
184 * @param args - The arguments for the signal.
185 *
186 * #### Notes
187 * Selection model implementations should update their selections
188 * in a manner that is relevant for the changes to the data model.
189 *
190 * The default implementation of this method is a no-op.
191 */
192 protected onDataModelChanged(
193 sender: DataModel,
194 args: DataModel.ChangedArgs
195 ): void {
196 // pass
197 }
198
199 /**
200 * Emit the `changed` signal for the selection model.
201 *
202 * #### Notes
203 * Subclasses should call this method whenever the selection model
204 * has changed so that attached data grids can update themselves.
205 */
206 protected emitChanged(): void {
207 this._changed.emit(undefined);
208 }
209
210 private _changed = new Signal<this, void>(this);
211 private _selectionMode: SelectionModel.SelectionMode = 'cell';
212 }
213
214 /**
215 * The namespace for the `SelectionModel` class statics.
216 */
217 export namespace SelectionModel {
218 /**
219 * A type alias for the selection mode.
220 */
221 export type SelectionMode = 'row' | 'column' | 'cell';
222
223 /**
224 * A type alias for the cursor move direction.
225 */
226 export type CursorMoveDirection = 'up' | 'down' | 'left' | 'right' | 'none';
227
228 /**
229 * A type alias for the clear mode.
230 */
231 export type ClearMode = 'all' | 'current' | 'none';
232
233 /**
234 * A type alias for the select args.
235 */
236 export type SelectArgs = {
237 /**
238 * The first row of the selection.
239 *
240 * This may be greater than `r2`.
241 */
242 r1: number;
243
244 /**
245 * The first column of the selection.
246 *
247 * This may be greater than `c2`.
248 */
249 c1: number;
250
251 /**
252 * The last row of the selection.
253 *
254 * This may be less than `r1`.
255 */
256 r2: number;
257
258 /**
259 * The last column of the selection.
260 *
261 * This may be less than `c1`.
262 */
263 c2: number;
264
265 /**
266 * The row index for the cursor.
267 *
268 * This should be contained within the selection.
269 */
270 cursorRow: number;
271
272 /**
273 * The column index for the cursor.
274 *
275 * This should be contained within the selection.
276 */
277 cursorColumn: number;
278
279 /**
280 * Which of the existing selections to clear.
281 */
282 clear: ClearMode;
283 };
284
285 /**
286 * A type alias for a selection in a selection model.
287 */
288 export type Selection = {
289 /**
290 * The first row of the selection.
291 *
292 * This may be greater than `r2`.
293 */
294 readonly r1: number;
295
296 /**
297 * The first column of the selection.
298 *
299 * This may be greater than `c2`.
300 */
301 readonly c1: number;
302
303 /**
304 * The last row of the selection.
305 *
306 * This may be less than `r1`.
307 */
308 readonly r2: number;
309
310 /**
311 * The last column of the selection.
312 *
313 * This may be less than `c1`.
314 */
315 readonly c2: number;
316 };
317
318 /**
319 * An options object for initializing a selection model.
320 */
321 export interface IOptions {
322 /**
323 * The data model for the selection model.
324 */
325 dataModel: DataModel;
326
327 /**
328 * The selection mode for the model.
329 *
330 * The default is `'cell'`.
331 */
332 selectionMode?: SelectionMode;
333 }
334 }
335
336 /**
337 * The namespace for the module implementation details.
338 */
339 namespace Private {
340 /**
341 * Test whether a selection contains a given row.
342 */
343 export function containsRow(
344 selection: SelectionModel.Selection,
345 row: number
346 ): boolean {
347 let { r1, r2 } = selection;
348 return (row >= r1 && row <= r2) || (row >= r2 && row <= r1);
349 }
350
351 /**
352 * Test whether a selection contains a given column.
353 */
354 export function containsColumn(
355 selection: SelectionModel.Selection,
356 column: number
357 ): boolean {
358 let { c1, c2 } = selection;
359 return (column >= c1 && column <= c2) || (column >= c2 && column <= c1);
360 }
361
362 /**
363 * Test whether a selection contains a given cell.
364 */
365 export function containsCell(
366 selection: SelectionModel.Selection,
367 row: number,
368 column: number
369 ): boolean {
370 return containsRow(selection, row) && containsColumn(selection, column);
371 }
372 }