JSDoc: Class: Hypergrid

Constructor

new Hypergrid(containeropt, optionsopt)

The first parameter, container, is optional. If omitted, the options parameter is promoted to first position. (Note that the container can also be given in options.container.)

`options.canvasContextAttributes` object (see below)

The only currently meaningful property of this object is alpha:

var gridOptions = {
    canvasContextAttributes: { alpha: false }
};
var myGrid = new Hypergrid(gridOptions);

alpha is a boolean that indicates if the canvas contains an alpha channel. If set to false, the browser now knows that the backdrop is always opaque, which can speed up drawing of transparent content and images.

This option was added by request although testing failed to show any measurable performance benefit.

Use with caution. In particular, if the canvas is set to "opaque" ({alpha: false}), do not also specify a transparent or translucent color for grid.properties.backGround because content may then be drawn with corrupt anti-aliasing (at lest in Chrome v67).

Note that such an "opaque" canvas can still be made to appear translucent using the CSS opacity property — a different effect entirely.

Although this option has no apparent performance gains (in Chrome v63), it does permit the graphics context to use sub-pixel rendering for sharper text as viewed on LCD or LED screens, especially black text on white backgrounds, and especially when viewed on a high-pixel-density display such as an Apple retina display.

value	Canvas	Text	Sample
`{ alpha: true }`	transparent	regular anti-aliasing
`{ alpha: false }`	opaque	sub-pixel rendering

Parameters:

Name	Type	Attributes	Default	Description
`container`	string \| Element	<optional>		CSS selector or Element. If omitted, Hypergrid first looks for an empty element with an ID of `hypergrid`. If not found, it will create a new element. In either case, the container element has the class name `hypergrid-container` added to its class name list. Finally, if the there is more than one such element with that class name, the element's ID attribute is set to `hypergrid` + n where n is an ordinal one less than the number of such elements.
`options`	object	<optional>
`options.Behavior`	function	<optional>	behaviors.JSON	A grid behavior constructor (extended from `Behavior`).
`options.pipeline`	Array.<function()>	<optional>		A list function constructors to use for passing data through a series of transforms to occur on reindex call
`options.data`	function \| Array.<object>	<optional>		Passed to behavior constructor. May be: An array of congruent raw data objects A function returning same
`options.schema`	function \| Array.<menuItem>	<optional>	derivedSchema	Passed to behavior constructor. May be: A schema array A function returning a schema array. Called at filter reset time with behavior as context. Omit to generate a basic schema from `this.behavior.columns`.
`options.plugins`	pluginSpec \| Array.<pluginSpec>	<optional>
`options.subgrids`	Array.<subgridSpec>	<optional>
`options.state`	object	<optional>
`options.container`	string \| Element	<optional>		CSS selector or Element
`options.canvasContextAttributes`	object	<optional>		Passed to `HTMLCanvasElement.getContext`. Please see discussion above.
`options.localization`	string	<optional>	Hypergrid.localization
`options.localization.locale`	string \| Array.<string>	<optional>	Hypergrid.localization.locale	The default locale to use when an explicit `locale` is omitted from localizer constructor calls. Passed to Intl.NumberFomrat`and`Intl.DateFomrat`. See Locale identification and negotiation for more information.
`options.localization.numberOptions`	string	<optional>	Hypergrid.localization.numberOptions	Options passed to `Intl.NumberFormat` for creating the basic "number" localizer.
`options.localization.dateOptions`	string	<optional>	Hypergrid.localization.dateOptions	Options passed to `Intl.DateTimeFormat` for creating the basic "date" localizer.
`options.schema`	object	<optional>
`options.margin`	object	<optional>		Optional canvas "margins" applied to containing div as .left, .top, .right, .bottom. (Default values actually derive from 'grid' stylesheet's `.hypergrid-container` rule.)
`options.margin.top`	string	<optional>	'0px'
`options.margin.right`	string	<optional>	'0px'
`options.margin.bottom`	string	<optional>	'0px'
`options.margin.left`	string	<optional>	'0px'
`options.boundingRect`	object	<optional>		Optional grid container size & position. (Default values actually derive from 'grid' stylesheet's `.hypergrid-container > div:first-child` rule.)
`options.boundingRect.height`	string	<optional>	'500px'
`options.boundingRect.width`	string	<optional>	'auto'
`options.boundingRect.left`	string	<optional>	'auto'
`options.boundingRect.top`	string	<optional>	'auto'
`options.boundingRect.right`	string	<optional>	'auto'
`options.boundingRect.bottom`	string	<optional>	'auto'
`options.boundingRect.position`	string	<optional>	'relative'

Mixes In:

Members

(static) applyTheme

Apply global theme.

Apply props from the given theme object to the global theme object, the defaults layer at the bottom of the properties hierarchy.

(static) dataModels :object

Registry of data models.

Type:

object

See:

dataModels

(static) defaults :object

The defaults layer of the Hypergrid properties hierarchy.

Default values for all Hypergrid properties, including grid-level properties and column property defaults.

Properties are divided broadly into two categories:

Style (a.k.a. "lnf" for "look'n'feel") properties
All other properties.

Type:

object

(static) grids :Array.<Hypergrid>

List of grid instances.

Added in constructor; removed in terminate(). Used in themes.js.

Type:

Array.<Hypergrid>

(static) localization :object

Shared localization defaults for all grid instances.

These property values are overridden by those supplied in the Hypergrid constructor's options.localization.

Type:

object

Properties:

Name	Type	Attributes	Description
`locale`	string \| Array.<string>	<optional>	The default locale to use when an explicit `locale` is omitted from localizer constructor calls. Passed to Intl.NumberFormat`and`Intl.DateFormat`. See {@ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation\|Locale identification and negotiation} for more information. Omitting will use the runtime's local language and region.
`numberOptions`	object	<optional>	Options passed to `Intl.NumberFormat` for creating the basic "number" localizer.
`dateOptions`	object	<optional>	Options passed to `Intl.DateFormat` for creating the basic "date" localizer.

