5.20231.904
wijmo.grid.multirow Class MultiRow Wijmo API Class

MultiRow Class

Extends the FlexGrid control to provide multiple rows per item.

Use the layoutDefinition property to define the layout of the rows used to display each data item.

A few FlexGrid properties are disabled in the MultiRow control because they would interfere with the custom multi-row layouts. The list of disabled properties includes the following:

FlexGrid.allowMerging, FlexGrid.mergeManager, FlexGrid.autoGenerateColumns, FlexGrid.columnGroups, FlexGrid.allowDragging, FlexGrid.allowPinning, FlexGrid.childItemsPath, FlexGridDetailProvider, and Column.visible.

Note also that cells in the FlexGrid.columnFooters panel do not follow the multi-row layout. That is because those cells belong to rows that are not created by the grid itself, but by custom code.

Heirarchy

Constructors

Properties

Methods

Events

Constructors

constructor

  • new MultiRow(element: any, options?: any): MultiRow
  • Initializes a new instance of the MultiRow class.

    In most cases, the options parameter will include the value for the layoutDefinition property.

    Parameters

    • element: any

      The DOM element that hosts the control, or a CSS selector for the host element (e.g. '#theCtrl').

    • Optional options: any

      JavaScript object containing initialization data for the control.

    Returns MultiRow

Properties

activeCell

activeCell: HTMLElement

Gets the HTMLElement that represents the currently active cell element.

If no cell is currently selected, or if the selected cell is not currently within view, this property returns null.

activeEditor

activeEditor: HTMLInputElement

Gets the HTMLInputElement that represents the currently active cell editor.

If no cell is currently being edited, this property returns null.

allowAddNew

allowAddNew: boolean

Gets or sets a value that indicates whether the grid should provide a new row template so users can add items to the source collection.

The new row template will not be displayed if the isReadOnly property is set to true.

The default value for this property is false.

allowDelete

allowDelete: boolean

Gets or sets a value that indicates whether the grid should delete selected rows when the user presses the Delete key.

Selected rows will not be deleted if the isReadOnly property is set to true.

The default value for this property is false.

allowDragging

allowDragging: AllowDragging

Gets or sets a value that determines whether users are allowed to drag rows and/or columns with the mouse.

If the autoScroll property is set to true, the grid will automatically scroll its contents while the user drags rows or columns into new positions.

The grid allows dragging columns by default.

Dragging rows requires special considerations in bound scenarios.

When you drag rows on bound grids, the rows will get out of sync with the data source (row 4 may refer to item 6 for example). To avoid this, you should handle the draggedRow event and synchronize the data with the new row positions.

Also, remember to set the allowSorting property to false or you the row order will be determined by the data, and dragging rows will be pointless.

This fiddle demonstrates row dragging with a bound grid: Bound Row Dragging.

The default value for this property is AllowDragging.Columns for the FlexGrid control and AllowDragging.None for the PivotGrid control.

This property does not apply to the MultiRow control.

allowMerging

allowMerging: AllowMerging

Gets or sets which parts of the grid provide cell merging.

The default value for this property is AllowMerging.None for the FlexGrid control and AllowMerging.All for the PivotGrid control.

This property does not apply to the MultiRow control.

allowResizing

allowResizing: AllowResizing

Gets or sets a value that determines whether users may resize rows and/or columns with the mouse.

If resizing is enabled, users can resize columns by dragging the right edge of column header cells, or rows by dragging the bottom edge of row header cells.

Users may also double-click the edge of the header cells to automatically resize rows and columns to fit their content. The auto-size behavior can be customized using the autoSizeMode property.

The default value for this property is AllowResizing.Columns.

allowSorting

allowSorting: AllowSorting

Gets or sets a value that determines whether users are allowed to sort columns by clicking the column header cells.

The default value for this property is AllowSorting.SingleColumn.

alternatingRowStep

alternatingRowStep: number

Gets or sets a value that determines the number of regular rows between 'alternating' rows.

The default value for this property is 1 for the FlexGrid. Set it to zero to disable alternating rows, or to a number greater than one to insert multiple regular rows between alternating rows.

The default value for this property is 1 for the FlexGrid control and 0 for the PivotGrid control.

anchorCursor

anchorCursor: boolean

Gets or sets a value that determines whether extending selections with the mouse or keyboard should change the start (cursor) or the end of the current selection.

The default value for this property is false, which causes the grid to move the cursor and keep the selection end anchored.

Setting this property to true causes the grid to move the selection end and keep the cursor anchored. This is Excel's behavior.

ariaLabel

ariaLabel: string

Gets or sets the aria label property of cells host.

autoClipboard

autoClipboard: boolean

Gets or sets a value that determines whether the grid should handle clipboard shortcuts.

The clipboard shortcuts are as follows:

ctrl+C, ctrl+Ins
Copy grid selection to clipboard.
ctrl+V, shift+Ins
Paste clipboard text to grid selection.

Only visible rows and columns are included in clipboard operations.

Read-only cells are not affected by paste operations.

The default value for this property is true.

autoGenerateColumns

autoGenerateColumns: boolean

Gets or sets a value that determines whether the grid should generate columns automatically based on the itemsSource.

The column generation depends on the itemsSource property containing at least one item. This data item is inspected and a column is created and bound to each property that contains a primitive value (number, string, Boolean, or Date).

Properties set to null do not generate columns, because the grid would have no way of guessing the appropriate type. In this type of scenario, you should set the autoGenerateColumns property to false and create the columns explicitly. For example:

import { FlexGrid } from '@grapecity/wijmo.grid';
let grid = new FlexGrid('#theGrid', {
  autoGenerateColumns: false, // data items may contain null values
  columns: [                  // so define columns explicitly
    { binding: 'name', header: 'Name', dataType: 'String' },
    { binding: 'amount', header: 'Amount', dataType: 'Number' },
    { binding: 'date', header: 'Date', dataType: 'Date' },
    { binding: 'active', header: 'Active', dataType: 'Boolean' }
  ],
  itemsSource: customers
});

The default value for this property is true for the FlexGrid control and false for the PivotGrid control.

autoRowHeights

autoRowHeights: boolean

Gets or sets a value that determines whether the grid should automatically resize the rows when the data or grid layout change.

This property is especially useful when the grid has columns configured to word-wrap their content (see Column.wordWrap), and when the grid has a relatively small number of rows (auto-sizing is an expensive operation).

The default value for this property is false.

autoScroll

autoScroll: boolean

Gets or sets a value that determines whether the grid should automatically scroll its contents while users drag rows or columns into new positions.

Row and column dragging are controlled by the allowDragging property.

The default value for this property is true.

autoSearch

autoSearch: boolean

Gets or sets a value that determines whether the grid should search for cells as the users types into read-only cells.

The search happens on the column that is currently selected, if it is not editable. The search starts at the currently selected row and is case-insensitive.

See also the caseSensitiveSearch property.

The default value for this property is false.

autoSizeMode

autoSizeMode: AutoSizeMode

Gets or sets which cells should be taken into account when auto-sizing a row or column.

This property controls what happens when users double-click the edge of a column header.

By default, the grid will automatically set the column width based on the content of the header and data cells in the column. This property allows you to change that to include only the headers or only the data.

The default value for this property is AutoSizeMode.Both.

bigCheckboxes

bigCheckboxes: boolean

Gets or sets a value that determines whether the checkboxes used to edit boolean columns should extend to cover the whole cell width.

Big checkboxes are easier to toggle with the mouse, since the user may click anywhere in the cell to toggle them.

The default value for this property is false.

bottomLeftCells

bottomLeftCells: GridPanel

Gets the GridPanel that contains the bottom left cells.

The bottomLeftCells panel appears below the row headers, to the left of the columnFooters panel.

caseSensitiveSearch

caseSensitiveSearch: boolean

Gets or sets a value that determines whether searches performed while the user types should case-sensitive.

The searches include searching for regular text (see the autoSearch property) as well as searching for items while editing data-mapped cells (see the Column.dataMap property).

The default value for this property is false (searches are not case-sensitive by default).

cellFactory

cellFactory: CellFactory

Gets or sets the CellFactory that creates and updates cells for this grid.

cells

cells: GridPanel

Gets the GridPanel that contains the data cells.

centerHeadersVertically

centerHeadersVertically: boolean

Gets or sets a value that determines whether the content of cells that span multiple rows should be vertically centered.

