A widget which implements a high-performance tabular data grid.

Notes

A data grid is implemented as a composition of child widgets. These child widgets are considered an implementation detail. Manipulating the child widgets of a data grid directly is undefined behavior.

This class is not designed to be subclassed.

Hierarchy (view full)

Constructors

Properties

Accessors

Methods

_blitContent _drawBackground _drawBodyRegion _drawBodySelections _drawCells _drawColumnBackground _drawColumnHeaderRegion _drawColumnHeaderSelections _drawCursor _drawHorizontalGridLines _drawRowBackground _drawRowHeaderRegion _drawRowHeaderSelections _drawShadows _drawVerticalGridLines _drawVoidRegion _evtContextMenu _evtKeyDown _evtMouseDoubleClick _evtMouseDown _evtMouseLeave _evtMouseMove _evtMouseUp _evtWheel _fitBodyColumnHeaders _fitRowColumnHeaders _getCellTextWidth _getColumnSize _getMaxWidthInArea _getMaxWidthInColumn _getRowSize _getTextToRender _onCellsChanged _onColumnsInserted _onColumnsMoved _onColumnsRemoved _onDataModelChanged _onModelReset _onPageRequested _onRenderersChanged _onRowsInserted _onRowsMoved _onRowsRemoved _onSelectionsChanged _onStepRequested _onThumbMoved _onViewportColumnResizeRequest _onViewportOverlayPaintRequest _onViewportPaintRequest _onViewportResize _onViewportRowResizeRequest _onViewportScrollRequest _paintMergedCells _paintOverlay _processViewportMessage _refreshDPI _releaseMouse _resizeCanvasIfNeeded _resizeColumn _resizeColumnHeader _resizeRow _resizeRowHeader _scrollTo _syncScrollState _syncViewport activate addClass cellGroupInteresectsRegion children clearFlag close columnAt columnCount columnOffset columnSize contains copyToClipboard dispose drawCornerHeaderRegion fit fitColumnNames handleEvent hasClass hide hitTest mapToLocal mapToVirtual messageHook moveCursor notifyLayout onActivateRequest onAfterAttach onAfterDetach onAfterHide onAfterShow onBeforeAttach onBeforeDetach onBeforeHide onBeforeShow onChildAdded onChildRemoved onCloseRequest onFitRequest onResize onUpdateRequest paintContent processMessage removeClass repaintContent repaintOverlay repaintRegion resetColumns resetRows resizeColumn resizeRow rowAt rowCount rowOffset rowSize scrollBy scrollByPage scrollByStep scrollTo scrollToCell scrollToColumn scrollToCursor scrollToRow setFlag setHidden show testFlag toggleClass update _getCellMetadata _getCellValue _getConfig

Constructors

Properties

_cellRenderers: RendererMap
_columnHeaderSections: SectionList
_columnSections: SectionList
_copyConfig: CopyConfig
_dataModel: null | DataModel = null
_dpiRatio: number = ...
_editingEnabled: boolean = false
_editorController: null | ICellEditorController
_hScrollBar: ScrollBar
_hScrollBarMinHeight: number = 0
_headerVisibility: HeaderVisibility
_keyHandler: null | IKeyHandler = null
_mouseHandler: null | IMouseHandler = null
_mousedown: boolean = false
_rowHeaderSections: SectionList
_rowSections: SectionList
_scrollCorner: Widget
_scrollX: number = 0
_scrollY: number = 0
_selectionModel: null | SelectionModel = null
_stretchLastColumn: boolean
_stretchLastRow: boolean
_style: Style
_vScrollBar: ScrollBar
_vScrollBarMinWidth: number = 0
_viewport: Widget
_viewportHeight: number = 0
_viewportWidth: number = 0

Get the DOM node owned by the widget.