(static) plugins :object

Hash of references to shared plug-ins.

Dictionary of shared (pre-installed) plug-ins. Used internally, primarily to avoid reinstallations. See examples for how to reference (albeit there is normally no need to reference plugins directly).

For the dictionary of instance plugins, see plugins (defined in the Hypergrid constructor).

To force reinstallation of a shared plugin delete it first:

delete Hypergrid.plugins.mySharedPlugin;

To force reinstallation of all shared plugins:

Hypergrid.plugins = {};

Type:

object

Example

var allSharedPlugins = Hypergrid.plugins;
var mySharedPlugin = Hypergrid.plugins.mySharedPlugin;

applyTheme

Apply a grid theme.

Apply props from the given theme object to the grid instance, the instance's myGrid.themeLayer layer in the properties hierarchy.

behavior :object

A null object behavior serves as a place holder.

Type:

object

cellEditor :CellEditor

The instance of the currently active cell editor. Will be null when not editing.

Type:

CellEditor

cellEditors :Registry

Private version of cell editors registry with a bound create method for use by getCellEditorAt.

Type:

Registry

cellRenderers :Registry

Type:

Registry

dragExtent :Point

The extent from the mousedown point during a drag operation.

Type:

Point

hoverCell :Point

The pixel location of the current hovered cell.

Type:

Point

To Do:

Need to detect hovering over bottom totals.

hScrollValue :number

A float value between 0.0 - 1.0 of the horizontal scroll position.

Type:

number

isWebkit :boolean

Cached result of webkit test.

Type:

boolean

mouseDown :Point

The pixel location of an initial mousedown click, either for editing a cell or for dragging a selection.

Type:

Point

plugins :object

Dictionary of named instance plug-ins.

See examples for how to reference (albeit there is normally no need to reference plugins directly).

For the dictionary of shared plugins, see plugins (a property of the constructor).

Type:

object

Example

var instancePlugins = myGrid.plugins;
var instancePlugins = this.plugins; // internal use
var myInstancePlugin = myGrid.plugins.myInstancePlugin;

properties :object

Object containing the properties of the grid.

Grid properties objects have the following structure:

User-configured properties and dynamic properties are in the "own" layer.
Extends from the theme object.
The theme object in turn extends from the defaults object.

Note: Any changes the application developer may wish to make to the defaults object should be made before reaching this point (i.e., prior to any grid instantiations).

Type:

object

renderOverridesCache :object

Non-null members represent additional things to render, after rendering the grid, such as the column being dragged.

Type:

object

sbHScroller :FinBar

The horizontal scroll bar model/controller.

Type:

FinBar

sbPrevHScrollValue :number

The previous value of sbHScrollValue.

Type:

number

sbPrevVScrollValue :number

The previous value of sbVScrollVal.

Type:

number

sbVScroller :FinBar

The verticl scroll bar model/controller.

Type:

FinBar

selectionModel :SelectionModel

The instance of the grid's selection model. May or may not contain any cell, row, and/or column selections.

Type:

SelectionModel

vScrollValue :number

A float value between 0.0 - 1.0 of the vertical scroll position.

Type:

number

Methods

(static) registerTheme(nameopt, themeopt)

Parameters:

Name Type Attributes Description

Name	Type	Attributes	Description
`name`	string	<optional>	A registry name for the new theme. May be omitted if the theme has an embedded name (in `theme.themeName`). If omitted, the 2nd parameter (`theme`) is promoted to first position.
`theme`	HypergridThemeObject	<optional>	To build a Hypergrid theme object from a loaded Polymer Theme CSS stylesheet: `var myTheme = require('fin-hypergrid-themes').buildTheme();`

name

string

A registry name for the new theme. May be omitted if the theme has an embedded name (in theme.themeName). If omitted, the 2nd parameter (theme) is promoted to first position.

theme

HypergridThemeObject

To build a Hypergrid theme object from a loaded Polymer Theme CSS stylesheet:

var myTheme = require('fin-hypergrid-themes').buildTheme();

(static) registerThemes(themeCollection)

App developers are free to add in additional themes, such as those in https://openfin.github.com/fin-hypergrid-themes/themes:

Hypergrind.registerThemes(require('fin-hypergrid-themes'));

Parameters:

Name	Type	Description
`themeCollection`	object

abortEditing() → {boolean}

Give cell editor opportunity to cancel (or something) instead of stop .

Returns:

One of:

false - Editing BUT could not abort.
true - Not editing OR was editing AND abort was successful.

Type: boolean

addEventListener(eventName, listener, internalopt)

Add an event listener to me.

