Module: defaults

This module lists the properties that can be set on a Hypergrid along with their default values. Edit this file to override the defaults.

Members

(static) autoSelectColumns :boolean

Select cell's entire column.

When truthy, selecting a cell will also select the entire column it is in.

Type:
  • boolean

(static) autoSelectRows :boolean

Select cell's entire row.

When truthy, selecting a cell will also select the entire row it is in, subject to note #1 below.

Notes:

  1. Ineffectual unless checkboxOnlyRowSelections is set to false.
  2. To allow auto-selection of multiple rows, set singleRowSelectionMode to false.
Type:
  • boolean

(static) backgroundColor :string

Background color for data cells.

Type:
  • string
Default Value:
  • rgb(241, 241, 241)

(static) backgroundColor2 :cssColor

Type:
  • cssColor
Default Value:
  • rgb(201, 201, 201)

(static) backgroundSelectionColor :string

Background color for selected cell(s).

Type:
  • string
Default Value:
  • rgba(147, 185, 255, 0.625)

(static) boxSizing :string

Analogous to CSS box-sizing property:

  • 'content-box' (default starting in version 3)
    Grid and fixed rule lines are rendered between cells; cell rects are spread out to accommodate.
  • 'border-box' (default in version 2)
    Grid and fixed rule lines are rendered on inside right and bottom edges of each cell (except right-most and bottom-most visible cells); cell rects are contiguous.
Type:
  • string

(static) cellPadding :number

Padding to left and right of cell value.

NOTE: Right padding may not be visible if column is not sized wide enough.

See also iconPadding.

Type:
  • number
Default Value:
  • 5

(static) cellSelection :boolean

Clicking in a cell "selects" it; it is added to the select region and repainted with "cell selection" colors.

Type:
  • boolean
Default Value:
  • true

(static) centerIcon :string

Name of image to appear at right of cell.

Must be a key from images.

Used by SimpleCell cell renderer.

Type:
  • string
See:

(static) checkboxOnlyRowSelections :boolean

Retain row selections.

When falsy, row selections are cleared when selecting cells; when truthy, row selections are kept as is when selecting cells.

Type:
  • boolean
To Do:
  • Deprecate in favor of something simpler like `keepRowSelections`. (The current name is misleading and has caused some confusion among both developers and users. At the very least it should have been called `checkboxOnlyRowDeselections`.)

(static) collapseCellSelections :boolean

Collapse cell selection onto next row selection.

Type:
  • boolean

(static) color :string

Font color for data cells.

Type:
  • string
Default Value:
  • rgb(25, 25, 25)

(static) columnAutosizing :boolean

Whether to automatically expand column width to accommodate widest rendered value.

When truthy for a given column and user has not manually resized it, column will expand to accommodate widest rendered value.

What's actually happening is (props in the following refers to the column's properties):

  1. On each grid render, for all visible columns:
    1. The cell renderer reports back the width of each rendered cell contents.
    2. The largest value for each column is saved (in props.preferredWidth).
  2. At the conclusion of the grid render, the renderer calls grid.gridRenderedNotification, which calls grid.behavior.checkColumnAutosizing, which for all columns for which props.columnAutosizing is truthy, determines if the column needs to be widened subject to the following conditions:
    1. If user has not already manually set column width (props.columnAutosized is still falsy)
    2. If render width > current width (props.preferredWidths > props.width)
    3. If column's max autosizing width is defined and it's greater than render width (props.peferredWidths < props.columnAutosizingMax)
  3. If any column width has changed, re-shape the grid with the new column widths and re-render it. As this typically happens before the next monitor refresh, user only sees the final result.
Type:
  • boolean
Default Value:
  • true

(static) columnAutosizingMax :boolean

The widest the column will be auto-sized to.

For no limit, set this property to a falsy value such as undefined or 0.

Note this property only specifies a maximum column width for auto-sizing; it places no limit on manual resizing of column width.

Type:
  • boolean
Default Value:
  • 400

(static) columnClip :boolean|undefined

Set up a clipping region around each column before painting cells.

One of:

  • true - Clip column.
  • false - Do not clip column.
  • null - Clip iff last active column.

Clipping prevents text that overflows to the right of the cell from being rendered. If you can guarantee that none of your text will overflow, turn column clipping off for better performance. If not, you may still be able to get away without clipping. If the background color of the next column is opaque, you don't really need to clip, although text can leak out to the right of the last column. Clipping the last column only can help this but not solve it since the leaked text from (say) the column before the last column could stretch across the entire last column and leak out anyway. The solution to this is to clip the rendered string so at most only a partial character will overflow.

Type:
  • boolean | undefined
Default Value:
  • true

