Debian Codegraph @

packages/datagrid/src/datamodel.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 { ISignal, Signal } from '@lumino/signaling';
11
12 import { CellGroup } from './cellgroup';
13 /**
14 * An object which provides the data for a data grid.
15 *
16 * #### Notes
17 * If the predefined data models are insufficient for a particular use
18 * case, a custom model can be defined which derives from this class.
19 */
20 export abstract class DataModel {
21 /**
22 * A signal emitted when the data model has changed.
23 */
24 get changed(): ISignal<this, DataModel.ChangedArgs> {
25 return this._changed;
26 }
27
28 /**
29 * Get the row count for a region in the data model.
30 *
31 * @param region - The row region of interest.
32 *
33 * @returns - The row count for the region.
34 *
35 * #### Notes
36 * This method is called often, and so should be efficient.
37 */
38 abstract rowCount(region: DataModel.RowRegion): number;
39
40 /**
41 * Get the column count for a region in the data model.
42 *
43 * @param region - The column region of interest.
44 *
45 * @returns - The column count for the region.
46 *
47 * #### Notes
48 * This method is called often, and so should be efficient.
49 */
50 abstract columnCount(region: DataModel.ColumnRegion): number;
51
52 /**
53 * Get the data value for a cell in the data model.
54 *
55 * @param region - The cell region of interest.
56 *
57 * @param row - The row index of the cell of interest.
58 *
59 * @param column - The column index of the cell of interest.
60 *
61 * @returns The data value for the specified cell.
62 *
63 * #### Notes
64 * The returned data should be treated as immutable.
65 *
66 * This method is called often, and so should be efficient.
67 */
68 abstract data(region: DataModel.CellRegion, row: number, column: number): any;
69
70 /**
71 * Get the count of merged cell groups pertaining to a given
72 * cell region.
73 * @param region the target cell region.
74 */
75 groupCount(region: DataModel.CellRegion): number {
76 return 0;
77 }
78
79 /**
80 * Get the metadata for a cell in the data model.
81 *
82 * @param region - The cell region of interest.
83 *
84 * @param row - The row index of the cell of interest.
85 *
86 * @param column - The column index of the cell of interest.
87 *
88 * @returns The metadata for the specified cell.
89 *
90 * #### Notes
91 * The returned metadata should be treated as immutable.
92 *
93 * This method is called often, and so should be efficient.
94 *
95 * The default implementation returns `{}`.
96 */
97 metadata(
98 region: DataModel.CellRegion,
99 row: number,
100 column: number
101 ): DataModel.Metadata {
102 return DataModel.emptyMetadata;
103 }
104
105 /**
106 * Get the merged cell group corresponding to a region and index number.
107 * @param region the cell region of cell group.
108 * @param groupIndex the group index of the cell group.
109 * @returns a cell group.
110 */
111 group(region: DataModel.CellRegion, groupIndex: number): CellGroup | null {
112 return null;
113 }
114
115 /**
116 * Emit the `changed` signal for the data model.
117 *
118 * #### Notes
119 * Subclasses should call this method whenever the data model has
120 * changed so that attached data grids can update themselves.
121 */
122 protected emitChanged(args: DataModel.ChangedArgs): void {
123 this._changed.emit(args);
124 }
125
126 private _changed = new Signal<this, DataModel.ChangedArgs>(this);
127 }
128
129 /**
130 * An object which provides the mutable data for a data grid.
131 *
132 * #### Notes
133 * This object is an extension to `DataModel` and it only adds ability to
134 * change data for cells.
135 */
136 export abstract class MutableDataModel extends DataModel {
137 /**
138 * Set the data value for a cell in the data model.
139 *
140 * @param region - The cell region of interest.
141 *
142 * @param row - The row index of the cell of interest.
143 *
144 * @param column - The column index of the cell of interest.
145 *
146 * @returns true if succeeds, false otherwise.
147 *
148 */
149 abstract setData(
150 region: DataModel.CellRegion,
151 row: number,
152 column: number,
153 value: unknown
154 ): boolean;
155 }
156
157 /**
158 * The namespace for the `DataModel` class statics.
159 */
160 export namespace DataModel {
161 /**
162 * A type alias for the data model row regions.
163 */
164 export type RowRegion = 'body' | 'column-header';
165
166 /**
167 * A type alias for the data model column regions.
168 */
169 export type ColumnRegion = 'body' | 'row-header';
170
171 /**
172 * A type alias for the data model cell regions.
173 */
174 export type CellRegion =
175 | 'body'
176 | 'row-header'
177 | 'column-header'
178 | 'corner-header';
179
180 /**
181 * The metadata for a column in a data model.
182 */
183 export type Metadata = { [key: string]: any };
184
185 /**
186 * A singleton empty metadata object.
187 */
188 export const emptyMetadata: Metadata = Object.freeze({});
189
190 /**
191 * An arguments object for the `changed` signal.
192 *
193 * #### Notes
194 * Data models should emit the `changed` signal with this args object
195 * type when rows are inserted or removed.
196 */
197 export type RowsChangedArgs = {
198 /**
199 * The discriminated type of the args object.
200 */
201 readonly type: 'rows-inserted' | 'rows-removed';
202
203 /**
204 * The region which contains the modified rows.
205 */
206 readonly region: RowRegion;
207
208 /**
209 * The index of the first modified row.
210 */
211 readonly index: number;
212
213 /**
214 * The number of modified rows.
215 */
216 readonly span: number;
217 };
218
219 /**
220 * An arguments object for the `changed` signal.
221 *
222 * #### Notes
223 * Data models should emit the `changed` signal with this args object
224 * type when columns are inserted or removed.
225 */
226 export type ColumnsChangedArgs = {
227 /**
228 * The discriminated type of the args object.
229 */
230 readonly type: 'columns-inserted' | 'columns-removed';
231
232 /**
233 * The region which contains the modified columns.
234 */
235 readonly region: ColumnRegion;
236
237 /**
238 * The index of the first modified column.
239 */
240 readonly index: number;
241
242 /**
243 * The number of modified columns.
244 */
245 readonly span: number;
246 };
247
248 /**
249 * An arguments object for the `changed` signal.
250 *
251 * #### Notes
252 * Data models should emit the `changed` signal with this args object
253 * type when rows are moved.
254 */
255 export type RowsMovedArgs = {
256 /**
257 * The discriminated type of the args object.
258 */
259 readonly type: 'rows-moved';
260
261 /**
262 * The region which contains the modified rows.
263 */
264 readonly region: RowRegion;
265
266 /**
267 * The starting index of the first modified row.
268 */
269 readonly index: number;
270
271 /**
272 * The number of modified rows.
273 */
274 readonly span: number;
275
276 /**
277 * The ending index of the first modified row.
278 */
279 readonly destination: number;
280 };
281
282 /**
283 * An arguments object for the `changed` signal.
284 *
285 * #### Notes
286 * Data models should emit the `changed` signal with this args object
287 * type when columns are moved.
288 */
289 export type ColumnsMovedArgs = {
290 /**
291 * The discriminated type of the args object.
292 */
293 readonly type: 'columns-moved';
294
295 /**
296 * The region which contains the modified columns.
297 */
298 readonly region: ColumnRegion;
299
300 /**
301 * The starting index of the first modified column.
302 */
303 readonly index: number;
304
305 /**
306 * The number of modified columns.
307 */
308 readonly span: number;
309
310 /**
311 * The ending index of the first modified column.
312 */
313 readonly destination: number;
314 };
315
316 /**
317 * An arguments object for the `changed` signal.
318 *
319 * #### Notes
320 * Data models should emit the `changed` signal with this args object
321 * type when cells are changed in-place.
322 */
323 export type CellsChangedArgs = {
324 /**
325 * The discriminated type of the args object.
326 */
327 readonly type: 'cells-changed';
328
329 /**
330 * The region which contains the modified cells.
331 */
332 readonly region: CellRegion;
333
334 /**
335 * The row index of the first modified cell.
336 */
337 readonly row: number;
338
339 /**
340 * The column index of the first modified cell.
341 */
342 readonly column: number;
343
344 /**
345 * The number of rows in the modified cell range.
346 */
347 readonly rowSpan: number;
348
349 /**
350 * The number of columns in the modified cell range.
351 */
352 readonly columnSpan: number;
353 };
354
355 /**
356 * An arguments object for the `changed` signal.
357 *
358 * #### Notes
359 * Data models should emit the `changed` signal with this args object
360 * type when the model has changed in a fashion that cannot be easily
361 * expressed by the other args object types.
362 *
363 * This is the "big hammer" approach, and will cause any associated
364 * data grid to perform a full reset. The other changed args types
365 * should be used whenever possible.
366 */
367 export type ModelResetArgs = {
368 /**
369 * The discriminated type of the args object.
370 */
371 readonly type: 'model-reset';
372 };
373
374 /**
375 * A type alias for the args objects of the `changed` signal.
376 */
377 export type ChangedArgs =
378 | RowsChangedArgs
379 | ColumnsChangedArgs
380 | RowsMovedArgs
381 | ColumnsMovedArgs
382 | CellsChangedArgs
383 | ModelResetArgs;
384 }