Debian Codegraph @

packages/datagrid/src/cellrenderer.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 { DataModel } from './datamodel';
11
12 import { GraphicsContext } from './graphicscontext';
13
14 /**
15 * An object which renders the cells of a data grid.
16 *
17 * #### Notes
18 * If the predefined cell renderers are insufficient for a particular
19 * use case, a custom cell renderer can be defined which derives from
20 * this class.
21 *
22 * The data grid renders cells in column-major order, by region. The
23 * region order is: body, row header, column header, corner header.
24 */
25 export abstract class CellRenderer {
26 /**
27 * Paint the content for a cell.
28 *
29 * @param gc - The graphics context to use for drawing.
30 *
31 * @param config - The configuration data for the cell.
32 *
33 * #### Notes
34 * The grid will save/restore the `gc` state before/after invoking
35 * the renderer.
36 *
37 * For performance, the cell content is efficiently clipped to the
38 * width of the column, but *the height is not clipped*. If height
39 * clipping is needed, the renderer must set up its own clip rect.
40 *
41 * The renderer **must not** draw outside the cell bounding height.
42 */
43 abstract paint(gc: GraphicsContext, config: CellRenderer.CellConfig): void;
44 }
45
46 /**
47 * The namespace for the `CellRenderer` class statics.
48 */
49 export namespace CellRenderer {
50 /**
51 * An object which holds the configuration data for a cell.
52 */
53 export type CellConfig = {
54 /**
55 * The X position of the cell rectangle, in viewport coordinates.
56 */
57 readonly x: number;
58
59 /**
60 * The Y position of the cell rectangle, in viewport coordinates.
61 */
62 readonly y: number;
63
64 /**
65 * The height of the cell rectangle, in viewport pixels.
66 */
67 readonly height: number;
68
69 /**
70 * The width of the cell rectangle, in viewport pixels.
71 */
72 readonly width: number;
73
74 /**
75 * The region for the cell.
76 */
77 readonly region: DataModel.CellRegion;
78
79 /**
80 * The row index of the cell.
81 */
82 readonly row: number;
83
84 /**
85 * The column index of the cell.
86 */
87 readonly column: number;
88
89 /**
90 * The value for the cell.
91 */
92 readonly value: any;
93
94 /**
95 * The metadata for the cell.
96 */
97 readonly metadata: DataModel.Metadata;
98 };
99
100 /**
101 * A type alias for a cell renderer config function.
102 *
103 * This type is used to compute a value from a cell config object.
104 */
105 export type ConfigFunc<T> = (config: CellConfig) => T;
106
107 /**
108 * A type alias for a cell renderer config option.
109 *
110 * A config option can be a static value or a config function.
111 */
112 export type ConfigOption<T> = T | ConfigFunc<T>;
113
114 /**
115 * Resolve a config option for a cell renderer.
116 *
117 * @param option - The config option to resolve.
118 *
119 * @param config - The cell config object.
120 *
121 * @returns The resolved value for the option.
122 */
123 export function resolveOption<T>(
124 option: ConfigOption<T>,
125 config: CellConfig
126 ): T {
127 return typeof option === 'function'
128 ? (option as ConfigFunc<T>)(config)
129 : option;
130 }
131 }