Listeners added by this method should only be removed by grid.removeEventListener (or grid.removeAllEventListeners).

Parameters:

Name	Type	Attributes	Default	Description
`eventName`	string			The type of event we are interested in.
`listener`	function			The event handler.
`internal`	boolean	<optional>	false	Used by `grid.addInternalEventListener` (see).

addInternalEventListener(eventName, listener)

Add an internal event listener to me.

The new listener is flagged as "internal." Internal listeners are removed as usual by grid.removeEventListener. However, they are ignored by grid.removeAllEventListeners() (as called by reset). (But see grid.removeAllEventListeners(true).)

Listeners added by this method should only be removed by grid.removeEventListener (or grid.removeAllEventListeners(true)).

Parameters:

Name	Type	Description
`eventName`	string	The type of event we are interested in.
`listener`	function	The event handler.

addProperties(moreProperties)

Amend properties for this hypergrid only.

Parameters:

Name	Type	Description
`moreProperties`	object	A simple properties hash.

addState(state)

Add to the state object.

Parameters:

Name	Type	Description
`state`	object

autosizeColumn(columnOrIndex)

Autosize a column for best fit.

Parameters:

Name	Type	Description
`columnOrIndex`	Column \| number	The column or active column index.

beCursor(cursorName)

Switch the cursor for a grid instance.

Parameters:

Name	Type	Description
`cursorName`	string \| Array.<string>	A well know cursor name.

See:

cursor names

behaviorChanged()

I've been notified that the behavior has changed.

behaviorShapeChanged()

The dimensions of the grid data have changed. You've been notified.

behaviorStateChanged()

The dimensions of the grid data have changed. You've been notified.

cancelEditing() → {boolean}

Shut down the current cell editor without saving the edited val

Returns:

One of:

false - Editing BUT could not abort.
true - Not editing OR was editing AND abort was successful.

Type: boolean

cellClicked(event) → {boolean|undefined}

A click event occurred.

Determine the cell and delegate to the behavior (model).

Parameters:

Name	Type	Description
`event`	MouseEvent	The mouse event to interrogate.

Returns:

Changed. Specifically, one of:

undefined row had no drill-down control
true drill-down changed
false drill-down unchanged (was already in requested state)

Type: boolean | undefined

checkClipboardCopy(event)

Conditionally copy to clipboard.

If we have focus, copy our current selection data to the system clipboard.

Parameters:

Name	Type	Description
`event`	event	The copy system event.

checkColumnAutosizing()

The grid has just been rendered, make sure the column widths are optimal.

clearMostRecentColumnSelection()

Clear the most recent column selection.

clearMostRecentRowSelection()

Clear the most recent row selection.

clearMostRecentSelection()

Clear the most recent selection.

clearMouseDown()

Empty out the mouse down stack.

clearSelections()

Clear all the selections.

clearState()

columnHeaderClicked(event)

A fixed column has been clicked.

Delegates to the behavior.

Parameters:

Name	Type	Description
`event`	event	The event details.

delegateClick(mouseDetails)

Delegate click to the behavior (model).

Parameters:

Name	Type	Description
`mouseDetails`	mouseDetails	An enriched mouse event from fin-canvas.

delegateContextMenu(event)

Delegate MouseExit to the behavior (model).

Parameters:

Name	Type	Description
`event`	Event	The pertinent event.

delegateDoubleClick(mouseDetails)

We've been doubleclicked on. Delegate through the behavior (model).

Parameters:

Name	Type	Description
`mouseDetails`	mouseDetails	An enriched mouse event from fin-canvas.

delegateKeyDown(event)

Generate a function name and call it on self.

This should also be delegated through Behavior keeping the default implementation here though.

Parameters:

Name	Type	Description
`event`	event	The pertinent event.

delegateKeyUp(event)

Generate a function name and call it on self.

This should also be delegated through Behavior keeping the default implementation here though.

Parameters:

Name	Type	Description
`event`	event	The pertinent event.

delegateMouseDown(mouseDetails)

Delegate mousedown to the behavior (model).

Parameters:

Name	Type	Description
`mouseDetails`	mouseDetails	An enriched mouse event from fin-canvas.

delegateMouseDrag(mouseDetails)

Delegate mouseDrag to the behavior (model).

Parameters:

Name	Type	Description
`mouseDetails`	mouseDetails	An enriched mouse event from fin-canvas.

delegateMouseExit(event)

Delegate MouseExit to the behavior (model).

Parameters:

Name	Type	Description
`event`	Event	The pertinent event.

delegateMouseMove(mouseDetails)

Delegate MouseMove to the behavior (model).

Parameters:

Name	Type	Description
`mouseDetails`	mouseDetails	An enriched mouse event from fin-canvas.

delegateMouseUp(mouseDetails)

Delegate mouseup to the behavior (model).

Parameters:

Name	Type	Description
`mouseDetails`	mouseDetails	An enriched mouse event from fin-canvas.

delegateWheelMoved(event)

Delegate the wheel moved event to the behavior.

Parameters:

Name	Type	Description
`event`	Event	The pertinent event.

editAt(event) → {undefined|CellEditor}

Open the cell-editor for the cell at the given coordinates.

Parameters:

Name	Type	Description
`event`	CellEvent	Coordinates of "edit point" (gridCell.x, dataCell.y).