The default value for this property is true.

childItemsPath

childItemsPath: string | string[] | null

Gets or sets the name of the property (or properties) used to generate child rows in hierarchical grids.

Set this property to a string to specify the name of the property that contains an item's child items (e.g. childItemsPath = 'items';).

If items at different levels have child items with different names, set this property to an array containing the names of the properties that contain child items et each level (e.g. childItemsPath = ['checks','earnings'];).

Example

The default value for this property is null.

This property does not apply to the MultiRow control.

clientSize

clientSize: Size

Gets the client size of the control (control size minus headers and scrollbars).

cloneFrozenCells

cloneFrozenCells: boolean | null

Gets or sets a value that determines whether the FlexGrid should clone frozen cells and show then in a separate element to reduce flicker while scrolling.

The default value for this property is null, which causes the grid to select the best setting depending on the browser.

collapsedHeaders

collapsedHeaders: boolean | null

Gets or sets a value that determines whether column headers should be collapsed and displayed as a single row containing the group headers.

If you set the collapsedHeaders property to true, remember to set the header property of every group in order to avoid empty header cells.

Setting the collapsedHeaders property to null causes the grid to show all header information (groups and columns). In this case, the first row will show the group headers and the remaining rows will show the individual column headers.

The default value for this property is false.

collectionView

collectionView: ICollectionView

Gets the ICollectionView that contains the grid data.

If the itemsSource property was set to an ICollectionView, this property returns that value.

If the itemsSource property was set to an array of data items, this property returns the internal CollectionView created by the grid to support currency, editing, and sorting.

columnFooters

columnFooters: GridPanel

Gets the GridPanel that contains the column footer cells.

The columnFooters panel appears below the grid cells, to the right of the bottomLeftCells panel. It can be used to display summary information below the grid data.

The example below shows how you can add a row to the columnFooters panel to display summary data for columns that have the Column.aggregate property set:

function addFooterRow(flex) {

  // create a GroupRow to show aggregates
  let row = new wijmo.grid.GroupRow();

  // add the row to the column footer panel
  flex.columnFooters.rows.push(row);

  // show a sigma on the header
  flex.bottomLeftCells.setCellData(0, 0, '\u03A3');
}

columnGroups

columnGroups: any[]

Gets or sets an array used to define hierarchical column groups.

The items in the array should be JSON objects with properties of Column objects, plus three optional members:

  • 'columns' array containing an array of child columns,
  • 'collapseTo' string containing the binding(s) of the child column(s) that should remain visible when the group is collapsed.
  • 'isCollapsed' boolean that determines if the group should be initially collapsed.

For example, the code below generates a grid with two column groups, both initially collapsed:

new FlexGrid('#theGrid', {
    autoGenerateColumns: false,
    columnGroups: [
        { header: 'Group 1', align: 'center', collapseTo: ['id', 'country'], isCollapsed: true, columns: [
            { binding: 'id', header: 'ID' },
            { binding: 'date', header: 'Date', dataType: 'Date' },
            { binding: 'country', header: 'Country', dataType: 'String' },
            { binding: 'active', header: 'Active', dataType: 'Boolean' },
        ]},
        { header: 'Group 2', align: 'center', collapseTo: 'sales', isCollapsed: true, columns: [
            { binding: 'sales', header: 'Sales', dataType: 'Number' },
            { binding: 'expenses', header: 'Expenses', dataType: 'Number' },
        ]}
    ],
    itemsSource: getData(20)
});

columnHeaders

columnHeaders: GridPanel

Gets the GridPanel that contains the column header cells.

columnLayout

columnLayout: string

Gets or sets a JSON string that defines the current column layout.

The column layout string represents an array with the columns and their properties. It can be used to persist column layouts defined by users so they are preserved across sessions, and can also be used to implement undo/redo functionality in applications that allow users to modify the column layout.

The column layout string does not include properties that cannot be converted to JSON, such as dataMap and editor.

If you want to save and restore column layouts and don't require the layouts to be serializable, you can clone the content of the columns property and restore it later using array methods. This is not as convenient as using the columnLayout property, but it does allow you to save and restore data maps and editors.

columns

Gets the grid's column collection.

commitEmptyEdits

commitEmptyEdits: boolean

Gets or sets a value that indicates how the grid commit empty edits to cell values.

The default value for this property is true.

If you choose to ignore commit empty edits, the Grid will not commit empty edits to cell values if the original value is null.

controlRect

controlRect: Rect

Gets the bounding rectangle of the control in page coordinates.

copyHeaders

copyHeaders: HeadersVisibility

Gets or sets a value that determines whether the grid should include the content of header cells when copying data to the clipboard.

This property is especially useful in read-only grids, because the header information typically should not be included when pasting data into the grid.

The default value for this property is HeadersVisibility.None for the FlexGrid control and HeadersVisibility.All for the PivotGrid control.

deferResizing

deferResizing: boolean

Gets or sets a value that determines whether row and column resizing should be deferred until the user releases the mouse button.

By default, deferResizing is set to false, causing rows and columns to be resized as the user drags the mouse. Setting this property to true causes the grid to show a resizing marker and to resize the row or column only when the user releases the mouse button.

The default value for this property is false for the FlexGrid control and true for the PivotGrid control.

editColumnIndex

editColumnIndex: number | null

Gets or sets the index of column in the row header panel that shows whether items are being edited.

The default value for this property is null, which causes the grid to show the edit glyph on the last column of the rowHeaders panel.

editRange

editRange: CellRange

Gets a CellRange that identifies the cell currently being edited.

editableCollectionView

editableCollectionView: IEditableCollectionView

Gets the IEditableCollectionView that contains the grid data.

errorTip

errorTip: Tooltip | null

Gets or sets the Tooltip object used to show validation errors detected by the grid when the showErrors property is set to true.

By default, this property is set to a tooltip with zero show delay (so it appears immediately when hovering over invalid cells), no HTML content, and a "wj-error-tip" class which can be used to customize the tooltip's appearance.

Setting this property to null causes the control to use the cell's "title" attribute to show validation errors.

expandSelectionOnCopyPaste

expandSelectionOnCopyPaste: boolean

Gets or sets a value that determines whether the grid should automatically expand the selection to include cells in merged ranges when copying or pasting content to/from the clipboard.

The default value for this property is true.

frozenColumns

frozenColumns: number

Gets or sets the number of frozen columns.

Frozen columns do not scroll horizontally, but the cells they contain may be selected and edited.

The default value for this property is 0.

frozenRows

frozenRows: number

Gets or sets the number of frozen rows.

Frozen rows do not scroll vertically, but the cells they contain may be selected and edited.

The default value for this property is 0.

groupHeaderFormat

groupHeaderFormat: string | null

Gets or sets the format string used to create the group header content.

The string may contain any text, plus the following replacement strings:

  • {name}: The name of the property being grouped on.
  • {value}: The value of the property being grouped on.
  • {level}: The group level.
  • {count}: The total number of items in this group.

If a column is bound to the grouping property, the column header is used to replace the {name} parameter, and the column's format and data maps are used to calculate the {value} parameter. If no column is available, the group information is used instead.

You may add invisible columns bound to the group properties in order to customize the formatting of the group header cells.

The default value for this property is null, which causes the grid to use a culture-specific version of the string

'{name}: <b>{value}</b>({count:n0} items)'

This default format string creates group headers similar to

'Country: <b>UK</b> (12 items)'
'Country: <b>Japan</b> (8 items)'

headerLayoutDefinition

headerLayoutDefinition: any[] | null

Gets or sets an array that defines the layout of the rows used to display the grid's column headers.

The array contains a list of cell group objects similar to those used with the layoutDefinition property.

The default value for this property is null, which causes the grid to use the layoutDefinition property to create the column headers.

headersFocusability

headersFocusability: HeadersFocusability

Gets or sets a value that determines whether the row and column headers are focusable.

The default value for this property is HeadersFocusability.None.

headersVisibility

headersVisibility: HeadersVisibility

Gets or sets a value that determines whether the row and column headers are visible.

The default value for this property is HeadersVisibility.All.

hostElement

hostElement: HTMLElement

Gets the DOM element that is hosting the control.

imeEnabled

imeEnabled: boolean

Gets or sets a value that determines whether the grid should support Input Method Editors (IME) while not in edit mode.

This property is relevant only for sites/applications in Japanese, Chinese, Korean, and other languages that require IME support.