(static) columnGrabMargin :number

Column grab within this number of pixels from top of cell.

Type:
  • number
Default Value:
  • 5

(static) columnHeaderBackgroundColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(223, 227, 232)

(static) columnHeaderBackgroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgba(255, 220, 97, 0.45)

(static) columnHeaderColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(25, 25, 25)

(static) columnHeaderFont :cssFont

Type:
  • cssFont
Default Value:
  • 12px Tahoma, Geneva, sans-serif

(static) columnHeaderForegroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(80, 80, 80)

(static) columnHeaderForegroundSelectionFont :string

Font style for selected columns' headers.

Type:
  • string
Default Value:
  • bold 12px Tahoma, Geneva, sans-serif

(static) columnHeaderFormat :string

There is no standard format called "header"; unless defined, defaults to "string" (pass-thru formatter).

Type:
  • string
Default Value:
  • header

(static) columnHeaderHalign :string

Type:
  • string
Default Value:
  • center

(static) columnHeaderRenderer :string

Type:
  • string
Default Value:
  • SimpleCell

(static) columnSelection :boolean

Clicking in a column header (top row) "selects" the column; the entire column is added to the select region and repainted with "column selection" colors.

Type:
  • boolean
Default Value:
  • true

(static) columnsReorderable :boolean

Allow user to move columns .

Columns can be reordered through either of two interfaces:

  • Column Dragging feature
  • behavior.columns API
Type:
  • boolean
Default Value:
  • true

(static) defaultColumnWidth :number

This default column width is used when width property is undefined. (width is defined on column creation unless columnAutosizing has been set to false.)

Type:
  • number
Default Value:
  • 100

(static) defaultRowHeight :number

Type:
  • number
See:

(static) editable :boolean

Type:
  • boolean
Default Value:
  • true

(static) editOnDoubleClick :boolean

Edit cell on double-click rather than single-click.

Type:
  • boolean
Default Value:
  • true

(static) editOnKeydown :boolean

Grid-level property. When user presses a "printable" keyboard character or BACKSPACE or DELETE:

  1. Activate cell editor on current cell (i.e., origin of most recent selection).
  2. If cell editor is a text editor:
    1. Replace current value with the character the user typed; or
    2. Clear it on BACKSPACE, DELETE, or other invalid character (e.g. when user types a letter but the cell editor only accepts digits).

In invoked, user has the option to back out by pressing the ESCAPE key.

Type:
  • boolean
Default Value:
  • true

(static) editOnNextCell :boolean

Open cell editor when cell selected via keyboard navigation.

Keyboard navigation always includes:

  1. The four arrow keys -- but only when there is no active text cell editor open
  2. Additional keys mapped to the four directs in module:defaults.navKeyMap

Generally set at the grid level. If set at the column (or cell) level, note that the property pertains to the cell navigated to, not the cell navigated away from.

Type:
  • boolean

(static) editor :string

Name of a cell editor from the cellEditors API..

Not editable if named editor is does not exist.

Type:
  • string
Default Value:
  • undefined
Tutorials:

(static) enableContinuousRepaint :boolean

Re-render grid at maximum speed.

In this mode:

  • The "dirty" flag, set by calling grid.repaint(), is ignored.
  • grid.getCanvas().currentFPS is a measure of the number times the grid is being re-rendered each second.
  • The Hypergrid renderer gobbles up CPU time even when the grid appears idle (the very scenario repaint() is designed to avoid). For this reason, we emphatically advise against shipping applications using this mode.
Type:
  • boolean

(static) feedbackCount :number|undefined

Validation failure feedback.

Validation occurs on stopEditing, normally called on commit (TAB, ENTER, or any other keys listed in navKeyMap).

On successful validation, the value is saved back to the data source and the editor is closed.

On validation failure, feedback is shown to the user in the form of an "error effect" possibly followed by an "end effect" containing a detailed explanation.

The error effect to use is named in feedbackEffect.

The value of this property is the number of times to show the "error effect" on validation failure before showing the detailed explanation.

feedback may be set to one of:

  • undefined - Do not show the error effect or the alert. Just discard the value and close the editor (as if ESC had been typed).
  • 0 - Just shows the error feedback effect (see the errorEffect property).
  • 1 - Shows the error feedback effect followed by the detailed explanation.
  • 2 or more:
    1. Shows the error feedback effect
    2. On every feedback tries, shows the detailed explanation.
Type:
  • number | undefined
Default Value:
  • 3

(static) feedbackEffect :Object|string

Type:
  • Object | string
Default Value:
  • shaker
See:

(static) filterable :boolean

Type:
  • boolean
Default Value:
  • true

(static) filterBackgroundColor :cssColor