Returns:

The cellEditor determined from the cell's render properties, which may be modified by logic added by overriding getCellEditorAt.

Type: undefined | CellEditor

editorTakeFocus()

Request focus for our cell editor.

extendSelect(offsetX, offsetY)

Extend cell selection by offset.

Augment the most recent selection extent by (offsetX,offsetY) and scroll if necessary.

Parameters:

Name	Type	Description
`offsetX`	number	x coordinate to start at
`offsetY`	number	y coordinate to start at

fireAfterCellEdit(cell, oldValue, newValue) → {Renderer}

Parameters:

Name	Type	Description
`cell`	Point	The x,y coordinates.
`oldValue`	Object	The old value.
`newValue`	Object	The new value.

Returns:

sub-component

Type: Renderer

fireBeforeCellEdit(cell, value) → {boolean}

Synthesize and fire a fin-before-cell-edit event.

Parameters:

Name	Type	Description
`cell`	Point	The x,y coordinates.
`value`	Object	The current value.

Returns:

Proceed (don't cancel).

Type: boolean

fireScrollEvent(type, oldValue, newValue)

Synthesize and fire a scroll event.

Parameters:

Name	Type	Description
`type`	string	Should be either `fin-scroll-x` or `fin-scroll-y`.
`oldValue`	number	The old scroll value.
`newValue`	number	The new scroll value.

fireSyntheticClickEvent(cell, event)

Synthesize and fire a fin-cell-click event.

Parameters:

Name	Type	Description
`cell`	Point	The pixel location of the cell in which the click event occured.
`event`	MouseEvent	The system mouse event.

fireSyntheticColumnSortEvent(c, keys)

Parameters:

Name	Type	Description
`c`	number	grid column index.
`keys`	Array.<string>

fireSyntheticContextMenuEvent(event)

Synthesize and fire a fin-context-menu event

Parameters:

Name	Type	Description
`event`	keyEvent	The canvas event.

fireSyntheticDoubleClickEvent(event)

Synthesize and fire a fin-double-click event.

Parameters:

Name	Type	Description
`event`	MouseEvent	The system mouse event.

fireSyntheticGridRenderedEvent()

Synthesize and fire a rendered event.

fireSyntheticKeydownEvent(event)

Synthesize and fire a fin-keydown event.

Parameters:

Name	Type	Description
`event`	keyEvent	The canvas event.

fireSyntheticKeyupEvent(event)

Synthesize and fire a fin-keyup event.

Parameters:

Name	Type	Description
`event`	keyEvent	The canvas event.

fireSyntheticOnCellEnterEvent(cell, event)

Synthesize and fire a fin-cell-enter event

Parameters:

Name	Type	Description
`cell`	Point	The pixel location of the cell in which the click event occurred.
`event`	MouseEvent	The system mouse event.

fireSyntheticOnCellExitEvent(cell, event)

Synthesize and fire a fin-cell-exit event.

Parameters:

Name	Type	Description
`cell`	Point	The pixel location of the cell in which the click event occured.
`event`	MouseEvent	The system mouse event.

fireSyntheticOnColumnsChangedEvent()

Synthesize and fire a fin-column-drag-start event.

fireSyntheticRowSelectionChangedEvent()

Synthesize and fire a fin-row-selection-changed event.

getActiveColumnIndex(columnOrIndex) → {undefined|number}

The "grid index" of an active column given a "data index" (number), column name (string), or column object

Parameters:

Name	Type	Description
`columnOrIndex`	Column \| number

Returns:

The grid index of the column or undefined if column not in grid.

Type: undefined | number

getBounds() → {Rectangle}

Returns:

My bounds.

Type: Rectangle

getBoundsOfCell(gridCell) → {Rectangle}

Parameters:

Name	Type	Description
`gridCell`	Point	The pixel location of the mouse in physical grid coordinates.

Returns:

The pixel based bounds rectangle given a data cell point.

Type: Rectangle

getCanvas() → {Canvas}

Returns:

Our fin-canvas instance.

Type: Canvas

getCellEditorAt(cellEvent)

Get the cell editor.

Delegates to the behavior.

Parameters:

Name	Type	Description
`cellEvent`	Point	The grid cell coordinates.

Returns:

The cell editor at the given coordinates.

getColumnCount() → {number}

Number of visible columns.

Returns:

The number of columns.

Type: number

getColumnProperties(x) → {Object}

Parameters:

Name	Type	Description
`x`	index	Data x coordinate.

Returns:

The properties for a specific column.

Type: Object

getColumnWidth(columnIndex) → {number}

Parameters:

Name	Type	Description
`columnIndex`	number	The untranslated column index.

Returns:

The width of the given column.

Type: number

getController(type) → {null|undefined|*}

Get the given data controller.

Parameters:

Name	Type	Description
`type`	string

Returns:

The data controller or:

null means unknown data controller.
undefined means the data source handles this data controller but the data controller is undefined.

Type: null | undefined | *

getDataBounds() → {Rectangle}

Returns:

The pixel coordinates of just the center 'main" data area.

Type: Rectangle

getDragExtent() → {Point}

Returns:

The extent point of the current drag selection rectangle.

Type: Point

getFixedColumnCount() → {number}

Returns:

The number of fixed columns.

Type: number

getFixedColumnsWidth() → {number}

Returns:

The total width of all the fixed columns.

Type: number

getFixedRowCount()

Returns:

The number of fixed rows.

getFixedRowsHeight() → {number}

Returns:

The total fixed rows height

Type: number

getFooterRowCount() → {number}

Returns:

The total number of rows of all subgrids following the data subgrid.

Type: number

getGridCellFromLastSelection(useAllCellsopt) → {undefined|CellEvent}

Parameters:

Name	Type	Attributes	Description
`useAllCells`	boolean	<optional>	Search in all rows and columns instead of only rendered ones.

Returns:

Type: undefined | CellEvent

getGridCellFromMousePoint(mouse)

Answer which data cell is under a pixel value mouse point.

Parameters:

Name	Type	Description
`mouse`	mousePoint	The mouse point to interrogate.

getHeaderRowCount() → {number}

Returns:

The total number of rows of all subgrids preceding the data subgrid.

Type: number

getHiDPI() → {number}

Returns:

The HiDPI ratio.

Type: number

getHoverCell() → {Point}

Returns:

The cell over which the cursor is hovering.

Type: Point

getHScrollValue()

Returns:

The vertical scroll value.

getLogicalRowCount() → {number}

Returns:

The total number of logical rows of all subgrids.

Type: number

getMouseDown() → {object}

Returns:

The initial mouse position on a mouse down event for cell editing or a drag operation.

Type: object

getPrivateState() → {object}

See:

Memento pattern

Returns:

The state object for remembering our state.

Type: object

getRenderedData() → {Array.<object>}

Returns:

Objects with the values that were just rendered.

Type: Array.<object>

getRenderedHeight(rowIndex) → {number}

Parameters:

Name	Type	Description
`rowIndex`	number	The row index.

Returns:

The height of the given (recently rendered) row.

Type: number

getRenderedWidth(colIndex) → {number}

Parameters:

Name	Type	Description
`colIndex`	number	The column index.

Returns:

The width of the given (recently rendered) column.

Type: number

getRowCount() → {number}

Returns:

The number of rows.

Type: number

getRowHeight(rowIndex) → {number}

Parameters:

Name	Type	Description
`rowIndex`	number	The untranslated fixed column index.

Returns:

The height of the given row

Type: number

getRowSelection(hiddenColumnsopt) → {Object}

Parameters:

Name	Type	Attributes	Default	Description
`hiddenColumns`	boolean \| Array.<number> \| Array.<string>	<optional>	false	See `Hypergrid~getColumns`.

Returns:

Type: Object

getRowSelectionMatrix(hiddenColumnsopt) → {Array}

Parameters:

Name	Type	Attributes	Default	Description
`hiddenColumns`	boolean \| Array.<number> \| Array.<string>	<optional>	false	See `Hypergrid~getColumns`.

Returns:

Type: Array

getSelectedRow() → {object}

Returns:

An object that represents the currently selection row.

Type: object

getSelectionAsTSV() → {string}

Returns:

Tab separated value string from the selection and our data.

Type: string

getTheme() → {string|undefined|object}

Get currently active theme.

May return a theme name or a theme object.

Returns:

One of:

string: Theme name (registered theme).
object: Theme object (unregistered anonymous theme).
undefined: No theme (i.e., the default theme).

Type: string | undefined | object

getValue(x, y)

Get data value at given cell.

Parameters:

Name	Type	Description
`x`	number	The horizontal coordinate.
`y`	number	The vertical coordinate.

getVisibleColumns() → {number}

Note that "viewable columns" includes any partially viewable columns.

Returns:

The number of viewable columns.

Type: number

getVisibleColumnsCount() → {number}

Returns:

The number of columns that were just rendered

Type: number

getVisibleRows() → {number}

Note that "viewable rows" includes any partially viewable rows.

Returns:

The number of viewable rows.

Type: number

getVisibleRowsCount() → {number}

Returns:

The number of rows that were just rendered

Type: number

getVScrollValue() → {number}

Returns:

The vertical scroll value.

Type: number

gridRenderedNotification()

This function is a callback from the HypergridRenderer sub-component. It is called after each paint of the canvas.

hasFocus() → {boolean}

Returns:

We have focus.

Type: boolean

hasSelections() → {boolean}

Returns:

We have any selections.

Type: boolean

initRenderer()

Initialize the renderer sub-component.

initScrollbars()

Initialize the scroll bars.

installPlugins(pluginsopt)

Install plugins.

Plugin installation:

Each simple API is installed by calling it's install method with this as first arg + any additional args listed in the pluginSpec (when it is an array).
Each object API is installed by instantiating it's constructor with this as first arg + any additional args listed in the pluginSpec (when it is an array).

The resulting plain object or instantiated objects may be named by (in priority order):

if pluginSpec contains an array and first element is a string
object has a name property
object has a $$CLASS_NAME property

If named, a reference to each object is saved in this.plugins. If the plug-in is unnamed, no reference is kept.

There are two types of plugin installations:

Preinstalled plugins which are installed on the prototype. These are simple API plugins with a preinstall method called with the installPlugins calling context as the first argument. Preinstallations are automatically performed whenever a grid is instantiated (at the beginning of the constructor), by calling installPlugins with Hypergrid.prototype as the calling context.
Regular plugins which are installed on the instance. These are simple API plugins with an install method, as well as all object API plugins (constructors), called with the installPlugins calling context as the first argument. These installations are automatically performed whenever a grid is instantiated (at the end of the constructor), called with the new grid instance as the calling context.

The "installPlugins calling context" means either the grid instance or its prototype, depending on how this method is called.

Plugins may have both preinstall and install methods, in which case both will be called. However, note that in any case, install methods on object API plugins are ignored.

Parameters:

Name	Type	Attributes	Description
`plugins`	pluginSpec \| Array.<pluginSpec>	<optional>	The plugins to install. If omitted, the call is a no-op.

insureModelColIsVisible(colIndex, offsetX) → {boolean}

Scroll in the offsetX direction if column index colIndex is not visible.

Parameters:

Name	Type	Description
`colIndex`	number	The column index in question.
`offsetX`	number	The direction and magnitude to scroll if we need to.

Returns:

Column is visible.

Type: boolean

insureModelRowIsVisible(rowIndex, offsetX) → {boolean}

Scroll in the offsetY direction if column index c is not visible.

Parameters:

Name	Type	Description
`rowIndex`	number	The column index in question.
`offsetX`	number	The direction and magnitude to scroll if we need to.

Returns:

Row is visible.

Type: boolean

isCellSelectedInColumn(x) → {boolean}

Parameters:

Name	Type	Description
`x`	number	The column index.

Returns:

The given row is selected anywhere in the entire table.

Type: boolean

isCellSelectedInRow(y) → {boolean}

Parameters:

Name	Type	Description
`y`	number	The row index.

Returns:

The given column is selected anywhere in the entire table.

Type: boolean

isColumnVisible(columnIndex) → {boolean}

Parameters:

Name	Type	Description
`columnIndex`	number	The column index in question.

Returns:

The given column is fully visible.

Type: boolean

isDataRowVisible(r) → {boolean}

Parameters:

Name	Type	Description
`r`	number	The raw row index in question.

Returns:

The given row is fully visible.

Type: boolean

isDataVisible(c, rn) → {boolean}

Parameters:

Name	Type	Description
`c`	number	The column index in question.
`rn`	number	The grid row index in question.

Returns:

The given cell is fully is visible.

Type: boolean

isDraggingColumn() → {boolean}

Returns:

The user is currently dragging a column to reorder it.

Type: boolean

isGridRow(rn) → {boolean}

Parameters:

Name	Type	Description
`rn`	integerRowIndex \| sectionPoint

Returns:

Type: boolean

isScrollingNow() → {boolean}

Returns:

The scrollingNow field.

Type: boolean

isSelected(x, y) → {boolean}

Parameters:

Name	Type	Description
`x`	number	The horizontal coordinate.
`y`	number	The vertical coordinate.

Returns:

Given point is selected.

Type: boolean

moveSingleSelect(offsetX, offsetY)

Move cell selection by offset.

Replace the most recent selection with a single cell selection that is moved (offsetX,offsetY) from the previous selection extent.

Parameters:

Name	Type	Description
`offsetX`	number	x offset
`offsetY`	number	y offset

moveToSingleSelect(newX, newY)

Move cell selection by offset.

Replace the most recent selection with a single cell selection that is moved (offsetX,offsetY) from the previous selection extent.

Parameters:

Name	Type	Description
`newX`	number	x coordinate to start at
`newY`	number	y coordinate to start at

onEditorActivate() → {undefined|CellEditor}

An edit event has occurred. Activate the editor at the given coordinates.

Parameters:

Name	Type	Attributes	Description
`event.gridCell.x`	number		The horizontal coordinate.
`event.gridCell.y`	number		The vertical coordinate.
`event.primitiveEvent.type`	boolean	<optional>

Returns:

The editor object or undefined if no editor or editor already open.

Type: undefined | CellEditor

pageDown() → {number}

Scroll down one full page.

Returns:

Type: number

pageLeft()

Not yet implemented.

pageRight()

Not yet implemented.

pageUp() → {number}

Scroll up one full page.

Returns:

Type: number

paintNow()

Paint immediately in this microtask.

popMouseDown()

Remove the last item from the mouse down stack.

refreshProperties(properties)

Utility function to push out properties if we change them.

Parameters:

Name	Type	Description
`properties`	object	An object of various key value pairs.

To Do:

deprecate this in favor of making properties dynamic instead (for those that need to be)

removeAllEventListeners(internalopt)

Remove all event listeners.

Removes all event listeners added with grid.addEventListener except those added as "internal."

Parameters:

Name	Type	Attributes	Default	Description
`internal`	boolean	<optional>	false	Include internal listeners.

removeEventListener()

Remove an event listeners.

Removes the event listener with matching name and function that was added by grid.addEventListener.

NOTE: This method cannot remove event listeners added by other means.

repaintCell(x, y)

Repaint the given cell.

Parameters:

Name	Type	Description
`x`	x	The horizontal coordinate.
`y`	y	The vertical coordinate.

reset(optionsopt)

Clear out all state settings, data (rows), and schema (columns) of a grid instance.

Parameters:

Name Type Attributes Description

options

object

Properties

Name	Type	Attributes	Description
`subgrids`	object	<optional>	Consumed by `Behavior#reset`. If omitted, previously established subgrids list is reused.
`pipeline`	object	<optional>	Consumed by `dataModels.JSON#reset`. If omitted, previously established pipeline is reused.
`controllers`	object	<optional>	Consumed by `dataModels.JSON#reset`. If omitted, previously established controllers list is reused.

resized()

This is called by the fin-canvas when a resize occurs.

resolveProperty(key) → {string}

Parameters:

Name	Type	Description
`key`	string	A look-and-feel key.

Returns:

The value of a lnf property.

Type: string

restartPaintThread()

Restart the global repainting check flag thread.

restartResizeThread()

Restart the global resize check flag thread.

rowHeaderClicked(event)

A fixed row has been clicked.

Delegates to the behavior.

Parameters:

Name	Type	Description
`event`	event	The event details.

saveState(optionsopt)

Parameters:

Name Type Attributes Description

options

object

Properties

Name	Type	Attributes	Default	Description
`blacklist`	Array.<string>	<optional>		List of grid properties to exclude. Pertains to grid own properties only.
`compact`	boolean	<optional>		Run garbage collection first. The only property this current affects is `properties.calculators` (removes unused calculators).
`space`	number \| string	<optional>	'\t'	For no space, give `0`. (See JSON.stringify's `space` param other options.)
`headerify`	function	<optional>		If your headers were generated by a function (taking column name as a parameter), give a reference to that function here to avoid persisting headers that match the generated string.

To Do:

Only output values when they differ from defaults (deep compare needed).

scrollBy(offsetX, offsetY)

Scroll horizontal and vertically by the provided offsets.

Parameters:

Name	Type	Description
`offsetX`	number	Scroll in the x direction this much.
`offsetY`	number	Scroll in the y direction this much.

scrollHBy(offsetX)

Scroll horizontally by the provided offset.

Parameters:

Name	Type	Description
`offsetX`	number	Scroll in the x direction this much.

scrollVBy(offsetY)

Scroll vertically by the provided offset.

Parameters:

Name	Type	Description
`offsetY`	number	Scroll in the y direction this much.

select(ox, oy, ex, ex)

Select given region.

Parameters:

Name	Type	Description
`ox`	number	origin x
`oy`	number	origin y
`ex`	number	extent x
`ex`	number	extent y

selectionChanged()

Synthesize and dispatch a fin-selection-changed event.

setAttribute()

setBehavior(options)

Set the Behavior (model) object for this grid control.

This can be done dynamically.

Parameters:

Name Type Description

options

object

(See behaviors.JSON#setData.)

Properties

Name	Type	Attributes	Default	Description
`behavior`	Behavior	<optional>	behaviors.JSON	The behavior (model) can be either a constructor or an instance.
`data`	Array.<dataRowObject>	<optional>		(See `behaviors.JSON#setData`.)
`pipeline`	pipelineSchema	<optional>		New pipeline description.

setColumnProperties(x) → {Object}

Parameters:

Name	Type	Description
`x`	index	Data x coordinate.

Returns:

The properties for a specific column.

Type: Object

setColumnWidth(columnIndex, columnWidth)

Set the width of the given column.

Parameters:

Name	Type	Description
`columnIndex`	number	The untranslated column index.
`columnWidth`	number	The width in pixels.

setColumnWidth(columnOrIndex, width)

Parameters:

Name	Type	Description
`columnOrIndex`	Column \| number	The column or active column index.
`width`

setController(typeOrHashOfTypes, controlleropt) → {object}

Set the given data controller(s).

The data model needs to be able to accept the specified data controller type(s). If it fails to accept the specified data controller(s), an error condition is raised.

(To ignore the error, place the call in a try...catch. From there you could call notify to report it as a warning or an alert instead.)

Setting data controller(s) triggers a shape change.

Parameters:

Name Type Attributes Description

typeOrHashOfTypes

string

One of:

object - Hash of multiple data controllers, by type.
string - Type of the single data controller given in controller.

controller

dataControlInterface

Only required when 'hash' is a string; omit when hash is an object.

Returns:

Hash of all results, by type. Each member will be:
The given data controller for that type when defined.
A new "null" data controller, generated by the data model when the given data controller for that type was undefined.
undefined - The data controller was unknown to the data model.

Type: object

setData(dataRows, optionsopt)

Set the underlying datasource.

This can be done dynamically.

Parameters:

Name Type Attributes Description

dataRows

function | Array.<object>

May be:

An array of congruent raw data objects.
A function returning same.

options

object

(See behaviors.JSON#setData.)

setDragExtent(point)

Set the extent point of the current drag selection operation.

Parameters:

Name	Type	Description
`point`	Point

setFocusable()

Enable/disable if this component can receive the focus.

Parameters:

Type	Description
boolean	canReceiveFocus

setHoverCell(cellEvent)

Set the cell under the cursor.

Parameters:

Name	Type	Description
`cellEvent`	CellEvent

setHScrollValue(newValue)

Set the horizontal scroll value.

Parameters:

Name	Type	Description
`newValue`	number	The new scroll value.

setMouseDown(point)

Set the mouse point that initiated a cell edit or drag operation.

Parameters:

Name	Type	Description
`point`	Point

setPipeline(pipelinesopt, optionsopt)

Parameters:

Name	Type	Attributes	Description
`pipelines`	object	<optional>	New pipeline description. (See `dataModels.JSON#setPipeline`.)
`options`	object	<optional>	(See `dataModels.JSON#setPipeline`.)

setRowHeight(rowIndex, rowHeight)

Set the height of the given row.

Parameters:

Name	Type	Description
`rowIndex`	number	The row index.
`rowHeight`	number	The width in pixels.

setScrollingNow(isItNow)

Set for scrollingNow field.

Parameters:

Name	Type	Description
`isItNow`	boolean	The type of event we are interested in.

setState(state)

Set the state object to return to the given user configuration.

Parameters:

Name	Type	Description
`state`	object	A memento object.

See:

Memento pattern

setValue(x, y, value)

Set a data value of a given cell.

Parameters:

Name	Type	Description
`x`	number	The horizontal coordinate.
`y`	number	The vertical coordinate.
`value`	*	New cell value.

setVScrollbarValues()

Scroll values have changed, we've been notified.

setVScrollValue(newValue)

Set the vertical scroll value.

Parameters:

Name	Type	Description
`newValue`	number	The new scroll value.

stopEditing() → {boolean}

Shut down the current cell editor and save the edited value.

Returns:

One of:

false - Editing BUT could not abort.
true - Not editing OR was editing AND abort was successful.

Type: boolean

stopPaintThread()

Stop the global repainting flag thread.

stopResizeThread()

Stop the global resize check flag thread.

synchronizeScrollingBoundaries()

The data dimensions have changed, or our pixel boundaries have changed. Adjust the scrollbar properties as necessary.

takeFocus()

Request input focus.

toggleHiDPI()

Toggle HiDPI support.

HiDPI support is now on by default.

There used to be a bug in Chrome that caused severe slow down on bit blit of large images, so this HiDPI needed to be optional.

topLeftClicked(mouse)

The top left area has been clicked on

Delegates to the behavior.

Parameters:

Name	Type	Description
`mouse`	event	The event details.

uninstallPlugins(pluginNamesopt)

Uninstall all uninstallable plugins or just named plugins.

Calls uninstall on plugins that define such a method.

To uninstall "preinstalled" plugins, call with Hypergrid.prototype as context.

For convenience, the following args are passed to the call:

this - the plugin to be uninstalled
grid - the hypergrid object
key - name of the plugin to be uninstalled (i.e., key in plugins)
plugins - the plugins hash (a.k.a. grid.plugins)

Parameters:

Name	Type	Attributes	Description
`pluginNames`	string \| Array.<stirng>	<optional>	If provided, limit uninstall to the named plugin (string) or plugins (string[]).

updateCursor()

Update the cursor under the hover cell.

updateData(dataRows, optionsopt)

(See Hypergrid.prototype#setData.)

Binds the data and reshapes the grid (new column objects created)

Parameters:

Name Type Attributes Description

dataRows

function | Array.<object>

May be:

An array of congruent raw data objects.
A function returning same.

options object <optional>

updateSize()

Update the size of a grid instance.

useHiDPI() → {boolean}

Returns:

In HiDPI mode (has an attribute as such).

Type: boolean

windowOpen()

To intercept link clicks, override this method (either on the prototype to apply to all grid instances or on an instance to apply to a specific grid instance).

(inner) getColumns(hiddenColumnsopt) → {Array.<Column>}

Parameters:

Name Type Attributes Default Description

hiddenColumns

boolean | Array.<number> | Array.<string>

false

One of: false - Active column list true - All column list Array - Active column list with listed columns prefixed as needed (when not already in the list). Each item in the array may be either:

number - index into all column list
string - name of a column from the all column list

Returns:

Type: Array.<Column>

Class: Hypergrid

Constructor

new Hypergrid(containeropt, optionsopt)

options.canvasContextAttributes object (see below)

Parameters:

Members

(static) applyTheme

(static) dataModels :object

Type:

(static) defaults :object

Type:

(static) grids :Array.<Hypergrid>

Type:

(static) localization :object

Type:

Properties:

(static) plugins :object

Type:

Example

applyTheme

behavior :object

Type:

cellEditor :CellEditor

Type:

cellEditors :Registry

Type:

cellRenderers :Registry

Type:

dragExtent :Point

Type:

hoverCell :Point

Type:

hScrollValue :number

Type:

isWebkit :boolean

Type:

mouseDown :Point

Type:

plugins :object

Type:

Example

properties :object

Type:

renderOverridesCache :object

Type:

sbHScroller :FinBar

Type:

sbPrevHScrollValue :number

Type:

sbPrevVScrollValue :number

Type:

sbVScroller :FinBar

Type:

selectionModel :SelectionModel

Type:

vScrollValue :number

Type:

Methods

(static) registerTheme(nameopt, themeopt)

Parameters:

(static) registerThemes(themeCollection)

Parameters:

abortEditing() → {boolean}

Returns:

addEventListener(eventName, listener, internalopt)

Parameters:

addInternalEventListener(eventName, listener)

Parameters:

addProperties(moreProperties)

Parameters:

addState(state)

Parameters:

autosizeColumn(columnOrIndex)

Parameters:

beCursor(cursorName)

Parameters:

behaviorChanged()

behaviorShapeChanged()

behaviorStateChanged()

cancelEditing() → {boolean}

`options.canvasContextAttributes` object (see below)