The default value for this property is false.

isDisabled

isDisabled: boolean

Gets or sets a value that determines whether the control is disabled.

Disabled controls cannot get mouse or keyboard events.

isReadOnly

isReadOnly: boolean

Gets or sets a value that determines whether the user can modify cell values using the mouse and keyboard.

The default value for this property is false for the FlexGrid control and true for the PivotGrid control.

isTouching

isTouching: boolean

Gets a value that indicates whether the control is currently handling a touch event.

isUpdating

isUpdating: boolean

Gets a value that indicates whether the control is currently being updated.

itemFormatter

itemFormatter: IItemFormatter

Gets or sets a formatter function used to customize cells on this grid.

The formatter function can add any content to any cell. It provides complete flexibility over the appearance and behavior of grid cells.

If specified, the function should take four parameters: the GridPanel that contains the cell, the row and column indices of the cell, and the HTML element that represents the cell. The function will typically change the innerHTML property of the cell element.

For example:

flex.itemFormatter = (panel, r, c, cell) => {
  if (panel.cellType == CellType.Cell) {

    // draw sparklines in the cell
    let col = panel.columns[c];
    if (col.name == 'sparklines') {
      cell.innerHTML = getSparkline(panel, r, c);
    }
  }
}

Note that the FlexGrid recycles cells, so if your itemFormatter modifies the cell's style attributes, you must make sure that it resets these attributes for cells that should not have them. For example:

flex.itemFormatter = (panel, r, c, cell) => {

  // reset attributes we are about to customize
  let s = cell.style;
  s.color = '';
  s.backgroundColor = '';
  // customize color and backgroundColor attributes for this cell
  ...
}

If you have a scenario where multiple clients may want to customize the grid rendering (for example when creating directives or re-usable libraries), consider using the formatItem event instead. The event allows multiple clients to attach their own handlers.

itemValidator

itemValidator: IItemValidator

Gets or sets a validator function to determine whether cells contain valid data.

If specified, the validator function should take parameters containing the cell's row and column indices and a parsing parameter that describes whether the data has already been parsed and applied to the data item (parsing == false), or whether the user was trying to edit the value and entered a value that could not be parsed into the data type expected (parsing == true).

The method returns a string containing an error message, or null if no errors were detected.

For example,

grid.itemValidator = (row: number, col: number, parsing: boolean) => {
    let item = grid.rows[row].dataItem,
        prop = grid.columns[col].binding;

    // parsing failed, show message
    if (parsing) {
        if (prop == 'date') {
            return 'Please enter a valid date in the format "MM/dd/yyyy"';
        } else if (prop == 'id') {
            return 'Please enter a positive number';
        }
    }

    // check that stored (parsed) data is valid
    if (prop == 'date' && item.date < minDate) {
        return 'Please enter a date after ' + Globalize.formatDate(minDate, 'd');
    } else if (prop == 'id' && item.id < 0) {
        return 'Please enter a positive number';
    }
});

See also the CollectionView.getError method.

itemsSource

itemsSource: any

Gets or sets the array or ICollectionView that contains items shown on the grid.

keyActionEnter

keyActionEnter: KeyAction

Gets or sets the action to perform when the ENTER key is pressed.

The default setting for this property is KeyAction.MoveDown, which causes the control to move the selection to the next row. This is the standard Excel behavior.

keyActionTab

keyActionTab: KeyAction

Gets or sets the action to perform when the TAB key is pressed.

The default setting for this property is KeyAction.None, which causes the browser to select the next or previous controls on the page when the TAB key is pressed. This is the recommended setting to improve page accessibility.

Note that the default setting for the inherited FlexSheet control is KeyAction.CycleOut (see below).

In previous versions, the default was set to KeyAction.Cycle, which caused the control to move the selection across and down the grid. This is the standard Excel behavior, but is not good for accessibility.

There is also a KeyAction.CycleOut setting that causes the selection to move through the cells (as KeyAction.Cycle), and then on to the next/previous control on the page when the last or first cells are selected.

layoutDefinition

layoutDefinition: any[]

Gets or sets an array that defines the layout of the rows used to display each data item.

The array contains a list of cell group objects which have the following properties:

  • header: Group header (shown when the headers are collapsed).
  • isRowHeader: Whether cells in this group should be displayed and treated as row header cells.
  • colspan: Number of grid columns spanned by the group.
  • cells: Array of cell objects, which extend Column with a colspan property.

When the layoutDefinition property is set, the grid scans the cells in each group as follows:

  1. The grid calculates the colspan of the group either as group's own colspan or as span of the widest cell in the group, whichever is wider.
  2. If the cell fits the current row within the group, it is added to the current row.
  3. If it doesn't fit, it is added to a new row.

When all groups are ready, the grid calculates the number of rows per record to the maximum rowspan of all groups, and adds rows to each group to pad their height as needed.

This scheme is simple and flexible. For example:

{ header: 'Group 1', cells: [{ binding: 'c1' }, { binding: 'c2'}, { binding: 'c3' }]}

The group has colspan 1, so there will be one cell per column. The result is:

| C1 |
| C2 |
| C3 |

To create a group with two columns, set the colspan property of the group:

{ header: 'Group 1', colspan: 2, cells:[{ binding: 'c1' }, { binding: 'c2'}, { binding: 'c3' }]}

The cells will wrap as follows:

| C1 | C2 |
| C3      |

Note that the last cell spans two columns (to fill the group).

You can also specify the colspan on individual cells rather than on the group:

{ header: 'Group 1', cells: [{binding: 'c1', colspan: 2 }, { binding: 'c2'}, { binding: 'c3' }]}

Now the first cell has colspan 2, so the result is:

| C1      |
| C2 | C3 |

You can also make cells extend vertically using the cell's rowspan property:

{ header: 'Group 1', cells: [{binding: 'c1', rowspan: 2 }, { binding: 'c2'}, { binding: 'c3' }]}

Now the first cell has rowspan 2, so the result is:

| C1 | C2 |
|    | C3 |

Because cells extend the Column class, you can add all the usual Column properties to any cells:

{ header: 'Group 1', cells: [
   { binding: 'c1', colspan: 2 },
   { binding: 'c2'},
   { binding: 'c3', format: 'n0', required: false, etc... }
]}

The isRowHeader property of the cell groups allows you to create groups to be displayed as row header cells. This is done using frozen columns, so even though the row headers are regular cells, they look and behave like header cells.

Setting the isRowHeader property to true automatically sets the cell's isReadOnly property to true (headers cannot be edited), adds a 'wj-header' style to the cell's cssClass property (so the cells are styled as headers), and sets the cell's cellTemplate property to its header value (so the cell shows the header as an unbound string). You may choose to set the cell's binding property instead of header if you want to show bound values in the row header cells.

lazyRender

lazyRender: boolean

Gets or sets a value that determines whether the grid should skip rendering cells that were updated in the last render cycle.

The default value for this property is true.

mergeManager

mergeManager: MergeManager

Gets or sets the MergeManager object responsible for determining how cells should be merged.

multiRowGroupHeaders

multiRowGroupHeaders: boolean

Gets or sets a value that determines whether group headers should have multiple rows instead of a single header row.

This property is useful when you want to display aggregate values in the group headers (see the Column.aggregate property).

The default value for this property is false.

newRowAtTop

newRowAtTop: boolean

Gets or sets a value that indicates whether the new row template should be located at the top of the grid or at the bottom.

If you set the newRowAtTop property to true, and you want the new row template to remain visible at all times, set the frozenRows property to one. This will freeze the new row template at the top so it won't scroll off the view.

The new row template will be displayed only if the allowAddNew property is set to true and if the itemsSource object supports adding new items.

The default value for this property is false.

preserveOutlineState

preserveOutlineState: boolean

Gets or sets a value that determines whether the grid should preserve the expanded/collapsed state of nodes when the data is refreshed.

The preserveOutlineState property implementation is based on JavaScript's Map object, which is not available in IE 9 or 10.

The default value for this property is true.

preserveSelectedState

preserveSelectedState: boolean

Gets or sets a value that determines whether the grid should preserve the selected state of rows when the data is refreshed.

The default value for this property is true.

preserveWhiteSpace

preserveWhiteSpace: boolean

Gets or sets a value that determines whether the grid should keep whitespace in cells as they appear in the data (white-space: pre) or whether it should collapse the whitespace into a single space character (white-space: normal).