Type:
  • cssColor
Default Value:
  • white

(static) filterBackgroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(255, 220, 97)

(static) filterColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(25, 25, 25)

(static) filterEditor :string

Type:
  • string
Default Value:
  • TextField

(static) filterFont :cssFont

Type:
  • cssFont
Default Value:
  • 12px Tahoma, Geneva, sans-serif

(static) filterForegroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(25, 25, 25)

(static) filterHalign :string

Type:
  • string
Default Value:
  • center

(static) filterRenderer :string

Type:
  • string
Default Value:
  • SimpleCell

(static) fixedColumnCount :number

Type:
  • number

(static) fixedLinesHColor :cssColor

Define this property to style rule lines between fixed & scolling rows differently from module:defaults.gridLinesHColor.

Type:
  • cssColor
Default Value:
  • rgb(164,164,164)

(static) fixedLinesHEdge :number

Define this property to render just the edges of the lines between non-scrollable rows & scrollable rows, creating a double-line effect. The value is the thickness of the edges. Typical definition would be 1 in tandem with setting fixedLinesHWidth to 3.

Type:
  • number

(static) fixedLinesHWidth :number

Define this property to style rule lines between non-scrollable rows and scrollable rows differently from gridLinesHWidth. Undefine it to show normal grid line in that position.

Type:
  • number
Default Value:
  • 2

(static) fixedLinesVColor :cssColor

Define this property to style rule lines between fixed & scolling columns differently from module:defaults.gridLinesVColor.

Type:
  • cssColor
Default Value:
  • rgb(164,164,164)

(static) fixedLinesVEdge :number

Define this property to render just the edges of the lines between fixed & scrolling columns, creating a double-line effect. The value is the thickness of the edges. Typical definition would be 1 in tandem with setting fixedLinesVWidth to 3.

Type:
  • number
See:

(static) fixedLinesVWidth :number

Define this property to style rule lines between non-scrollable columns and scrollable columns differently from gridLinesVWidth. Undefine it to show normal grid line in that position.

Type:
  • number
Default Value:
  • 2

(static) fixedRowCount :number

Type:
  • number

(static) font :cssFont

The font for data cells.

Type:
  • cssFont
Default Value:
  • 13px Tahoma, Geneva, sans-serif

(static) foregroundSelectionColor :string

Font color for selected cell(s).

Type:
  • string
Default Value:
  • rgb(0, 0, 128)

(static) foregroundSelectionFont :string

Font style for selected cell(s).

Type:
  • string
Default Value:
  • bold 13px Tahoma, Geneva, sans-serif

(static) format :string

Name of a formatter for cell text.

Unknown formatter falls back to the string formatter (simple conversion to string with + '').

Type:
  • string
Default Value:
  • undefined
Tutorials:

(static) gridBorder :boolean|string

Set canvas's CSS border to this string as well as:

  • gridBorderLeft
  • gridBorderRight
  • gridBorderTop
  • gridBorderBottom.

If set to: true: uses current lineWidth and lineColor false: uses null

Caveat: The use of grid.canvas.canvas.style.boxSizing = 'border-box' is not recommended due to the fact that the canvas is squashed slightly to accommodate the border resulting in blurred text.

Type:
  • boolean | string

(static) gridBorderBottom :boolean

Set canvas's bottom CSS border to this string.

If set to:

Type:
  • boolean

(static) gridBorderLeft :boolean|string

Set canvas's left CSS border to this string.

If set to:

Type:
  • boolean | string

(static) gridBorderRight :boolean

Set canvas's right CSS border to this string.

If set to:

Type:
  • boolean

(static) gridBorderTop :boolean

Set canvas's top CSS border to this string.

If set to:

Type:
  • boolean

(static) gridLinesColumnHeader :boolean

When module:defaults.gridLinesV is truthy, determines if lines render in the column headers area.

Type:
  • boolean
Default Value:
  • true

(static) gridLinesH :boolean

Enable rendering of horizontal grid lines.

Type:
  • boolean
Default Value:
  • true

(static) gridLinesHColor :string

Color of horizontal grid lines.

Type:
  • string
Default Value:
  • rgb(199, 199, 199)
See:

(static) gridLinesHWidth :number

Thickness of horizontal grid lines (pixels).

Type:
  • number
Default Value:
  • 1
See:

(static) gridLinesRowHeader :boolean

When module:defaults.gridLinesH is truthy, determines if lines render in the row headers area.

Type:
  • boolean
Default Value:
  • true

(static) gridLinesUserDataArea :boolean

When module:defaults.gridLinesV or module:defaults.gridLinesH are truthy, determines if lines render in the user data area.