Accessors

  • get bodyHeight(): number
  • The virtual height of the grid body.

    Notes

    This does not account for a stretched last row.

    Returns number

  • get bodyWidth(): number
  • The virtual width of the grid body.

    Notes

    This does not account for a stretched last column.

    Returns number

  • get dataset(): DOMStringMap
  • The dataset for the widget's DOM node.

    Returns DOMStringMap

  • get disposed(): ISignal<this, void>
  • A signal emitted when the widget is disposed.

    Returns ISignal<this, void>

  • get editable(): boolean
  • Whether the grid cells are editable.

    editingEnabled flag must be on and grid must have required selection model, editor controller and data model properties.

    Returns boolean

  • get hiddenMode(): HiddenMode
  • Get the method for hiding the widget.

    Returns HiddenMode

  • set hiddenMode(value): void
  • Set the method for hiding the widget.

    Parameters

    Returns void

  • get id(): string
  • Get the id of the widget's DOM node.

    Returns string

  • set id(value): void
  • Set the id of the widget's DOM node.

    Parameters

    • value: string

    Returns void

  • get isAttached(): boolean
  • Test whether the widget's node is attached to the DOM.

    Returns boolean

  • get isDisposed(): boolean
  • Test whether the widget has been disposed.

    Returns boolean

  • get isHidden(): boolean
  • Test whether the widget is explicitly hidden.

    Returns boolean

  • get isVisible(): boolean
  • Test whether the widget is visible.

    Notes

    A widget is visible when it is attached to the DOM, is not explicitly hidden, and has no explicitly hidden ancestors.

    Returns boolean

  • get layout(): null | Layout
  • Get the layout for the widget.

    Returns null | Layout

  • set layout(value): void
  • Set the layout for the widget.

    Notes

    The layout is single-use only. It cannot be changed after the first assignment.

    The layout is disposed automatically when the widget is disposed.

    Parameters

    Returns void

  • get parent(): null | Widget
  • Get the parent of the widget.

    Returns null | Widget

  • set parent(value): void
  • Set the parent of the widget.

    Notes

    Children are typically added to a widget by using a layout, which means user code will not normally set the parent widget directly.

    The widget will be automatically removed from its old parent.

    This is a no-op if there is no effective parent change.

    Parameters

    Returns void

  • get title(): Title<Widget>
  • The title object for the widget.

    Notes

    The title object is used by some container widgets when displaying the widget alongside some title, such as a tab panel or side bar.

    Since not all widgets will use the title, it is created on demand.

    The owner property of the title is set to this widget.

    Returns Title<Widget>

  • get totalHeight(): number
  • The virtual height of the entire grid.

    Notes

    This does not account for a stretched last row.

    Returns number

  • get totalWidth(): number
  • The virtual width of the entire grid.

    Notes

    This does not account for a stretched last column.

    Returns number