This property allows you to specify how the grid should handle white space without changing any CSS rules. You choose to use CSS rules instead, however, since they provide better control over scope.

For example, you could create CSS rules that apply to all grids in the application, to specific grids, or to specific columns.

Be aware that setting this property to true may have undesired effects in applications that use interop cell templates (Vue templates especially).

The default value for this property is false.

quickAutoSize

quickAutoSize: boolean | null

Gets or sets a value that determines whether the grid should optimize performance over precision when auto-sizing columns.

Setting this property to false disables quick auto-sizing. Setting it to true enables the feature, subject to the value of each column's wijmo.grid.Column.quickAutoSize property.

The default value for this property is null, which enables quick auto-sizing for grids that don't have a custom itemFormatter or handlers attached to the formatItem event.

Quick auto-sizing uses different strategies when auto-sizing rows or columns.

When auto-sizing columns, it uses a temporary canvas element to locate the row with the widest entry for a column. When the row is located, its contents are measured precisely. The limitation with this approach is that the canvas only renders plain text, so if cells contain HTML the auto-sizing may miss the widest column.

When auto-sizing rows, it uses a cache to store the row heights based on the cell content, and skips measuring numeric cells. The limitation with this approach is that it only improves performance if many cells have the same content, or if many columns are numeric.

If you find that auto-sizing is slowing down your application, it is probably worth setting quickAutoSize to true and checking the results to see if it works correctly and improves performance for your app.

recordViewRange

recordViewRange: CellRange

Similar with viewRange but row is first record index instead of first row index row2 is last record index instead of last records row index

refreshOnEdit

refreshOnEdit: boolean

Gets or sets a value that determines whether the grid should refresh all cells after a cell is edited.

The default value for this property is true.

rightToLeft

rightToLeft: boolean

Gets a value indicating whether the control is hosted in an element with right-to-left layout.

rowHeaderPath

rowHeaderPath: string

Gets or sets the name of the property used to create row header cells.

Row header cells are not visible or selectable. They are meant for use with accessibility tools.

rowHeaders

rowHeaders: GridPanel

Gets the GridPanel that contains the row header cells.

rows

Gets the grid's row collection.

rowsPerItem

rowsPerItem: number

Gets the number of rows used to display each item.

This value is calculated automatically based on the value of the layoutDefinition property.

scrollPosition

scrollPosition: Point

Gets or sets a Point that represents the value of the grid's scrollbars.

scrollSize

scrollSize: Size

Gets the size of the grid content in pixels.

selectedItems

selectedItems: any[]

Gets or sets an array containing the data items that are currently selected.

Note: this property can be read in all selection modes, but it can be set only when selectionMode is set to SelectionMode.ListBox.

selectedRanges

selectedRanges: CellRange[]

Gets or sets an array with CellRange objects that represent the current selection.

The first element in the array is the current selection. If the grid's selectionMode property is set to SelectionMode.MultiRange, the array may contain additional ranges that represent the extended selection.

Note that ranges in the selectedRanges array may contain overlapping areas, which may be important when performing actions like aggregating over the extended selection.

selectedRows

selectedRows: Row[]

Gets or sets an array containing the rows that are currently selected.

Note: this property can be read in all selection modes, but it can be set only when selectionMode is set to SelectionMode.ListBox.

selection

selection: CellRange

Gets or sets the current selection.

selectionMode

selectionMode: SelectionMode

Gets or sets the current selection mode.

showDropDown

showDropDown: boolean

Gets or sets a value that indicates whether the grid should add drop-down buttons to data-mapped cells.

The drop-down buttons are shown on columns that have a Column.dataMap and are editable.

Clicking on the drop-down buttons causes the grid to show a drop-down list from which users can select the cell value.

This setting may be overridden on specific columns using the column's Column.dataMapEditor property.

Cell drop-downs require the wijmo.input module to be loaded.

showErrors

showErrors: boolean

Gets or sets a value that determines whether the grid should add the 'wj-state-invalid' class to cells that contain validation errors and tooltips with error descriptions.

The grid detects validation errors using the itemValidator property and the CollectionView.getError property on the grid's itemsSource.

The default value for this property is true.

showGroups

showGroups: boolean

Gets or sets a value that determines whether the FlexGrid should insert group rows to delimit data groups.

Data groups are created by modifying the ICollectionView.groupDescriptions property of the ICollectionView object used as an itemsSource.

The default value for this property is true.

showHeaderCollapseButton

showHeaderCollapseButton: boolean

Gets or sets a value that determines whether the grid should display a button in the column header panel to allow users to collapse and expand the column headers.

If the button is visible, clicking on it will cause the grid to toggle the value of the collapsedHeaders property.

The default value for this property is false.

showMarquee

showMarquee: boolean

Gets or sets a value that indicates whether the grid should display an Excel-style marquee around the current selection.

The default value for this property is false.

If you choose to show the marquee, you may want to improve accessibility by using some simple CSS to make the marquee fully opaque only when the grid has the focus:

.wj-flexgrid:not(.wj-state-focused) .wj-marquee {
    opacity: 0.2;
}

showPlaceholders

showPlaceholders: boolean

Gets or sets a value that determines whether the grid should use the column headers as placeholders when editing cells.

The default value for this property is false.

This property is especially useful in grids that have multiple rows per data item (like the MultiRow grid) and in grids that allow adding new items (see the allowAddNew property).

This property only works with the grid's built-in editor. If you are using custom editors (see the Column.editor property), then you are responsible for setting the placeholder property on those.

The Internet Explorer browser does not show input placeholders on focused input elements, so this property is not useful in IE.

showSelectedHeaders

showSelectedHeaders: HeadersVisibility

Gets or sets a value that indicates whether the grid should add class names to indicate selected header cells.

The default value for this property is HeadersVisibility.None.

showSort

showSort: boolean

Gets or sets a value that determines whether the grid should display sort indicators in the column headers.

Sorting is controlled by the ICollectionView.sortDescriptions property of the ICollectionView object used as a the grid's itemsSource.

The default value for this property is true.

skipMerged

skipMerged: boolean

Gets or sets a value that determines whether when copying, skip cells that have been merged The default value for this property is false.

sortRowIndex

sortRowIndex: number | null

Gets or sets the index of row in the column header panel that shows and changes the current sort.

The default value for this property is null, which causes the bottom row in the columnHeaders panel to act as the sort row.

stickyHeaders

stickyHeaders: boolean

Gets or sets a value that determines whether column headers should remain visible when the user scrolls the document.

The default value for this property is false.

tabOrder

tabOrder: number

Gets or sets a value of the tabindex attribute associated with the control.

tabindex attribute value can be defined statically for a Wijmo control by specifying it on the control's host HTML element. But this value can't be changed later during application lifecycle, because Wijmo controls have complex structure, and the control may need to propagate this attribute value to its internal element to work properly.

Because of this, to read or change control's tabindex dynamically, you should do it using this property.

topLeftCells

topLeftCells: GridPanel

Gets the GridPanel that contains the top left cells (to the left of the column headers).

treeIndent

treeIndent: number

Gets or sets the indent used to offset row groups of different levels.

The default value for this property is 14 pixels for the FlexGrid control, and 32 pixels for the PivotGrid.

validateEdits

validateEdits: boolean

Gets or sets a value that determines whether the grid should remain in edit mode when the user tries to commit edits that fail validation.

The grid detects validation errors by calling the CollectionView.getError method on the grid's itemsSource.

The default value for this property is true.

viewRange

viewRange: CellRange

Gets the range of cells currently in view.

virtualizationThreshold

virtualizationThreshold: number | number[]

Gets or sets the minimum number of rows and/or columns required to enable virtualization.

This property is set to zero by default, meaning virtualization is always enabled. This improves binding performance and memory requirements, at the expense of a small performance decrease while scrolling.

If your grid has a small number of rows (about 50 to 100), you may be able to improve scrolling performance by setting this property to a slightly higher value (like 150). This will disable virtualization and will slow down binding, but may improve perceived scroll performance. For example, the code below sets causes the grid to virtualize cells when the data source has more than 150 items:

// virtualize grid when there are more than 150 items
theGrid.virtualizationThreshold = 150;

Setting this property to values higher than 200 is not recommended. Loading times will become too long; the grid will freeze for a few seconds while creating cells for all rows, and the browser will become slow because of the large number of elements on the page.