Type:
  • boolean
Default Value:
  • true

(static) gridLinesV :boolean

Enable rendering of vertical grid lines.

Type:
  • boolean
Default Value:
  • true

(static) gridLinesVColor :string

Color of vertical grid lines.

Type:
  • string
Default Value:
  • rgb(199, 199, 199)
See:

(static) gridLinesVWidth :number

Thickness of vertical grid lines (pixels).

Type:
  • number
Default Value:
  • 1
See:

(static) gridRenderer :string

Name of grid renderer. Renderer must have been registered.

Type:
  • string
Default Value:
  • by-columns-and-rows
See:
  • Renderer#registerGridRenderer.

(static) halign :string

Horizontal alignment of each cell as interpreted by it's cell renderer.

Type:
  • string
Default Value:
  • center

(static) headerify :string

The name of a transformer function defined in require('synonomous/transformers').

If the named headerify function is defined, whenever the schema array changes, it is applied each element (column schema) for each column that does not already have an explicitly defined header property.

When this property does not name a defined headerify function, undefined column headers default to their column names.

Type:
  • string
Default Value:
  • toTitle
See:
  • lib/headerifiers.js

(static) headerTextWrapping :boolean

Whether text in header cells is wrapped.

For performance reasons, text in data cells is not wrapped. (This is a function of the supplied SimpleCell renderer. Override with a custom renderer if you must have wrapped text in data cells.)

Type:
  • boolean

(static) hoverCellHighlight :hoverColors

On mouse hover, whether to repaint the cell background and how.

Type:
  • hoverColors
Default Value:
  • '{ enabled: true, background: rgba(160, 160, 40, 0.30) }'

(static) hoverColumnHighlight :hoverColors

On mouse hover, whether to repaint the column background and how.

Type:
  • hoverColors
Default Value:
  • '{ enabled: true, background: rgba(60, 60, 15, 0.15) }'

(static) hoverRowHighlight :hoverColors

On mouse hover, whether to repaint the row background and how.

Type:
  • hoverColors
Default Value:
  • '{ enabled: true, background: rgba(100, 100, 25, 0.15) }'

(static) hScrollbarClassPrefix :string

Type:
  • string

(static) iconPadding :number

Padding to left and right of cell icons.

Overrides cellPadding:

  • Left icon + iconPadding overrides left cellPddingg.
  • Right icon + iconPadding overrides right cellPddingg.
Type:
  • number
Default Value:
  • 3
See:

(static) leftIcon :string

Name of image to appear at right of cell.

Must be a key from images.

Used by SimpleCell cell renderer.

Type:
  • string
See:

Display cell value as a link (with underline).

