JSDoc: Class: Behavior

(abstract) new Behavior(grid, optionsopt)

A controller for the data model.

This constructor (actually initialize) will be called upon instantiation of this class or of any class that extends from this class. See extend-me for more info.

Parameters:

Name	Type	Attributes	Default	Description
`grid`	Hypergrid
`options`	object	<optional>		(Passed to `reset`).
`options.dataModel`	DataModel	<optional>		Per `reset`.
`options.metadata`	object	<optional>		Per `reset`.
`options.DataModel`	function	<optional>	require('datasaur-local')	Per `reset`.
`options.data`	function \| Array.<object>	<optional>		Per `setData`.
`options.schema`	function \| Array.<menuItem>	<optional>		Per `setData`.
`options.subgrids`	Array.<subgridSpec>	<optional>	this.grid.properties.subgrids	Per `setData`.
`options.apply`	boolean	<optional>	true	Per `setData`.

Mixes In:

cellProperties.behaviorMixin
rowProperties.mixin
subgrids.mixin
dataModel.mixin

Members

applyAnalytics

Synonym of Behavior#reindex.

Deprecated:

cellPropertiesPrePaintNotification

this function is a hook and is called just before the painting of a cell occurs

subgrids :Array.<DataModel>

An array where each element represents a subgrid to be rendered in the hypergrid.

The list should always include at least one "data" subgrid, typically dataModel. It may also include zero or more other types of subgrids such as header, filter, and summary subgrids.

This object also sports a dictionary of subgrids in lookup property where each dictionary key is one of:

subgrid.name (for those that have a defined name, which is presumed to be unique)
subgrid.type (not unique, so if you plan on having multiple, name them!)
'data' for the (one and only) data subgrid when unnamed (note that data subgrids have no type)

The setter:

"Enlivens" any constructors (see createSubgrid for details).
Reconstructs the dictionary.
Calls shapeChanged().

Type:

Array.<DataModel>

Methods

addCellProperties(xOrCellEvent, yopt, properties, dataModelopt)

update the data at point x, y with value

Parameters:

Name	Type	Attributes	Default	Description
`xOrCellEvent`	CellEvent \| number			Data x coordinate.
`y`	number	<optional>		Grid row coordinate. Omit when `xOrCellEvent` is a `CellEvent`.
`properties`	Object			Hash of cell properties. When `y` omitted, this param promoted to 2nd arg.
`dataModel`	DataModel	<optional>	this.dataModel	For use only when `xOrCellEvent` is not a `CellEvent`: Provide a subgrid.

addRowProperties(yOrCellEvent, properties, dataModelopt)

Add all the properties in the given row properties object to the row properties.

Parameters:

Name	Type	Attributes	Default	Description
`yOrCellEvent`	number \| CellEvent			Data row index local to `dataModel`; or a `CellEvent` object.
`properties`	object \| undefined			An object containing new property values(s) to assign to the row properties. If `undefined`, this call is a no-op.
`dataModel`	DataModel	<optional>	this.dataModel	This is the subgrid. You only need to provide the subgrid when it is not the data subgrid and you did not give a `CellEvent` object in the first param (which already knows what subgrid it's in).

addState(properties, settingStateopt)

Parameters:

Name	Type	Attributes	Description
`properties`	Object		assignable grid properties
`settingState`	boolean	<optional>	Clear properties object before assignments.

changed()

I've been notified that the behavior has changed.

clearAllCellProperties(xopt)

Clears all cell properties of given column or of all columns.

Parameters:

Name	Type	Attributes	Description
`x`	number	<optional>	Omit for all columns.

clearObjectProperties(obj, exportPropsopt)

utility function to empty an object of its members

Parameters:

Name	Type	Attributes	Description
`obj`	object		the object to empty
`exportProps`	boolean	<optional>	`undefined` (omitted) - delete all properties falsy - delete only the export properties truthy - delete all properties except the export properties

clearState()

clear all table state

createSubgrid(spec) → {DataModel}

Maps a subgridSpec to a data model.

The spec may describe either an existing data model, or a constructor for a new data model.

Parameters:

Name	Type	Description
`spec`	subgridSpec

Returns:

A data model.

Type: DataModel

endDragColumnNotification()

a dnd column has just been dropped, we've been notified

getActiveColumnCount() → {number}

Number of visible columns.

Returns:

The total number of columns.

Type: number

getCellEditorAt(editPoint) → {cellEditor}

Parameters:

Name	Type	Description
`editPoint`	CellEvent	The grid cell coordinates.

Returns:

The cell editor for the cell at the given coordinates.

Type: cellEditor

getCellOwnProperties(xOrCellEvent, yopt, dataModelopt) → {undefined|object}

Get the cell's own properties object.

May be undefined because cells only have their own properties object when at lest one own property has been set.

Parameters:

Name	Type	Attributes	Default	Description
`xOrCellEvent`	CellEvent \| number			Data x coordinate.
`y`	number	<optional>		Grid row coordinate. Omit when `xOrCellEvent` is a `CellEvent`.
`dataModel`	DataModel	<optional>	this.dataModel	For use only when `xOrCellEvent` is not a `CellEvent`: Provide a subgrid.

Returns:

The "own" properties of the cell at x,y in the grid. If the cell does not own a properties object, returns undefined.

Type: undefined | object

getCellProperties(xOrCellEvent, yopt, dataModelopt) → {object}

Get the properties object for cell.

This is the cell's own properties object if found else the column object.

If you are seeking a single specific property, consider calling Behavior#getCellProperty instead.

Parameters:

Name	Type	Attributes	Default	Description
`xOrCellEvent`	CellEvent \| number			Data x coordinate.
`y`	number	<optional>		Grid row coordinate. Omit when `xOrCellEvent` is a `CellEvent`.
`dataModel`	DataModel	<optional>	this.dataModel	For use only when `xOrCellEvent` is not a `CellEvent`: Provide a subgrid.

Returns:

The properties of the cell at x,y in the grid.

Type: object

getCellProperty(xOrCellEvent, yopt, key, dataModelopt) → {object}

Return a specific cell property.

If there is no cell properties object, defers to column properties object.

Parameters:

Name	Type	Attributes	Default	Description
`xOrCellEvent`	CellEvent \| number			Data x coordinate.
`y`	number	<optional>		Grid row coordinate. Omit when `xOrCellEvent` is a `CellEvent`.
`key`	string			Name of property to get. When `y` omitted, this param promoted to 2nd arg.
`dataModel`	DataModel	<optional>	this.dataModel	For use only when `xOrCellEvent` is not a `CellEvent`: Provide a subgrid.

Returns:

The specified property for the cell at x,y in the grid.

Type: object

getColumnProperties(x) → {Object}

Parameters:

Name	Type	Description
`x`	index	Data x coordinate.

Returns:

The properties for a specific column.

Type: Object

getCursorAt(x, y) → {null}

Parameters:

Name	Type	Description
`x`	number	the x coordinate
`y`	number	the y coordinate

Returns:

the cursor at a specific x,y coordinate

Type: null

getData() → {Array.<dataRowObject>}

Retrieve all data rows from the data model.

Use with caution!

See:

getData

Returns:

Type: Array.<dataRowObject>

getFixedColumnCount() → {number}

Returns:

The number of fixed columns.

Type: number

getFixedColumnsMaxWidth() → {number}

This exists to support "floating" columns.

Returns:

The total width of the fixed columns area.

Type: number

getFixedColumnsWidth() → {number}

Returns:

The width of the fixed column area in the hypergrid.

Type: number

getFixedRowCount() → {number}

The number of "fixed rows."

The number of (non-scrollable) rows preceding the (scrollable) data subgrid.

Returns:

The sum of:

All rows of all subgrids preceding the data subgrid.
The first fixedRowCount rows of the data subgrid.

Type: number

getFixedRowsHeight() → {number}

The total height of the "fixed rows."

The total height of all (non-scrollable) rows preceding the (scrollable) data subgrid.

Returns:

The height in pixels of the fixed rows area of the hypergrid, the total height of:

All rows of all subgrids preceding the data subgrid.
The first fixedRowCount rows of the data subgrid.

Type: number

getHiddenColumnDescriptors() → {Array.<string>}

Returns:

All the currently hidden column header labels.

Type: Array.<string>

getRow(y) → {dataRowObject}

Retrieve a data row from the data model.

Parameters:

Name	Type	Description
`y`	number	the row index of interest

See:

getRow

Returns:

The data row object at y index.

Type: dataRowObject

getRowCount()

Gets the number of rows in the data subgrid.

See:

getRowCount

getRowHeight(yOrCellEvent, dataModelopt) → {number}

Parameters:

Name	Type	Attributes	Default	Description
`yOrCellEvent`	number			Data row index local to `dataModel`.
`dataModel`	DataModel	<optional>	this.dataModel

Returns:

The row height in pixels.

Type: number

getRowProperties(yOrCellEvent, prototypeopt, dataModelopt) → {object|undefined}

Parameters:

Name	Type	Attributes	Default	Description
`yOrCellEvent`	number \| CellEvent			Data row index local to `dataModel`; or a `CellEvent` object.
`prototype`	boolean	<optional>		Prototype for a new properties object when one does not already exist. If you don't define this and one does not already exist, this call will return `undefined`. Typical defined value is `null`, which creates a plain object with no prototype, or `Object.prototype` for a more "natural" object. (Required when 3rd param provided.)
`dataModel`	DataModel	<optional>	this.dataModel	This is the subgrid. You only need to provide the subgrid when it is not the data subgrid and you did not give a `CellEvent` object in the first param (which already knows what subgrid it's in).

Returns:

The row properties object which will be one of:

object - existing row properties object or new row properties object created from prototype; else
false - row found but no existing row properties object and prototype was not defined; else
undefined - no such row

Type: object | undefined

getValue(x, y, dataModelopt) → {*}

Get the value at cell (x,y).

When the last parameter (see dataModel below) is omitted, this method:

Is backwards compatible to the v2 version.
Does not default to the data subgrid — although you can provide it explicitly (this.behavior.dataModel).

Parameters:

Name	Type	Attributes	Description
`x`	number		The horizontal grid coordinate
`y`	number		The vertical coordinate.
`dataModel`	DataModel	<optional>	`x` and `y` are data cell coordinates in the given subgrid data model. If If omitted, `x` and `y` are grid cell coordinates.

Returns:

The raw cell data.

Type: *

handleMouseDown(grid, event)

delegate handling mouse down to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

handleMouseExit(grid, event)

delegate handling mouse exit to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

hideColumns(isActiveColumnIndexesopt, columnIndexes)

Hide active column(s).

Removes one or several columns from the "active" column list.

Parameters:

Name Type Attributes Default Description

Name	Type	Attributes	Default	Description
`isActiveColumnIndexes`	boolean	<optional>	false	Which list `columnIndexes` refers to: `true` - The active column list. `false` - The full column list (as per column schema array).
`columnIndexes`	number \| Array.<number>			Column index(es) into list as determined by `isActiveColumnIndexes`. One of: Scalar column index - Adds single column at insertion point. Array of column indexes - Adds multiple consecutive columns at insertion point. This required parameter is promoted left one arg position when `isActiveColumnIndexes` omitted.

isActiveColumnIndexes

boolean

false

Which list columnIndexes refers to:

true - The active column list.
false - The full column list (as per column schema array).

columnIndexes

number | Array.<number>

Column index(es) into list as determined by isActiveColumnIndexes. One of:

Scalar column index - Adds single column at insertion point.
Array of column indexes - Adds multiple consecutive columns at insertion point.

This required parameter is promoted left one arg position when isActiveColumnIndexes omitted.

highlightCellOnHover(isColumnHovered, isRowHovered) → {boolean}

Parameters:

Name	Type	Description
`isColumnHovered`	boolean	the column is hovered or not
`isRowHovered`	boolean	the row is hovered or not

Returns:

true if we should highlight on hover

Type: boolean

initializeFeatureChain(gridopt)

Create the feature chain - this is the chain of responsibility pattern.

Parameters:

Name	Type	Attributes	Description
`grid`	Hypergrid	<optional>	Unnecesary legacy parameter. May be omitted.

isColumnReorderable() → {boolean}

Returns:

Can re-order columns.

Type: boolean

onClick(grid, event)

delegate handling tap to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onContextMenu(grid, event)

delegate handling tap to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onDoubleClick(grid, event)

delegate handling double click to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onKeyDown(grid, event)

delegate handling key down to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onKeyUp(grid, event)

delegate handling key up to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onMouseDrag(grid, event)

delegate handling mouse drag to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onMouseMove(grid, event)

delegate handling mouse move to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onMouseUp(grid, event)

delegate handling mouse up to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

onTouchEnd(grid, event)

Delegate handling touchend to the feature chain of responsibility.

Parameters:

Name	Type	Description
`grid`	Hypergrid	The grid instance.
`event`	Object	The event details.

onTouchMove(grid, event)

Delegate handling touchmove to the feature chain of responsibility.

Parameters:

Name	Type	Description
`grid`	Hypergrid	The grid instance.
`event`	Object	The event details.

onTouchStart(grid, event)

Delegate handling touchstart to the feature chain of responsibility.

Parameters:

Name	Type	Description
`grid`	Hypergrid	The grid instance.
`event`	Object	The event details.

onWheelMoved(grid, event)

delegate handling wheel moved to the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid
`event`	Object	the event details

reindex()

Calls apply() on the data model.

See:

reindex

reset(optionsopt)

Reset the behavior.

Parameters:

Name	Type	Attributes	Description
`options`	object	<optional>	Same as constructor's `options`. Passed to `resetDataModel` and `setData` (both of which see).

resolveProperty(key) → {*}

fetch the value for a property key

Parameters:

Name	Type	Description
`key`	string	a property name

Returns:

The value of the given property.

Type: *

setCellProperties(xOrCellEvent, yopt, properties, dataModelopt)

update the data at point x, y with value

Parameters:

Name	Type	Attributes	Default	Description
`xOrCellEvent`	CellEvent \| number			Data x coordinate.
`y`	number	<optional>		Grid row coordinate. Omit when `xOrCellEvent` is a `CellEvent`.
`properties`	Object			Hash of cell properties. When `y` omitted, this param promoted to 2nd arg.
`dataModel`	DataModel	<optional>	this.dataModel	For use only when `xOrCellEvent` is not a `CellEvent`: Provide a subgrid.

setCellProperty(xOrCellEvent, yopt, key, value, dataModelopt)

Set a specific cell property.

If there is no cell properties object, defers to column properties object.

NOTE: For performance reasons, renderer's cell event objects cache their respective cell properties objects. This method accepts a CellEvent overload. Whenever possible, use the CellEvent from the renderer's cell event pool. Doing so will reset the cell properties object cache.

If you use some other CellEvent, the renderer's CellEvent properties cache will not be automatically reset until the whole cell event pool is reset on the next call to Renderer#computeCellBoundaries. If necessary, you can "manually" reset it by calling resetCellPropertiesCache(yourCellEvent) which searches the cell event pool for one with matching coordinates and resets the cache.

The raw coordinates overload calls the resetCellPropertiesCache(x, y) overload for you.

Parameters:

Name	Type	Attributes	Default	Description
`xOrCellEvent`	CellEvent \| number			`CellEvent` or data x coordinate.
`y`	number	<optional>		Grid row coordinate. Omit when `xOrCellEvent` is a `CellEvent`.
`key`	string			Name of property to get. When `y` omitted, this param promoted to 2nd arg.
`value`
`dataModel`	DataModel	<optional>	this.dataModel	For use only when `xOrCellEvent` is not a `CellEvent`: Provide a subgrid.

setColumnIndexes(columnIndexes, silentopt)

Rebuild the column order indexes

Parameters:

Name	Type	Attributes	Default	Description
`columnIndexes`	Array			list of column indexes
`silent`	Boolean	<optional>	false	whether to trigger column changed event

setColumnProperties(x) → {Object}

Parameters:

Name	Type	Description
`x`	index	Data x coordinate.

Returns:

The properties for a specific column.

Type: Object

setCursor(grid)

delegate setting the cursor up the feature chain of responsibility

Parameters:

Name	Type	Description
`grid`	Hypergrid

setData(dataRowsopt, optionsopt)

Set grid data.

Fails silently if dataRows and options.data are both undefined.

Parameters:

Name	Type	Attributes	Default	Description
`dataRows`	function \| Array.<object>	<optional>	options.data	Array of uniform data row objects or function returning same.
`options`	object	<optional>		(Promoted to first argument position when `dataRows` omitted.)
`options.data`	function \| Array.<object>	<optional>		The data when `dataRows` undefined.
`options.schema`	function \| Array.<menuItem>	<optional>		May be: A schema array A function returning same. Called at filter reset time with behavior as context. Omit to allow the data model to generate a basic schema from its data.
`options.apply`	boolean	<optional>	true	Apply data transformations to the new data.

setFixedColumnCount(n)

set the number of fixed columns

Parameters:

Name	Type	Description
`n`	number	the integer count of how many columns to be fixed

setFixedRowCount(The) → {number}

Set the number of fixed rows, which includes (top to bottom order):

The header rows
1. The header labels row (optional)
2. The filter row (optional)
3. The top total rows (0 or more)
The non-scrolling rows (externally called "the fixed rows")

Parameters:

Name	Type	Description
`The`	number	number of rows.

Returns:

Sum of the above or 0 if none of the above are in use.

Type: number

setRowHeight(yOrCellEvent, height, dataModelopt)

set the pixel height of a specific row

Parameters:

Name	Type	Attributes	Default	Description
`yOrCellEvent`	number			Data row index local to dataModel.
`height`	number			pixel height
`dataModel`	DataModel	<optional>	this.dataModel

setRowProperties(yOrCellEvent, properties, dataModelopt)

Reset the row properties in its entirety to the given row properties object.

Parameters:

Name	Type	Attributes	Default	Description
`yOrCellEvent`	number \| CellEvent			Data row index local to `dataModel`; or a `CellEvent` object.
`properties`	object \| undefined			The new row properties object. If `undefined`, this call is a no-op.
`dataModel`	DataModel	<optional>	this.dataModel	This is the subgrid. You only need to provide the subgrid when it is not the data subgrid and you did not give a `CellEvent` object in the first param (which already knows what subgrid it's in).

setRowProperty(yOrCellEvent, key, value, dataModelopt)

Sets a single row property on a specific individual row.

Parameters:

Name	Type	Attributes	Default	Description
`yOrCellEvent`	number \| CellEvent			Data row index local to `dataModel`; or a `CellEvent` object.
`key`	string			The property name.
`value`				The new property value.
`dataModel`	DataModel	<optional>	this.dataModel	This is the subgrid. You only need to provide the subgrid when it is not the data subgrid and you did not give a `CellEvent` object in the first param (which already knows what subgrid it's in).

setScrollPositionX(x)

Column alignment of given grid column.

Quietly set the horizontal scroll position.

Parameters:

Name	Type	Description
`x`	number	The new position in pixels.

setScrollPositionY(y)

Quietly set the vertical scroll position.

Parameters:

Name	Type	Description
`y`	number	The new position in pixels.

setState(properties)

Restore this table to a previous state. See the memento pattern.

Parameters:

Name	Type	Description
`properties`	Object	assignable grid properties

setValue(x, y, value, dataModelopt)

Update the value at cell (x,y) with the given value.

When the last parameter (see dataModel below) is omitted, this method:

Is backwards compatible to the v2 version.
Does not default to the data subgrid — although you can provide it explicitly (this.behavior.dataModel).

Parameters:

Name	Type	Attributes	Description
`x`	number		The horizontal coordinate.
`y`	number		The vertical coordinate.
`value`	*		New cell data.
`dataModel`	DataModel	<optional>	`x` and `y` are data cell coordinates in the given subgrid data model. If If omitted, `x` and `y` are grid cell coordinates.

shapeChanged()

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

showColumns(isActiveColumnIndexesopt, columnIndexes, referenceIndexopt, allowDuplicateColumnsopt)

Show inactive column(s) or move active column(s).

Adds one or several columns to the "active" column list.

Parameters:

Name	Type	Attributes	Default	Description
`isActiveColumnIndexes`	boolean	<optional>	false	Which list `columnIndexes` refers to: `true` - The active column list. This can only move columns around within the active column list; it cannot add inactive columns (because it can only refer to columns in the active column list). `false` - The full column list (as per column schema array). This inserts columns from the "inactive" column list, moving columns that are already active.
`columnIndexes`	number \| Array.<number>			Column index(es) into list as determined by `isActiveColumnIndexes`. One of: Scalar column index - Adds single column at insertion point. Array of column indexes - Adds multiple consecutive columns at insertion point. This required parameter is promoted left one arg position when `isActiveColumnIndexes` omitted.
`referenceIndex`	number	<optional>	this.columns.length	Insertion point, i.e., the element to insert before. A negative values skips the reinsert. Default is to insert new columns at end of active column list. Promoted left one arg position when `isActiveColumnIndexes` omitted.
`allowDuplicateColumns`	boolean	<optional>	false	Unless true, already visible columns are removed first. Promoted left one arg position when `isActiveColumnIndexes` omitted + one position when `referenceIndex` omitted.

stateChanged()

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

swapColumns(src, tar)

swap src and tar columns

Parameters:

Name	Type	Description
`src`	number	column index
`tar`	number	column index

(inner) derefSubgridRef(ref) → {DataModel}

Resolves a subgrid constructor reference.

The ref is resolved to a data model constructor.

This:

{Behavior}

Parameters:

Name	Type	Description
`ref`	subgridConstructorRef

Returns:

A data model constructor.

Type: DataModel