If you want to set separate virtualization thresholds for rows and columns, you may set the virtualizationThreshold property to an array with two numbers. In this case, the first number will be used as the row threshold and the second as the column threshold. For example, the code below sets causes the grid to virtualize rows but not columns:

// virtualize rows (threshold 0) but not columns (threshold 10,000)
theGrid.virtualizationThreshold = [0, 10000];

The default value for this property is 0, which causes the grid to virtualize all rows and columns.

Static controlTemplate

controlTemplate: string

Gets or sets the template used to instantiate FlexGrid controls.

Static defaultTypeWidth

defaultTypeWidth: object

Gets a reference to a static object that defines the default width for auto-generated grid columns based on their types.

The object keys are DataType values. The object values are either numbers (widths in pixels) or star-size strings (multiples of the default width defined by the columns defaultSize property).

For example:

import { FlexGrid } from '@grapecity/wijmo.grid';
import { DataType } from '@grapecity/wijmo';

// make boolean columns on all grids 100px wide by default
FlexGrid.defaultTypeWidth[DataType.Boolean] = 100;

// make numeric columns on all grids 75% as wide as the columns defaultSize
FlexGrid.defaultTypeWidth[DataType.Number] = '0.75*';

Methods

addEventListener

  • addEventListener(target: EventTarget, type: string, fn: any, capture?: boolean, passive?: boolean): void
  • Adds an event listener to an element owned by this Control.

    The control keeps a list of attached listeners and their handlers, making it easier to remove them when the control is disposed (see the dispose and removeEventListener methods).

    Failing to remove event listeners may cause memory leaks.

    The passive parameter is set to false by default, which means the event handler may call event.preventDefault(). If you are adding passive handlers to touch or wheel events, setting this parameter to true will improve application performance.

    For details on passive event listeners, please see Improving scrolling performance with passive listeners.

    Parameters

    • target: EventTarget

      Target element for the event.

    • type: string

      String that specifies the event.

    • fn: any

      Function to execute when the event occurs.

    • Optional capture: boolean

      Whether the listener should be handled by the control before it is handled by the target element.

    • Optional passive: boolean

      Indicates that the handler will never call preventDefault().

    Returns void

adjustFrozenRowColSize

  • adjustFrozenRowColSize(index: number, type: FrozenRowCol, delta?: number): void
  • Adjusts the size of a column/row ensuring the total size of frozen elements does not exceed the grid size.

    Parameters

    Returns void

applyTemplate

  • applyTemplate(classNames: string, template: string, parts: Object, namePart?: string): HTMLElement
  • Applies the template to a new instance of a control, and returns the root element.

    This method should be called by constructors of templated controls. Therefore, this method is not available. It is responsible for binding the template parts to the corresponding control members.

    For example, the code below applies a template to an instance of an InputNumber control. The template must contain elements with the 'wj-part' attribute set to 'input', 'btn-inc', and 'btn-dec'. The control members '_tbx', '_btnUp', and '_btnDn' will be assigned references to these elements.

    this.applyTemplate('wj-control wj-inputnumber', templateString, {
      _tbx: 'input',
      _btnUp: 'btn-inc',
      _btnDn: 'btn-dec'
    }, 'input');

    @param classNames Names of classes to add to the control's host element. @param template An HTML string that defines the control template. @param parts A dictionary of part variables and their names. @param namePart Name of the part to be named after the host element. This determines how the control submits data when used in forms.

    Parameters

    • classNames: string
    • template: string
    • parts: Object
    • Optional namePart: string

    Returns HTMLElement

autoSizeColumn

  • autoSizeColumn(c: number, header?: boolean, extra?: number): void
  • Resizes a column to fit its content.

    This method only works if the grid is visible. If its host element has not been added to the DOM, or if any of the grid's ancestor elements is hidden, the grid will not be able to measure the cells and therefore will not be able to auto-size the columns.

    Parameters

    • c: number

      Index of the column to resize.

    • Optional header: boolean

      Whether the column index refers to a regular or a header row.

    • Optional extra: number

      Extra spacing, in pixels.

    Returns void

autoSizeColumns

  • autoSizeColumns(firstColumn?: number, lastColumn?: number, header?: boolean, extra?: number): void
  • Resizes a range of columns to fit their content.

    The grid will always measure all rows in the current view range, plus up to 2,000 rows not currently in view. If the grid contains a large amount of data (say 50,000 rows), then not all rows will be measured since that could take a long time.

    This method only works if the grid is visible. If its host element has not been added to the DOM, or if any of the grid's ancestor elements is hidden, the grid will not be able to measure the cells and therefore will not be able to auto-size the columns.

    Parameters

    • Optional firstColumn: number

      Index of the first column to resize (defaults to the first column).

    • Optional lastColumn: number

      Index of the last column to resize (defaults to the last column).

    • Optional header: boolean

      Whether the column indices refer to regular or header columns.

    • Optional extra: number

      Extra spacing, in pixels.

    Returns void

autoSizeRow

  • autoSizeRow(r: number, header?: boolean, extra?: number): void
  • Resizes a row to fit its content.

    This method only works if the grid is visible. If its host element has not been added to the DOM, or if any of the grid's ancestor elements are hidden, the grid will not be able to measure the cells and therefore will not be able to auto-size the rows.

    Parameters

    • r: number

      Index of the row to resize.

    • Optional header: boolean

      True to indicate the row index refers to a header row, false to indicate it refers to a regular data row, or null to indicate it refers to a footer row.

    • Optional extra: number

      Extra spacing, in pixels.

    Returns void

autoSizeRows

  • autoSizeRows(firstRow?: number, lastRow?: number, header?: boolean, extra?: number): void
  • Resizes a range of rows to fit their content.

    This method only works if the grid is visible. If its host element has not been added to the DOM, or if any of the grid's ancestor elements is hidden, the grid will not be able to measure the cells and therefore will not be able to auto-size the rows.

    Parameters

    • Optional firstRow: number

      Index of the first row to resize.

    • Optional lastRow: number

      Index of the last row to resize.

    • Optional header: boolean

      Whether the row indices refer to regular or header rows.

    • Optional extra: number

      Extra spacing, in pixels.

    Returns void

beginUpdate

  • beginUpdate(): void

canEditCell

  • canEditCell(r: number, c: number): boolean
  • Gets a value that indicates whether a given cell can be edited.

    Parameters

    • r: number

      Index of the row that contains the cell.

    • c: number

      Index of the column that contains the cell.

    Returns boolean

collapseGroupsToLevel

  • collapseGroupsToLevel(level: number): void
  • Collapses all the group rows to a given level.

    Parameters

    • level: number

      Maximum group level to show.

    Returns void

containsFocus

  • containsFocus(): boolean
  • Checks whether this control contains the focused element.

    Returns boolean

deferUpdate

  • deferUpdate(fn: Function): void
  • Executes a function within a beginUpdate/endUpdate block.

    The control will not be updated until the function has been executed. This method ensures endUpdate is called even if the function throws an exception.

    Parameters

    • fn: Function

      Function to be executed.

    Returns void

dispose

  • dispose(): void
  • Disposes of the control by removing its association with the host element.

    Returns void

endUpdate

  • endUpdate(): void

finishEditing

  • finishEditing(cancel?: boolean): boolean
  • Commits any pending edits and exits edit mode.

    Parameters

    • Optional cancel: boolean

      Whether pending edits should be canceled or committed.

    Returns boolean

    True if the edit operation finished successfully.

focus

  • focus(force?: boolean): void
  • Overridden to set the focus to the grid without scrolling the whole grid into view.

    Parameters

    • Optional force: boolean

      Whether to perform the focus operation even if the grid already contains the focus.

    Returns void

getBindingColumn

  • Gets the Column object used to bind a data item to a grid cell.

    Parameters

    • p: GridPanel

      GridPanel that contains the cell.

    • r: number

      Index of the row that contains the cell.

    • c: number

      Index of the column that contains the cell.

    Returns Column

getCellBoundingRect

  • getCellBoundingRect(r: number, c: number | string, raw?: boolean): Rect
  • Gets a the bounds of a cell element in viewport coordinates.

    This method returns the bounds of cells in the cells panel (scrollable data cells). To get the bounds of cells in other panels, use the getCellBoundingRect method in the appropriate GridPanel object.

    The returned value is a Rect object which contains the position and dimensions of the cell in viewport coordinates. The viewport coordinates are the same used by the getBoundingClientRect method.

    Parameters

    • r: number

      Index of the row that contains the cell.

    • c: number | string

      Index, name, or binding of the column that contains the cell.

    • Optional raw: boolean

      Whether to return the rectangle in raw panel coordinates as opposed to viewport coordinates.

    Returns Rect