One of:

  • boolean - No action occurs on click; you would need to attach a 'fin-click' listener to the hypergrid object.
    • true - Displays the cell as a link.
    • falsy - Displays the cell normally.
  • string - The URL is decorated (see {}) and then opened in a separate window/tab. See also linkTarget.
    • '*' - Use the cell value as the URL, ready for decorating (see {CellClick#openLink|openLink)).
    • field name - Fetches the string from the named field in the same row, assumed to be a URL ready for decorating. (May contain only alphanumerics and underscore; no spaces or other punctuation.)
    • otherwise Assumed to contains a URL ready for decorating.
  • function - A function to execute to get the URL ready for decorating. The function is passed a single parameter, cellEvent, from which you can get the field name, dataRow, etc.
  • Array - An array to "apply" to window.open in its entirety. The first element is interpreted as above for string or function.

In the case of string or Array, the link is further unpacked by openLink and then sent to grid.windowOpen.

Type:
  • boolean | string | Array
Example
// following affect upper-left data cell:
grid.behavior.setCellProperty(0, 0, 'https://nytimes.com'); // absolute address using specific protocol
grid.behavior.setCellProperty(0, 0, '//nytimes.com'); // absolute address using current protocol
grid.behavior.setCellProperty(0, 0, '/page2.com'); // relative to current site
grid.behavior.setCellProperty(0, 0, 'mypage.com'); // relative to current page
grid.behavior.setCellProperty(0, 0, 'mypage.com?id=%value'); // cell's value will replace %value
grid.behavior.setCellProperty(0, 0, ['//www.newyorker.com', 'ny', undefined, true]) // target='ny', replace=true

(static) linkColor :string

Color for link.

Falsy means defer to foreground color.

Type:
  • string
Default Value:
  • blue

(static) linkColorOnHover :boolean

Color link on hover only.

Type:
  • boolean

(static) linkOnHover :boolean

Underline link on hover only.

Type:
  • boolean

(static) linkTarget

The window (or tab) in which to open the link.

The default ('_blank'`) will open a new window for every click.

To have the first click open a new window and all subsequent clicks reuse that same window, set this to an arbitrary string.

Otherwise, specific columns or cells can be set to open their links in their own window by setting the appropriate column's or cell's linkTarget property.

Default Value:
  • _blank

(static) linkVisitedColor :string

Color for visited link.

Falsy means defer to foreground color.

Type:
  • string
Default Value:
  • purple

(static) maximumColumnWidth :number

Maximum column width. When defined, column width is clamped to this value by setWidth). Ignored when falsy. Respects resizeColumnInPlace but may cause user confusion when user can't make column narrower due to next column having reached its maximum.

Type:
  • number

(static) maxSortColumns :number

This is a standard property definition for sort plug-in use. It is not referenced in core.

The maximum number of columns that may participate in a multi-column sort (via ctrl-click headers).

Type:
  • number
Default Value:
  • 3

(static) minimumColumnWidth :number

Minimum column width. Adjust this value for different fonts/sizes or exotic cell renderers. Must be defined. The default (5) is enough room for an ellipsis with default font size.

Type:
  • number
Default Value:
  • 5

(static) multipleSelections :boolean

Allow multiple cell region selections.

Type:
  • boolean

(static) navKeyMap :object|undefined

Mappings for cell navigation keys.

Cell navigation is handled in the CellSelection "feature". This property gives you control over which key presses the built-in mechanism will respond to.

(If this built-in cell selection logic is insufficient for your needs, you can also listen for the various "fin-key" events and carry out more complex operations in your listeners.)

The key press names used here are defined in Canvas.js. Note that all key presses actually have two names, a normal name and a shifted name. The latter name is used when shift is depressed.

The built-in nav key presses are as follows:

  • UP (up-arrow key) - Replace all selections with a single cell, one row up from the last selection.
  • DOWN (down-arrow key) - Replace all selections with a single cell, one row down from the last selection.
  • LEFT (left-arrow key) - Replace all selections with a single cell, one column to the left of the last selection.
  • RIGHT (right-arrow key) - Replace all selections with a single cell, one column to the right of the last selection.
  • UPSHIFT (shift + up-arrow) - Extend the last selection up one row.
  • DOWNSHIFT (shift + down-arrow) - Extend the last selection down one row.
  • LEFTSHIFT (shift + left-arrow) - Extend the last selection left one column.
  • RIGHTSHIFT (shift + right-arrow) - Extend the last selection right one column.

To alter these or add other mappings see the examples below.

A note regarding the other meta keys (ctrl, option, and command): Although these meta keys can be detected, they do not modify the key names as shift does. This is because they are more for system use and generally (with the possibly exception fo ctrl) should not be depended upon, as system functions will take priority and your app will never see these key presses.

A special accommodation has been made to the editOnKeydown property:

  • If editOnKeydown truthy AND mapped character is an actual (non-white-space) character, as opposed to (say) tab or return, then navigation requires the ctrl key to distinguish between nav and data.
  • If editOnKeydown falsy, the ctrl key is ignored.

So if (say) a is mapped to LEFT as in the last example below, if editOnKeydown is ON, then a (without ctrl) would start editing the cell but ctrl + a would move the selection one column to the left.

Type:
  • object | undefined
Default Value:
  • {"RETURN":"DOWN","RETURNSHIFT":"UP","TAB":"RIGHT","TABSHIFT":"LEFT"}
Examples
// To void the above build-ins:
navKeyMap: {
    UP: undefined,
    UPSHIFT: undefined,
    DOWN: undefined,
    ...
}
// To map alternative nav key presses to RETURN and TAB (default mapping):
navKeyMap: {
    RETURN: 'DOWN',
    RETURNSHIFT: 'UP',
    TAB: 'RIGHT',
    TABSHIFT: 'LEFT'
}
// To map alternative nav key presses to a/w/d/s and extend select to A/W/D/S:
navKeyMap: {
    a: 'LEFT', A: 'LEFTSHIFT',
    w: 'UP', W: 'UPSHIFT',
    s: 'DOWN', S: 'DOWNSHIFT',
    d: 'RIGHT', D: 'RIGHTSHIFT'
}

(static) noDataMessage :string

The default message to display in front of the canvas when there are no grid rows. Format is HTML.

Type:
  • string

(static) readOnly :boolean

Type:
  • boolean

(static) renderer :string

Name of cell renderer from the cellRenderers API.

Type:
  • string
Default Value:
  • SimpleCell

(static) renderFalsy :boolean

Set to true to render 0 and false. Otherwise these value appear as blank cells.

Type:
  • boolean

(static) repaintImmediately :boolean

Normally multiple calls to grid.repaint(), grid.reindex(), grid.behaviorShapeChanged(), and/or grid.behaviorStateChanged() defer their actions until just before the next scheduled render. For debugging purposes, set repaintImmediately to truthy to carry out these actions immediately while leaving the paint loop running for when you resume execution. Alternatively, call grid.canvas.stopPaintLoop(). Caveat: Both these modes are for debugging purposes only and may not render the grid perfectly for all interactions.

Type:
  • boolean

(static) repaintIntervalRate :number

Type:
  • number
Default Value:
  • 60

(static) resizeColumnInPlace :boolean

Resizing a column through the UI (by clicking and dragging on the column's right border in the column header row) normally affects the width of the whole grid.

Set this new property to truthy to inversely resize the next column. In other words, if user expands (say) the third column, then the fourth column will contract — and vice versa — without therefore affecting the width of the grid.

This is a column property and may be set for selected columns (myColumn.properties.resizeColumnInPlace) or for all columns by setting it at the grid level (myGrid.properties.resizeColumnInPlace).

Note that the implementation of this property does not allow expanding a column beyond the width it can borrow from the next column. The last column, however, is unconstrained, and resizing of course affects the total grid width.

Type:
  • boolean

(static) restoreColumnSelections :boolean

Restore column selections across data transformations (reindex calls).

The restoration is based on the column names.

Type:
  • boolean
Default Value:
  • true

(static) restoreRowSelections :boolean

Restore row selections across data transformations (reindex calls).

The restoration is based on the underlying data row indexes.

Type:
  • boolean
Default Value:
  • true

(static) rightIcon :string

Name of image to appear at right of cell.

Must be a key from images.

Used by SimpleCell cell renderer.

Type:
  • string
See:

(static) rowHeaderBackgroundColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(223, 227, 232)

(static) rowHeaderBackgroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgba(255, 220, 97, 0.45)

(static) rowHeaderCheckboxes :boolean

Type:
  • boolean
Default Value:
  • true
See:

(static) rowHeaderColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(25, 25, 25)

(static) rowHeaderFont :cssFont

Type:
  • cssFont
Default Value:
  • 12px Tahoma, Geneva, sans-serif

(static) rowHeaderForegroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(80, 80, 80)

(static) rowHeaderForegroundSelectionFont :string

Font style for selected rows' headers.

Type:
  • string
Default Value:
  • bold 12px Tahoma, Geneva, sans-serif

(static) rowHeaderNumbers :boolean

Type:
  • boolean
Default Value:
  • true
See:

(static) rowNumberAutosizing :boolean

Whether to automatically expand row number column width to accommodate widest rendered row number

grid.properties.rowNumberAutosizing is the backing store for grid.behavior.columns[-2].columnAutosizing. Supports row number column styling via the rowNumber_______ grid state properties.

Type:
  • boolean
Default Value:
  • true

(static) rowResize :boolean

Type:
  • boolean

(static) rowSelection :boolean

Clicking in a row header (leftmost column) "selects" the row; the entire row is added to the select region and repainted with "row selection" colors.

Type:
  • boolean
Default Value:
  • true

(static) rowStripes :undefined|Array.<object>

Repeating pattern of property overrides for grid rows.

Notes:

  • "Grid row" refers to data rows.
  • Row index modulo is applied when dereferencing this array. In other words, this array represents a repeating pattern of properties to be applied to the data rows.
  • For no row properties, specify a falsy value in place of the array.
  • Do not specify an empty array (will throw an error).
  • Each element of the array may be either:
    • An object containing property overrides to be applied to every cell of the row; or
    • A falsy value signifying that there are no row properties for this specific row.
  • Caveat: Row properties use Object.assign() to copy properties and therefore are not as performant as column properties which use prototype chain.
  • Object.assign() is a polyfill in older versions of Chrome (<45) and in all Internet Explorer (through 11).
Type:
  • undefined | Array.<object>

(static) scrollbarHoverOff :string

Type:
  • string
Default Value:
  • hidden

(static) scrollbarHoverOver :string

Type:
  • string
Default Value:
  • visible

(static) scrollingEnabled :boolean

Type:
  • boolean
Default Value:
  • true

(static) selectionRegionOutlineColor :string

Stroke color for last selection overlay.

Type:
  • string
Default Value:
  • rgb(69, 69, 69)

(static) selectionRegionOverlayColor :cssColor

Fill color for last selection overlay.

The color should be translucent (or transparent). Note that "Partial" grid renderers (such as the paintCellsAsNeeded renderer) do not draw overlay because it just gets darker and darker for non-updated cells.

Type:
  • cssColor
Default Value:
  • transparent

(static) showFilterRow :boolean

Type:
  • boolean

(static) showHeaderRow :boolean

Type:
  • boolean
Default Value:
  • true

(static) showTreeColumn :boolean

Type:
  • boolean
Default Value:
  • true

(static) singleRowSelectionMode :boolean

Type:
  • boolean
Default Value:
  • true

(static) sortOnDoubleClick :boolean

Sort column on double-click rather than single-click.

Used by:

  • feature/ColumnSorting.js to decide which event to respond to (if any, see unsortabe).
  • feature/ColumnSelection.js to decide whether or not to wait for double-click.
Type:
  • boolean
Default Value:
  • true

(static) sortOnHiddenColumns :boolean

This is a standard property definition for sort plug-in use. It is not referenced in core.

Column(s) participating and subsequently hidden still affect sort.

Type:
  • boolean
Default Value:
  • true

(static) strikeThrough :boolean

Display cell font with strike-through line drawn over it.

Type:
  • boolean

(static) subgrids :Array.<subgridSpec>

List of subgrids by

Restrict usage here to strings (naming data models) or arrays consisting of such a string + constructor arguments. That is, avoid subgridSpec's function and object overloads and subgridConstructorRef function overload.

Type:
Default Value:
  • "[ 'HeaderSubgrid', 'data' ]"

(static) themeName :string

The global theme name.

Type:
  • string
Default Value:
  • default

(static) treeColumnAutosizing :boolean

Whether to automatically expand row number column width to accommodate widest rendered group label.

grid.properties.treeColumnAutosizing is the backing store for grid.behavior.columns[-1].columnAutosizing. Supports tree column styling via the rowColumn_______ grid state properties.

Type:
  • boolean
Default Value:
  • true

(static) treeColumnAutosizingMax :boolean

The widest the tree column will be auto-sized to.

grid.properties.treeColumnAutosizingMax is the store for grid.behavior.columns[-1].columnAutosizingMax. Supports tree column styling via the rowColumn_______ grid state properties.

Type:
  • boolean
Default Value:
  • 400

(static) treeHeaderBackgroundColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(223, 227, 232)

(static) treeHeaderBackgroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgba(255, 220, 97, 0.45)

(static) treeHeaderColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(25, 25, 25)

(static) treeHeaderFont :cssFont

Type:
  • cssFont
Default Value:
  • 12px Tahoma, Geneva, sans-serif

(static) treeHeaderForegroundSelectionColor :cssColor

Type:
  • cssColor
Default Value:
  • rgb(80, 80, 80)

(static) treeHeaderForegroundSelectionFont :string

Font style for selected rows' headers.

Type:
  • string
Default Value:
  • bold 12px Tahoma, Geneva, sans-serif

(static) treeRenderer :string

Type:
  • string
Default Value:
  • SimpleCell

(static) truncateTextWithEllipsis :boolean|null|undefined

How to truncate text.

A "quaternary" value, one of:

  • undefined - Text is not truncated.
  • true (default) - Truncate sufficient characters to fit ellipsis if possible. Most acceptable option that avoids need for clipping.
  • false - Truncate before last partially visible character. Visibly annoying; semantically jarring.
  • null - Truncate after partially visible character. Less visibly annoying; still semantically confusing. Best solution when combined with either column clipping or painting over with next column's background.
Type:
  • boolean | null | undefined
Default Value:
  • true

(static) unsortable :boolean

Ignore sort handling in feature/ColumnSorting.js. Useful for excluding some columns but not other from participating in sorting.

Type:
  • boolean

(static) useHiDPI :boolean

Type:
  • boolean
Default Value:
  • true

(static) voffset :number

Type:
  • number

(static) vScrollbarClassPrefix :string

Type:
  • string

(static) wheelHFactor :number

Multiplier for horizontal mouse wheel movement, applied to values of WheelEvent#deltaX (received by the horizontal scrollbar's listener).

Caveat

Wheel granularity depends on the OS, the input device, and possibly the browser. Any setting you choose will work differently in different environments. If you don't know the user's environment, it is probably best to give users control of this setting so they can fine tune it themselves.

Default values

This particular default value of 0.01 seems to work well on the MacBook Pro trackpad. It's slower than it was, which will greatly improve the scrolling experience since column scrolling often occurred inadvertently when the intent was to scroll in the veritcal direction only.

Be aware however that the trackpad scrolling speed can be adjusted by the Mac user at the OS level (System Preferences -> Accessibility -> Mouse & Trackpad -> Trackpad Options… -> Scrolling speed).

Hint: You can tell if the user is using a trackpad by listening for any deltaX (since a simple mouse wheel is deltaY only); and what OS by checking user agent.

Type:
  • number
Default Value:
  • 0.01

(static) wheelVFactor :number

Multiplier for vertical mouse wheel movement, applied to values of WheelEvent#deltaY (received by the vertical scrollbar's listener).

Caveat

Wheel granularity depends on the OS, the input device, and possibly the browser. Any setting you choose will work differently in different environments. If you don't know the user's environment, it is probably best to give users control of this setting so they can fine tune it themselves.

Default values

This particular default value of 0.05 is a compromise. It seems to work well on the MacBook Pro trackpad; and works acceptably (though differently) with a mouse wheel on both Mac OS and Windows.

Be aware however that the trackpad scrolling speed can be adjusted by the Mac user at the OS level (System Preferences -> Accessibility -> Mouse & Trackpad -> Trackpad Options… -> Scrolling speed). Mouse wheel scrolling speed is also adjustable ( yada yada -> Mouse Options… -> Scrolling speed; or on Windows search for "Change mouse wheel settings" in the Start menu).

This default setting of 0.05 feels good on trackpad (2-finger drag). It's much slower than it was, but the way it was before was way to coarse and fast, scrolling hundreds of rows in a flash.

With this setting, a mouse connected to a Mac, the wheel requires 5 click-stops to scroll 1 row; the same mouse connected to Windows scrolls 5 rows per click-stop. (However, I may have changed the default settings on my machines; not sure.)

On Windows, the original multiplier setting (i.e., 1.0) scrolled 100 grid rows on a single mouse wheel click-stop; the new default (0.05) scrolls 5 rows per click-stop. It stands to reason therefore that a setting of 0.01 will scroll 1:1 (1 row per 1 click-stop).

 #### Hint
 You can tell if the user is using a trackpad by listening for any deltaX (since a simple mouse wheel is deltaY only); and what OS by checking user agent.
Type:
  • number
Default Value:
  • 0.05

Methods

(static) exec(vf)

Execute value if "calculator" (function) or if column has calculator.

This function is referenced here so:

  1. It will be available to the cell renderers
  2. Its context will naturally be the config object
Parameters:
Name Type Description
vf

Value or function.
Default Value:

(static) getTextHeight(font) → {*}

Parameters:
Name Type Description
font
Returns:
Type
*

(static) getTextWidth(gc, string) → {nubmer}

Accumulates width of string in pixels, character by character, by chaching character widths and reusing those values when previously cached.

NOTE: There is a minor measuring error when taking the sum of the pixel widths of individual characters that make up a string vs. the pixel width of the string taken as a whole. This is possibly due to kerning or rounding. The error is typically about 0.1%.

Parameters:
Name Type Description
gc CanvasRenderingContext2D
string string

Text to measure.
Returns:

Width of string in pixels.

Type
nubmer

(static) mappedNavKey(keyChar, ctrlKeyopt) → {undefined|string}

Returns only values of keyChar that, when run through navKeyMap, pass the navKey logic test.

Parameters:
Name Type Attributes Default Description
keyChar string

A value from Canvas's charMap, to be remapped through navKeyMap.
ctrlKey boolean <optional>
 false

The CTRL key was down.
Returns:

undefined means not a nav key; otherwise returns keyChar.

Type
undefined | string

(static) navKey(keyChar, ctrlKeyopt) → {undefined|string}

Returns any value of keyChar that passes the following logic test:

  1. If a non-printable, white-space character, then nav key.
  2. If not (i.e., a normal character), can still be a nav key if not editing on key down.
  3. If not, can still be a nav key if CTRL key is down.

Note: Callers are typcially only interested in the following values of keyChar and will ignore all others:

  • 'LEFT' and 'LEFTSHIFT'
  • 'RIGHT' and 'RIGHTSHIFT'
  • 'UP' and 'UPSHIFT'
  • 'DOWN' and 'DOWNSHIFT'
Parameters:
Name Type Attributes Default Description
keyChar string

A value from Canvas's charMap.
ctrlKey boolean <optional>
 false

The CTRL key was down.
Returns:

undefined means not a nav key; otherwise returns keyChar.

Type
undefined | string

(static) reapplyCellProperties()

Reapply cell properties after getCell.

Type Definitions

cssColor

Type:
  • string
See:

cssFont

Type:
  • string
See:

hoverColors

Properties:
Name Type Attributes Default Description
enable boolean <optional>
 false

false means not hilite on hover
backgroundColor cssColor

cell, row, or column background color. Alpha channel will be respected and if given will be painted over the cells predetermined color.
header.backgroundColor cssColor <optional>
 backgroundColor

for columns and rows, this is the background color of the column or row "handle" (header rows or columns, respectively). (Not used for cells.)