Methods

  • Blit content into the on-screen grid canvas.

    The rect should be expressed in viewport coordinates.

    This automatically accounts for the dpi ratio.

    Parameters

    Returns void

  • Draw the background for the given paint region.

    Parameters

    • rgn: PaintRegion
    • color: undefined | string

    Returns void

  • Draw the body region which intersects the dirty rect.

    Parameters

    • rx: number
    • ry: number
    • rw: number
    • rh: number

    Returns void

  • Draw the column background for the given paint region.

    Parameters

    • rgn: PaintRegion
    • colorFn: undefined | ((i) => string)

    Returns void

  • Draw the column header region which intersects the dirty rect.

    Parameters

    • rx: number
    • ry: number
    • rw: number
    • rh: number

    Returns void

  • Draw the horizontal grid lines for the given paint region.

    Parameters

    • rgn: PaintRegion
    • color: undefined | string

    Returns void

  • Draw the row background for the given paint region.

    Parameters

    • rgn: PaintRegion
    • colorFn: undefined | ((i) => string)

    Returns void

  • Draw the row header region which intersects the dirty rect.

    Parameters

    • rx: number
    • ry: number
    • rw: number
    • rh: number

    Returns void

  • Draw the vertical grid lines for the given paint region.

    Parameters

    • rgn: PaintRegion
    • color: undefined | string

    Returns void

  • Draw the void region for the dirty rect.

    Parameters

    • rx: number
    • ry: number
    • rw: number
    • rh: number

    Returns void

  • Resizes body column headers so their text fits without clipping or wrapping.

    Parameters

    • dataModel: DataModel
    • padding: number
    • Optional numCols: number

    Returns void

  • Resizes row header columns so their text fits without clipping or wrapping.

    Parameters

    • dataModel: DataModel
    • padding: number
    • Optional numCols: number

    Returns void

  • Parameters

    • index: number
    • columnRegion: "body" | "row-header"

    Returns null | number

  • Handle the pageRequested signal from a scroll bar.

    Parameters

    • sender: ScrollBar
    • dir: "decrement" | "increment"

    Returns void

  • Handle the stepRequested signal from a scroll bar.

    Parameters

    • sender: ScrollBar
    • dir: "decrement" | "increment"

    Returns void

  • A message hook invoked on a viewport 'column-resize-request' message.

    Parameters

    • msg: ColumnResizeRequest

    Returns void

  • A message hook invoked on a viewport 'overlay-paint-request' message.

    Parameters

    Returns void

  • A message hook invoked on a viewport 'paint-request' message.

    Parameters

    • msg: PaintRequest

    Returns void

  • A message hook invoked on a viewport 'row-resize-request' message.

    Parameters

    • msg: RowResizeRequest

    Returns void

  • Paint group cells.

    Parameters

    • cellGroups: CellGroup[]
    • rgn: PixelRegion
    • backgroundColor: undefined | string

    Returns void

  • Paint the overlay content for the entire grid.

    This is the primary overlay paint entry point. The individual _draw* methods should not be invoked directly. This method dispatches to the drawing methods in the correct order.

    Returns void

  • Ensure the canvas is at least the specified size.

    This method will retain the valid canvas content.

    Parameters

    • width: number
    • height: number

    Returns void

  • Resize a column section immediately.

    Parameters

    • index: number
    • size: null | number

    Returns void

  • Resize a column header section immediately.

    Parameters

    • index: number
    • size: number

    Returns void

  • Resize a row section immediately.

    Parameters

    • index: number
    • size: number

    Returns void

  • Resize a row header section immediately.

    Parameters

    • index: number
    • size: null | number

    Returns void

  • Scroll immediately to the specified offset position.

    Parameters

    • x: number
    • y: number

    Returns void

  • Sync the scroll bars and scroll state with the viewport.

    Notes

    If the visibility of either scroll bar changes, a synchronous fit-request will be dispatched to the data grid to immediately resize the viewport.

    Returns void

  • Sync the viewport to the given scroll position.

    Notes

    This schedules a full repaint and syncs the scroll state.

    Returns void

  • Post an 'activate-request' message to the widget.

    Notes

    This is a simple convenience method for posting the message.

    Returns void

  • Add a class name to the widget's DOM node.

    Parameters

    • name: string

      The class name to add to the node.

      Notes

      If the class name is already added to the node, this is a no-op.

      The class name must not contain whitespace.

    Returns void

  • Create an iterator over the widget's children.

    Returns IterableIterator<Widget>

    A new iterator over the children of the widget.

    Notes

    The widget must have a populated layout in order to have children.

    If a layout is not installed, the returned iterator will be empty.

  • Clear the given widget flag.

    Notes

    This will not typically be called directly by user code.

    Parameters

    Returns void

  • Send a 'close-request' message to the widget.

    Notes

    This is a simple convenience method for sending the message.

    Returns void

  • Get the column at a virtual offset in the data grid.

    Parameters

    • region: ColumnRegion

      The region which holds the column of interest.

    • offset: number

      The virtual offset of the column of interest.

    Returns number

    The index of the column, or -1 if the offset is out of range.

    Notes

    This method accounts for a stretched last column.

  • Get the column count for a particular region in the data grid.

    Parameters

    Returns number

    The column count for the specified region.

  • Get the offset of a column in the data grid.

    Parameters

    • region: ColumnRegion

      The region which holds the column of interest.

    • index: number

      The index of the column of interest.

    Returns number

    The offset of the column, or -1 if the index is out of range.

    Notes

    A stretched last column has no effect on the return value.

  • Get the size of a column in the data grid.

    Parameters

    • region: ColumnRegion

      The region which holds the column of interest.

    • index: number

      The index of the column of interest.

    Returns number

    The size of the column, or -1 if the index is out of range.

    Notes

    This method accounts for a stretched last column.

  • Test whether a widget is a descendant of this widget.

    Parameters

    • widget: Widget

      The descendant widget of interest.

    Returns boolean

    true if the widget is a descendant, false otherwise.

  • Copy the current selection to the system clipboard.

    Notes

    The grid must have a data model and a selection model.

    The behavior can be configured via DataGrid.copyConfig.

    Returns void

  • Draw the corner header region which intersects the dirty rect.

    Parameters

    • rx: number
    • ry: number
    • rw: number
    • rh: number

    Returns void

  • Post a 'fit-request' message to the widget.

    Notes

    This is a simple convenience method for posting the message.

    Returns void

  • Auto sizes column-header widths based on their text content.

    Parameters

    • area: ColumnFitType = 'all'

      which area to resize: 'body', 'row-header' or 'all'.

    • padding: number = 15

      padding added to resized columns (pixels).

    • Optional numCols: number

      specify cap on the number of column resizes (optional).

    Returns void

  • Handle the DOM events for the data grid.

    Parameters

    • event: Event

      The DOM event sent to the data grid.

      Notes

      This method implements the DOM EventListener interface and is called in response to events on the data grid's DOM node. It should not be called directly by user code.

    Returns void

  • Test whether the widget's DOM node has the given class name.

    Parameters

    • name: string

      The class name of interest.

    Returns boolean

    true if the node has the class, false otherwise.

  • Hide the widget and make it hidden to its parent widget.

    Notes

    This causes the isHidden property to be true.

    If the widget is explicitly hidden, this is a no-op.

    Returns void

  • Hit test the viewport for the given client position.

    Parameters

    • clientX: number

      The client X position of the mouse.

    • clientY: number

      The client Y position of the mouse.

    Returns HitTestResult

    The hit test result, or null if the client position is out of bounds.

    Notes

    This method accounts for a stretched last row and/or column.

  • Map a client position to local viewport coordinates.

    Parameters

    • clientX: number

      The client X position of the mouse.

    • clientY: number

      The client Y position of the mouse.

    Returns {
        lx: number;
        ly: number;
    }

    The local viewport coordinates for the position.

    • lx: number
    • ly: number
  • Map a client position to virtual grid coordinates.

    Parameters

    • clientX: number

      The client X position of the mouse.

    • clientY: number

      The client Y position of the mouse.

    Returns {
        vx: number;
        vy: number;
    }

    The virtual grid coordinates for the position.

    • vx: number
    • vy: number
  • Intercept a message sent to a message handler.

    Parameters

    • handler: IMessageHandler

      The target handler of the message.

    • msg: Message

      The message to be sent to the handler.

    Returns boolean

    true if the message should continue to be processed as normal, or false if processing should cease immediately.

  • Move cursor down/up/left/right while making sure it remains within the bounds of selected rectangles

    Parameters

    Returns void

  • Invoke the message processing routine of the widget's layout.

    Parameters

    • msg: Message

      The message to dispatch to the layout.

      Notes

      This is a no-op if the widget does not have a layout.

      This will not typically be called directly by user code.

    Returns void

  • A message handler invoked on an 'after-attach' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on an 'after-hide' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on an 'after-show' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on a 'before-detach' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on a 'before-hide' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on a 'child-added' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on a 'child-removed' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on a 'close-request' message.

    Notes

    The default implementation unparents or detaches the widget.

    Parameters

    Returns void

  • A message handler invoked on a 'fit-request' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • A message handler invoked on an 'update-request' message.

    Notes

    The default implementation of this handler is a no-op.

    Parameters

    Returns void

  • Paint the grid content for the given dirty rect.

    The rect should be expressed in valid viewport coordinates.

    This is the primary paint entry point. The individual _draw* methods should not be invoked directly. This method dispatches to the drawing methods in the correct order.

    Parameters

    • rx: number
    • ry: number
    • rw: number
    • rh: number

    Returns void

  • Remove a class name from the widget's DOM node.

    Parameters

    • name: string

      The class name to remove from the node.

      Notes

      If the class name is not yet added to the node, this is a no-op.

      The class name must not contain whitespace.

    Returns void

  • Schedule a repaint of specific grid content.

    Parameters

    • region: CellRegion
    • r1: number
    • c1: number
    • r2: number
    • c2: number

    Returns void

  • Resize a column in the data grid.

    Parameters

    • region: ColumnRegion

      The region which holds the column of interest.

    • index: number

      The index of the column of interest.

    • size: null | number

      The desired size of the column.

    Returns void

  • Resize a row in the data grid.

    Parameters

    • region: RowRegion

      The region which holds the row of interest.

    • index: number

      The index of the row of interest.

    • size: number

      The desired size of the row.

    Returns void

  • Get the row at a virtual offset in the data grid.

    Parameters

    • region: RowRegion

      The region which holds the row of interest.

    • offset: number

      The virtual offset of the row of interest.

    Returns number

    The index of the row, or -1 if the offset is out of range.

    Notes

    This method accounts for a stretched last row.

  • Get the row count for a particular region in the data grid.

    Parameters

    • region: RowRegion

      The row region of interest.

    Returns number

    The row count for the specified region.

  • Get the offset of a row in the data grid.

    Parameters

    • region: RowRegion

      The region which holds the row of interest.

    • index: number

      The index of the row of interest.

    Returns number

    The offset of the row, or -1 if the index is out of range.

    Notes

    A stretched last row has no effect on the return value.

  • Get the size of a row in the data grid.

    Parameters

    • region: RowRegion

      The region which holds the row of interest.

    • index: number

      The index of the row of interest.

    Returns number

    The size of the row, or -1 if the index is out of range.

    Notes

    This method accounts for a stretched last row.

  • Scroll the viewport by the specified amount.

    Parameters

    • dx: number

      The X scroll amount.

    • dy: number

      The Y scroll amount.

    Returns void

  • Scroll the viewport by one page.

    Parameters

    • dir: "left" | "right" | "up" | "down"

      The desired direction of the scroll.

    Returns void

  • Scroll the viewport by one cell-aligned step.

    Parameters

    • dir: "left" | "right" | "up" | "down"

      The desired direction of the scroll.

    Returns void

  • Scroll to the specified offset position.

    Parameters

    • x: number

      The desired X position.

    • y: number

      The desired Y position.

    Returns void

  • Scroll the grid to the specified cell.

    Parameters

    • row: number

      The row index of the cell.

    • column: number

      The column index of the cell.

      Notes

      This is a no-op if the cell is already visible.

    Returns void

  • Scroll the grid to the specified column.

    Parameters

    • column: number

      The column index of the cell.

      Notes

      This is a no-op if the column is already visible.

    Returns void

  • Scroll the grid to the current cursor position.

    Notes

    This is a no-op if the cursor is already visible or if there is no selection model installed on the grid.

    Returns void

  • Scroll the grid to the specified row.

    Parameters

    • row: number

      The row index of the cell.

      Notes

      This is a no-op if the row is already visible.

    Returns void

  • Set the given widget flag.

    Notes

    This will not typically be called directly by user code.

    Parameters

    Returns void

  • Show or hide the widget according to a boolean value.

    Parameters

    • hidden: boolean

      true to hide the widget, or false to show it.

      Notes

      This is a convenience method for hide() and show().

    Returns void

  • Show the widget and make it visible to its parent widget.

    Notes

    This causes the isHidden property to be false.

    If the widget is not explicitly hidden, this is a no-op.

    Returns void

  • Test whether the given widget flag is set.

    Notes

    This will not typically be called directly by user code.

    Parameters

    Returns boolean

  • Toggle a class name on the widget's DOM node.

    Parameters

    • name: string

      The class name to toggle on the node.

    • Optional force: boolean

      Whether to force add the class (true) or force remove the class (false). If not provided, the presence of the class will be toggled from its current state.

    Returns boolean

    true if the class is now present, false otherwise.

    Notes

    The class name must not contain whitespace.

  • Post an 'update-request' message to the widget.

    Notes

    This is a simple convenience method for posting the message.

    Returns void