getCellData

  • getCellData(r: number, c: number | string, formatted: boolean): any
  • Gets the value stored in a cell in the scrollable area of the grid.

    Parameters

    • r: number

      Index of the row that contains the cell.

    • c: number | string

      Index, name, or binding of the column that contains the cell.

    • formatted: boolean

      Whether to format the value for display.

    Returns any

getClipString

  • getClipString(rng?: CellRange | null, options?: boolean | ClipStringOptions, colHeaders?: boolean, rowHeaders?: boolean): string
  • Gets the content of a CellRange as a string suitable for copying to the clipboard or exporting to CSV (comma-separated values) files.

    Hidden rows and columns are not included in the clip string.

    Invalid (with negative indexes) row or column ranges can be specified in CellRange, which indicates that data rows or columns are not included in the result. In conjunction with colHeaders or rowHeaders parameters set to true, this makes it possible to export colum or row headers only, without the corresponding data cells.

    Parameters

    • Optional rng: CellRange | null

      CellRange to copy. If omitted, the current selection is used.

    • Optional options: boolean | ClipStringOptions

      A boolean value that specifies the clip string should be a CSV string or a ClipStringOptions value that specifies options for the clip string.

    • Optional colHeaders: boolean

      Whether to include the column headers.

    • Optional rowHeaders: boolean

      Whether to include the row headers.

      To export the current selection, set the rng parameter to null. This will include not only the primary selection but also extended selections such as selected rows (in SelectionMode.ListBox mode) and multiple selected ranges (in SelectionMode.MultiRange mode).

      Note that multiple selected ranges are included only if all selected ranges refer to the same column range or row range.

    Returns string

getColumn

  • getColumn(name: string, header?: boolean): Column
  • Gets a column by name or by binding.

    The method searches the column by name. If a column with the given name is not found, it searches by binding. The searches are case-sensitive.

    Parameters

    • name: string

      The name or binding to find.

    • Optional header: boolean

      Whether to search column defined for header.

    Returns Column

    The column with the specified name or binding, or null if not found.

getColumnGroups

getMergedRange

  • Gets a CellRange that specifies the merged extent of a cell in a GridPanel.

    Parameters

    • p: GridPanel

      The GridPanel that contains the range.

    • r: number

      Index of the row that contains the cell.

    • c: number

      Index of the column that contains the cell.

    • Optional clip: boolean

      Whether to clip the merged range to the grid's current view range.

    Returns CellRange

    A CellRange that specifies the merged range, or null if the cell is not merged.

getSelectedState

getTemplate

  • getTemplate(): string
  • Gets the HTML template used to create instances of the control.

    This method traverses up the class hierarchy to find the nearest ancestor that specifies a control template. For example, if you specify a prototype for the ComboBox control, which does not specify a template, it will override the template defined by the DropDown base class (the nearest ancestor that does specify a template).

    Returns string

hasOwnProperty

  • hasOwnProperty(v: PropertyKey): boolean
  • Determines whether an object has a property with the specified name.

    Parameters

    • v: PropertyKey

      A property name.

    Returns boolean

hitTest

  • hitTest(pt: number | Point | MouseEvent | HTMLElement, y?: number | boolean): HitTestInfo
  • Gets a wijmo.grid.HitTestInfo object with information about a given point.

    For example:

    // hit test a point when the user clicks on the grid
    flex.hostElement.addEventListener('click', (e) => {
      let ht = flex.hitTest(e.pageX, e.pageY);
      console.log('you clicked a cell of type "' +
        wijmo.grid.CellType[ht.cellType] + '".');
    });

    Parameters

    • pt: number | Point | MouseEvent | HTMLElement

      Point to investigate, in page coordinates, or a MouseEvent object, or x coordinate of the point.

    • Optional y: number | boolean

      Y coordinate of the point in page coordinates (if the first parameter is a number).

    Returns HitTestInfo

    A wijmo.grid.HitTestInfo object with information about the point.

initialize

  • initialize(options: any): void
  • Initializes the control by copying the properties from a given object.

    This method allows you to initialize controls using plain data objects instead of setting the value of each property in code.

    For example:

    grid.initialize({
      itemsSource: myList,
      autoGenerateColumns: false,
      columns: [
        { binding: 'id', header: 'Code', width: 130 },
        { binding: 'name', header: 'Name', width: 60 }
      ]
    });
    
    // is equivalent to
    grid.itemsSource = myList;
    grid.autoGenerateColumns = false;
    // etc.

    The initialization data is type-checked as it is applied. If the initialization object contains unknown property names or invalid data types, this method will throw.

    Parameters

    • options: any

      Object that contains the initialization data.

    Returns void

invalidate

  • invalidate(fullUpdate?: boolean): void
  • Invalidates the control causing an asynchronous refresh.

    Parameters

    • Optional fullUpdate: boolean

      Whether to update the control layout as well as the content.

    Returns void

isPrototypeOf

  • isPrototypeOf(v: Object): boolean
  • Determines whether an object exists in another object's prototype chain.

    Parameters

    • v: Object

      Another object whose prototype chain is to be checked.

    Returns boolean

isRangeValid

  • Checks whether a given CellRange is valid for this grid's row and column collections.

    Parameters

    Returns boolean

onAutoSizedColumn

onAutoSizedRow

onAutoSizingColumn

onAutoSizingRow

onBeginningEdit

onCellEditEnded

onCellEditEnding

onCollapsedHeadersChanged

  • onCollapsedHeadersChanged(e?: EventArgs): void

onCollapsedHeadersChanging

onColumnGroupCollapsedChanged

onColumnGroupCollapsedChanging

onCopied

onCopying

onDeletedRow

onDeletingRow

onDraggedColumn

onDraggedRow

onDraggingColumn

onDraggingColumnOver

onDraggingRow

onDraggingRowOver

onFormatItem

onGotFocus

onGroupCollapsedChanged

onGroupCollapsedChanging

onInvalidInput

onItemsSourceChanged

onItemsSourceChanging

onLoadedRows

onLoadingRows

onLostFocus

onPasted

onPastedCell

onPasting

onPastingCell

onPinnedColumn

onPinningColumn

onPrepareCellForEdit

onRefreshed

onRefreshing

onResizedColumn

onResizedRow

onResizingColumn

onResizingRow

onRowAdded

onRowEditEnded

onRowEditEnding

onRowEditStarted

onRowEditStarting

onScrollPositionChanged

  • onScrollPositionChanged(e?: EventArgs): void

onSelectionChanged

onSortedColumn

onSortingColumn

onStarSizedColumns

onUpdatedLayout

onUpdatedView

onUpdatingLayout

onUpdatingView

propertyIsEnumerable

  • propertyIsEnumerable(v: PropertyKey): boolean
  • Determines whether a specified property is enumerable.

    Parameters

    • v: PropertyKey

      A property name.

    Returns boolean

refresh

  • refresh(fullUpdate?: boolean): void
  • Refreshes the grid display.

    Parameters

    • Optional fullUpdate: boolean

      Whether to update the grid layout and content, or just the content.

    Returns void

refreshCells

  • refreshCells(fullUpdate: boolean, recycle?: boolean, state?: boolean): void
  • Refreshes the grid display.

    Parameters

    • fullUpdate: boolean

      Whether to update the grid layout and content, or just the content.

    • Optional recycle: boolean

      Whether to recycle existing elements.

    • Optional state: boolean

      Whether to keep existing elements and update their state.

    Returns void

refreshRange

  • Refreshes the cells in a range, updating their content and styles.

    Unlike the refreshCells method, which updates all the cells, refreshRange allows you to specify which cells should be refreshed, which in some cases can improve performance.

    Parameters

    Returns void

removeEventListener

  • removeEventListener(target?: EventTarget, type?: string, fn?: any, capture?: boolean): number
  • Removes one or more event listeners attached to elements owned by this Control.

    Parameters

    • Optional target: EventTarget

      Target element for the event. If null, removes listeners attached to all targets.

    • Optional type: string

      String that specifies the event. If null, removes listeners attached to all events.

    • Optional fn: any

      Handler to remove. If null, removes all handlers.

    • Optional capture: boolean

      Whether the listener is capturing. If null, removes capturing and non-capturing listeners.

    Returns number

    The number of listeners removed.

scrollIntoView

  • scrollIntoView(r: number, c: number | string, refresh?: boolean): boolean
  • Scrolls the grid to bring a specific cell into view.

    Negative row and column indices are ignored, so if you call

    grid.scrollIntoView(200, -1);

    The grid will scroll vertically to show row 200, and will not scroll horizontally.

    Parameters

    • r: number

      Index of the row to scroll into view.

    • c: number | string

      Index, name, or binding of the column to scroll into view.

    • Optional refresh: boolean

      Optional parameter that determines whether the grid should refresh to show the new scroll position immediately.

    Returns boolean

    True if the grid scrolled.

select

  • select(rng: number | CellRange, show?: string | number | false | true): boolean
  • Selects a cell range and optionally scrolls it into view.

    The select method can be called by passing a CellRange and an optional boolean parameter that indicates whether the new selection should be scrolled into view. For example:

    // select cell 1,1 and scroll it into view
    grid.select(new CellRange(1, 1), true);
    
    // select range (1,1)-(2,4) and do not scroll it into view
    grid.select(new CellRange(1, 1, 2, 4), false);

    You can also call the select method passing the index or the row and column you want to select. In this case, the new selection always scrolls into view. For example:

    // select cell 1,1 and scroll it into view
    grid.select(1, 1);

    Parameters

    • rng: number | CellRange

      Range to select (or index of the row to select).

    • Optional show: string | number | false | true

      Whether to scroll the new selection into view (or index, name, or binding of the column to select).

    Returns boolean

    True if the new selection was applied.

selectAll

  • selectAll(): boolean
  • Selects all the cells on the grid.

    Returns boolean

setCellData

  • setCellData(r: number, c: string | number, value: any, coerce?: boolean, invalidate?: boolean): boolean
  • Sets the value of a cell in the scrollable area of the grid.

    Parameters

    • r: number

      Index of the row that contains the cell.

    • c: string | number

      Index, name, or binding of the column that contains the cell.

    • value: any

      Value to store in the cell.

    • Optional coerce: boolean

      Whether to change the value automatically to match the column's data type.

    • Optional invalidate: boolean

      Whether to invalidate the grid to show the change.

    Returns boolean

    True if the value was stored successfully, false otherwise.

setClipString

  • setClipString(text: string, rng?: CellRange): void
  • Parses a string into rows and columns and applies the content to a given range.

    Hidden rows and columns are skipped.

    Parameters

    • text: string

      Tab and newline delimited text to parse into the grid.

    • Optional rng: CellRange

      CellRange to copy. If omitted, the current selection is used.

    Returns void

startEditing

  • startEditing(fullEdit?: boolean, r?: number, c?: number | string, focus?: boolean, evt?: any): boolean
  • Starts editing a given cell.

    Editing in the FlexGrid is similar to editing in Excel: Pressing F2 or double-clicking a cell puts the grid in full-edit mode. In this mode, the cell editor remains active until the user presses Enter, Tab, or Escape, or until he moves the selection with the mouse. In full-edit mode, pressing the cursor keys does not cause the grid to exit edit mode.

    Typing text directly into a cell puts the grid in quick-edit mode. In this mode, the cell editor remains active until the user presses Enter, Tab, or Escape, or any arrow keys.

    Full-edit mode is normally used to make changes to existing values. Quick-edit mode is normally used for entering new data quickly.

    While editing, the user can toggle between full and quick modes by pressing the F2 key.

    Parameters

    • Optional fullEdit: boolean

      Whether to stay in edit mode when the user presses the cursor keys. Defaults to true.

    • Optional r: number

      Index of the row to be edited. Defaults to the currently selected row.

    • Optional c: number | string

      Index, name, or binding of the column to be edited. Defaults to the currently selected column.

    • Optional focus: boolean

      Whether to give the editor the focus when editing starts. Defaults to true.

    • Optional evt: any

      Event that triggered this action (usually a keypress or keydown).

    Returns boolean

    True if the edit operation started successfully.

toLocaleString

  • toLocaleString(): string
  • Returns a date converted to a string using the current locale.

    Returns string

toString

  • toString(): string
  • Returns a string representation of an object.

    Returns string

toggleDropDownList

  • toggleDropDownList(): boolean
  • Toggles the visibility of the drop-down list box associated with the currently selected cell.

    The drop-down list is created automatically based on the column's Column.dataMap property.

    This method can be used to show the drop-down list automatically when the cell enters edit mode, or when the user presses certain keys.

    For example, this code causes the grid to show the drop-down list whenever the grid enters edit mode:

    // show the drop-down list when the grid enters edit mode
    theGrid.beginningEdit.addHandler(() => {
      theGrid.toggleDropDownList();
    });

    This code causes the grid to show the drop-down list when the grid enters edit mode after the user presses the space bar:

    // show the drop-down list when the user presses the space bar
    theGrid.hostElement.addEventListener('keydown', (e) => {
      if (e.keyCode == 32) {
        e.preventDefault();
        theGrid.toggleDropDownList();
      }
    }, true);

    Returns boolean

valueOf

  • valueOf(): Object
  • Returns the primitive value of the specified object.

    Returns Object

Static disposeAll

  • disposeAll(e?: HTMLElement): void
  • Disposes of all Wijmo controls contained in an HTML element.

    Parameters

    • Optional e: HTMLElement

      Container element.

    Returns void

Static getControl

  • getControl(element: any): Control
  • Gets the control that is hosted in a given DOM element.

    Parameters

    • element: any

      The DOM element that hosts the control, or a CSS selector for the host element (e.g. '#theCtrl').

    Returns Control

Static invalidateAll

  • invalidateAll(e?: HTMLElement): void
  • Invalidates all Wijmo controls contained in an HTML element.

    Use this method when your application has dynamic panels that change the control's visibility or dimensions. For example, splitters, accordions, and tab controls usually change the visibility of its content elements. In this case, failing to notify the controls contained in the element may cause them to stop working properly.

    If this happens, you must handle the appropriate event in the dynamic container and call the Control.invalidateAll method so the contained Wijmo controls will update their layout information properly.

    Parameters

    • Optional e: HTMLElement

      Container element. If set to null, all Wijmo controls on the page will be invalidated.

    Returns void

Static refreshAll

  • refreshAll(e?: HTMLElement): void
  • Refreshes all Wijmo controls contained in an HTML element.

    This method is similar to invalidateAll, except the controls are updated immediately rather than after an interval.

    Parameters

    • Optional e: HTMLElement

      Container element. If set to null, all Wijmo controls on the page will be invalidated.

    Returns void

Events

autoSizedColumn

autoSizedColumn: Event<FlexGrid, CellRangeEventArgs>

Occurs after the user auto-sizes a column by double-clicking the right edge of a column header cell.

autoSizedRow

Occurs after the user auto-sizes a row by double-clicking the bottom edge of a row header cell.

autoSizingColumn

autoSizingColumn: Event<FlexGrid, CellRangeEventArgs>

Occurs before the user auto-sizes a column by double-clicking the right edge of a column header cell.

autoSizingRow

Occurs before the user auto-sizes a row by double-clicking the bottom edge of a row header cell.

beginningEdit

Occurs before a cell enters edit mode.

The 'data' property of the handler parameters contains a reference to the DOM event that caused the grid to enter edit mode.

The event handler may cancel the edit operation.

cellEditEnded

Occurs when a cell edit has been committed or canceled.

cellEditEnding

Occurs when a cell edit is ending.

You can use this event to perform validation and prevent invalid edits. For example, the code below prevents users from entering values that do not contain the letter 'a'. The code demonstrates how you can obtain the old and new values before the edits are applied.

function cellEditEnding(flex, e) {

  // get old and new values
  let oldVal = flex.getCellData(e.row, e.col),
      newVal = flex.activeEditor.value;

  // cancel edits if newVal doesn't contain 'a'
  e.cancel = newVal.indexOf('a') < 0;
}

Setting the CellEditEndingEventArgs.cancel parameter to true causes the grid to discard the edited value and keep the cell's original value.

If you also set the CellEditEndingEventArgs.stayInEditMode parameter to true, the grid will remain in edit mode so the user can correct invalid entries before committing the edits.

collapsedHeadersChanged

collapsedHeadersChanged: Event<MultiRow, EventArgs>

Occurs after the value of the collapsedHeaders property has changed.

collapsedHeadersChanging

collapsedHeadersChanging: Event<MultiRow, CancelEventArgs>

Occurs after the value of the collapsedHeaders property changes.

columnGroupCollapsedChanged

columnGroupCollapsedChanged: Event<FlexGrid, CellRangeEventArgs>

Occurs after a column group has been expanded or collapsed.

The 'data' property of the handler parameters contains a reference to the ColumnGroup that is about to change.

columnGroupCollapsedChanging

columnGroupCollapsedChanging: Event<FlexGrid, CellRangeEventArgs>

Occurs when a column group is about to be expanded or collapsed.

The 'data' property of the handler parameters contains a reference to the ColumnGroup that is about to change.

copied

Occurs after the user has copied the selection content to the clipboard by pressing one of the clipboard shortcut keys (see the autoClipboard property).

copying

Occurs when the user is copying the selection content to the clipboard by pressing one of the clipboard shortcut keys (see the autoClipboard property).

The event handler may cancel the copy operation.

deletedRow

Occurs after the user has deleted a row by pressing the Delete key (see the allowDelete property).

deletingRow

Occurs when the user is deleting a selected row by pressing the Delete key (see the allowDelete property).

The event handler may cancel the row deletion.

draggedColumn

Occurs when the user finishes dragging a column.

draggedRow

Occurs when the user finishes dragging a row.

draggingColumn

Occurs when the user starts dragging a column.

draggingColumnOver

draggingColumnOver: Event<FlexGrid, CellRangeEventArgs>

Occurs as the user drags a column to a new position.

The handler may cancel the event to prevent users from dropping columns at certain positions. For example:

// remember column being dragged
flex.draggingColumn.addHandler((s, e) => {
    theColumn = s.columns[e.col].binding;
});

// prevent 'sales' column from being dragged to index 0
s.draggingColumnOver.addHandler((s, e) => {
    if (theColumn == 'sales' && e.col == 0) {
        e.cancel = true;
    }
});

draggingRow

Occurs when the user starts dragging a row.

draggingRowOver

draggingRowOver: Event<FlexGrid, CellRangeEventArgs>

Occurs as the user drags a row to a new position.

formatItem

Occurs when an element representing a cell has been created.

This event can be used to format cells for display. It is similar in purpose to the itemFormatter property, but has the advantage of allowing multiple independent handlers.

For example, this code removes the 'wj-wrap' class from cells in group rows:

flex.formatItem.addHandler((flex, e) => {
  if (flex.rows[e.row] instanceof GroupRow) {
    wijmo.removeClass(e.cell, 'wj-wrap');
  }
});

gotFocus

gotFocus: Event<Control, EventArgs>

Occurs when the control gets the focus.

groupCollapsedChanged

groupCollapsedChanged: Event<FlexGrid, CellRangeEventArgs>

Occurs after a group has been expanded or collapsed.

groupCollapsedChanging

groupCollapsedChanging: Event<FlexGrid, CellRangeEventArgs>

Occurs when a group is about to be expanded or collapsed.

invalidInput

invalidInput: Event<Control, CancelEventArgs>

Occurs when invalid input is detected.

Invalid input may occur when the user types or pastes a value that cannot be converted to the proper type, or a value that is outside the valid range.

If the event handler cancels the event, the control will retain the invalid content and the focus, so users can correct the error.

If the event is not canceled, the control will ignore the invalid input and will retain the original content.

itemsSourceChanged

itemsSourceChanged: Event<FlexGrid, EventArgs>

Occurs after the grid has been bound to a new items source.

itemsSourceChanging

itemsSourceChanging: Event<FlexGrid, CancelEventArgs>

Occurs before the grid is bound to a new items source.

loadedRows

loadedRows: Event<FlexGrid, EventArgs>

Occurs after the grid rows have been bound to items in the data source.

loadingRows

Occurs before the grid rows are bound to items in the data source.

lostFocus

lostFocus: Event<Control, EventArgs>

Occurs when the control loses the focus.

pasted

Occurs after the user has pasted content from the clipboard by pressing one of the clipboard shortcut keys (see the autoClipboard property).

pastedCell

Occurs after the user has pasted content from the clipboard into a cell (see the autoClipboard property).

The 'data' property of the handler parameters contains the cell's original value (before the new value was pasted).

pasting

Occurs when the user is pasting content from the clipboard by pressing one of the clipboard shortcut keys (see the autoClipboard property).

The 'data' property of the handler parameters contains a copy of the text being pasted into the grid.

The event handler may cancel the paste operation.

pastingCell

Occurs when the user is pasting content from the clipboard into a cell (see the autoClipboard property).

The 'data' property of the handler parameters contains the text being pasted into the cell.

The event handler may cancel the paste operation.

pinnedColumn

Occurs after one or more columns are pinned (or unpinned).

pinningColumn

Occurs before one or more columns are pinned (or unpinned).

prepareCellForEdit

prepareCellForEdit: Event<FlexGrid, CellRangeEventArgs>

Occurs when an editor cell is created and before it becomes active.

The event handler can access the editor element using the grid's activeEditor property.

refreshed

refreshed: Event<Control, EventArgs>

Occurs after the control has refreshed its contents.

refreshing

refreshing: Event<Control, EventArgs>

Occurs when the control is about to refresh its contents.

resizedColumn

Occurs when the user finishes resizing a column.

resizedRow

Occurs when the user finishes resizing rows.

resizingColumn

Occurs as columns are resized.

resizingRow

Occurs as rows are resized.

rowAdded

Occurs when the user creates a new item by editing the new row template (see the allowAddNew property).

The event handler may customize the content of the new item or cancel the new item creation.

rowEditEnded

Occurs when a row edit has been committed or canceled.

rowEditEnding

Occurs when a row edit is ending, before the changes are committed or canceled.

This event can be used in conjunction with the rowEditStarted event to implement deep-binding edit undos. For example:

// save deep bound values when editing starts
let itemData = {};
s.rowEditStarted.addHandler((s, e) => {
  let item = s.collectionView.currentEditItem;
  itemData = {};
  s.columns.forEach(function (col) {
    if (col.binding.indexOf('.') &gt; -1) { // deep binding
      let binding = new wijmo.Binding(col.binding);
      itemData[col.binding] = binding.getValue(item);
    }
  })
});

// restore deep bound values when edits are canceled
s.rowEditEnded.addHandler((s, e) => {
  if (e.cancel) { // edits were canceled by the user
    let item = s.collectionView.currentEditItem;
    for (let k in itemData) {
      let binding = new wijmo.Binding(k);
      binding.setValue(item, itemData[k]);
    }
  }
  itemData = {};
});

rowEditStarted

Occurs after a row enters edit mode.

rowEditStarting

rowEditStarting: Event<FlexGrid, CellRangeEventArgs>

Occurs before a row enters edit mode.

scrollPositionChanged

scrollPositionChanged: Event<FlexGrid, EventArgs>

Occurs after the control has scrolled.

selectionChanged

selectionChanged: Event<FlexGrid, CellRangeEventArgs>

Occurs after selection changes.

selectionChanging

selectionChanging: Event<FlexGrid, CellRangeEventArgs>

Occurs before selection changes.

sortedColumn

Occurs after the user applies a sort by clicking on a column header.

sortingColumn

Occurs before the user applies a sort by clicking on a column header.

The 'data' property of the handler parameters contains a reference to the DOM event that caused the sort.

The event handler may cancel the sort action.

starSizedColumns

starSizedColumns: Event<FlexGrid, EventArgs>

When one or more columns have been resized due to star-sizing.

updatedLayout

updatedLayout: Event<FlexGrid, EventArgs>

Occurs after the grid has updated its internal layout.

updatedView

updatedView: Event<FlexGrid, EventArgs>

Occurs when the grid finishes creating/updating the elements that make up the current view.

The grid updates the view in response to several actions, including:

  • Refreshing the grid or its data source,
  • Adding, removing, or changing rows or columns,
  • Resizing or scrolling the grid,
  • Changing the selection.

updatingLayout

updatingLayout: Event<FlexGrid, CancelEventArgs>

Occurs before the grid updates its internal layout.

updatingView

Occurs when the grid starts creating/updating the elements that make up the current view.