handsontable
Version:
Handsontable is a JavaScript Data Grid available for React, Angular and Vue.
1,359 lines (1,358 loc) • 122 kB
JavaScript
/* eslint-disable jsdoc/require-description-complete-sentence */
/**
* @description
*
* ::: only-for javascript
* Handsontable events are the common interface that function in 2 ways: as __callbacks__ and as __hooks__.
* :::
*
* ::: only-for react
* This page lists all the **Handsontable hooks** – callbacks that let you react before or after an action occurs.
*
* Read more on the [Events and hooks](@/guides/getting-started/events-and-hooks/events-and-hooks.md) page.
* :::
*
* @example
*
* ::: only-for javascript
* ```js
* // using events as callbacks
* ...
* const hot1 = new Handsontable(document.getElementById('example1'), {
* afterChange: function(changes, source) {
* $.ajax({
* url: "save.php',
* data: change
* });
* }
* });
* ...
* ```
* :::
*
* ::: only-for react
* ```jsx
* <HotTable
* afterChange={(changes, source) => {
* fetch('save.php', {
* method: 'POST',
* headers: {
* 'Accept': 'application/json',
* 'Content-Type': 'application/json'
* },
* body: JSON.stringify(changes)
* });
* }}
* />
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* afterChange: (changes, source) => {
* changes?.forEach(([row, prop, oldValue, newValue]) => {
* // Some logic...
* });
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings" />
* ```
* :::
*
* ::: only-for javascript
* ```js
* // using events as plugin hooks
* ...
* const hot1 = new Handsontable(document.getElementById('example1'), {
* myPlugin: true
* });
*
* const hot2 = new Handsontable(document.getElementById('example2'), {
* myPlugin: false
* });
*
* // global hook
* Handsontable.hooks.add('afterChange', function() {
* // Fired twice - for hot1 and hot2
* if (this.getSettings().myPlugin) {
* // function body - will only run for hot1
* }
* });
*
* // local hook (has same effect as a callback)
* hot2.addHook('afterChange', function() {
* // function body - will only run in #example2
* });
* ```
* :::
*
* ::: only-for react
* ```jsx
* const hotRef1 = useRef(null);
* const hotRef2 = useRef(null);
*
* // Using events as plugin hooks:
* ...
*
* <HotTable
* ref={hotRef1}
* myPlugin={true}
* });
*
* <HotTable
* ref={hotRef2}
* myPlugin={false}
* });
*
* ...
*
* const hot2 = hotRef2.current.hotInstance;
* // local hook (has same effect as a callback)
* hot2.addHook('afterChange', function() {
* // function body - will only run in #example2
* });
*
* // global hook
* Handsontable.hooks.add('afterChange', function() {
* // Fired twice - for hot1 and hot2
* if (this.getSettings().myPlugin) {
* // function body - will only run for first instance
* }
* });
* :::
* ...
*/
export const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-sentence */
/**
* Fired after resetting a cell's meta. This happens when the {@link Core#updateSettings} method is called.
*
* @event Hooks#afterCellMetaReset
*/
'afterCellMetaReset',
/**
* Fired after one or more cells has been changed. The changes are triggered in any situation when the
* value is entered using an editor or changed using API (e.q [`setDataAtCell`](@/api/core.md#setdataatcell) method).
*
* __Note:__ For performance reasons, the `changes` array is null for `"loadData"` source.
*
* @event Hooks#afterChange
* @param {Array[]} changes 2D array containing information about each of the edited cells `[[row, prop, oldVal, newVal], ...]`. `row` is a visual row index.
* @param {string} [source] String that identifies source of hook call ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
* @example
* ::: only-for javascript
* ```js
* new Handsontable(element, {
* afterChange: (changes) => {
* changes?.forEach(([row, prop, oldValue, newValue]) => {
* // Some logic...
* });
* }
* })
* ```
* :::
*
* ::: only-for react
* ```jsx
* <HotTable
* afterChange={(changes, source) => {
* changes?.forEach(([row, prop, oldValue, newValue]) => {
* // Some logic...
* });
* }}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* afterChange: (changes, source) => {
* changes?.forEach(([row, prop, oldValue, newValue]) => {
* // Some logic...
* });
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings"></hot-table>
* ```
* :::
*/
'afterChange',
/**
* Fired each time user opens {@link ContextMenu} and after setting up the Context Menu's default options. These options are a collection
* which user can select by setting an array of keys or an array of objects in {@link Options#contextMenu} option.
*
* @event Hooks#afterContextMenuDefaultOptions
* @param {Array} predefinedItems An array of objects containing information about the pre-defined Context Menu items.
*/
'afterContextMenuDefaultOptions',
/**
* Fired each time user opens {@link ContextMenu} plugin before setting up the Context Menu's items but after filtering these options by
* user ([`contextMenu`](@/api/options.md#contextmenu) option). This hook can by helpful to determine if user use specified menu item or to set up
* one of the menu item to by always visible.
*
* @event Hooks#beforeContextMenuSetItems
* @param {object[]} menuItems An array of objects containing information about to generated Context Menu items.
*/
'beforeContextMenuSetItems',
/**
* Fired by {@link DropdownMenu} plugin after setting up the Dropdown Menu's default options. These options are a
* collection which user can select by setting an array of keys or an array of objects in {@link Options#dropdownMenu}
* option.
*
* @event Hooks#afterDropdownMenuDefaultOptions
* @param {object[]} predefinedItems An array of objects containing information about the pre-defined Context Menu items.
*/
'afterDropdownMenuDefaultOptions',
/**
* Fired by {@link DropdownMenu} plugin before setting up the Dropdown Menu's items but after filtering these options
* by user ([`dropdownMenu`](@/api/options.md#dropdownmenu) option). This hook can by helpful to determine if user use specified menu item or to set
* up one of the menu item to by always visible.
*
* @event Hooks#beforeDropdownMenuSetItems
* @param {object[]} menuItems An array of objects containing information about to generated Dropdown Menu items.
*/
'beforeDropdownMenuSetItems',
/**
* Fired by {@link ContextMenu} plugin after hiding the Context Menu. This hook is fired when {@link Options#contextMenu}
* option is enabled.
*
* @event Hooks#afterContextMenuHide
* @param {object} context The Context Menu plugin instance.
*/
'afterContextMenuHide',
/**
* Fired by {@link ContextMenu} plugin before opening the Context Menu. This hook is fired when {@link Options#contextMenu}
* option is enabled.
*
* @event Hooks#beforeContextMenuShow
* @param {object} context The Context Menu instance.
*/
'beforeContextMenuShow',
/**
* Fired by {@link ContextMenu} plugin after opening the Context Menu. This hook is fired when {@link Options#contextMenu}
* option is enabled.
*
* @event Hooks#afterContextMenuShow
* @param {object} context The Context Menu plugin instance.
*/
'afterContextMenuShow',
/**
* Fired by {@link CopyPaste} plugin after reaching the copy limit while copying data. This hook is fired when
* {@link Options#copyPaste} option is enabled.
*
* @event Hooks#afterCopyLimit
* @param {number} selectedRows Count of selected copyable rows.
* @param {number} selectedColumns Count of selected copyable columns.
* @param {number} copyRowsLimit Current copy rows limit.
* @param {number} copyColumnsLimit Current copy columns limit.
*/
'afterCopyLimit',
/**
* Fired before created a new column.
*
* @event Hooks#beforeCreateCol
* @param {number} index Represents the visual index of first newly created column in the data source array.
* @param {number} amount Number of newly created columns in the data source array.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
* @returns {*} If `false` then creating columns is cancelled.
* @example
* ::: only-for javascript
* ```js
* // Return `false` to cancel column inserting.
* new Handsontable(element, {
* beforeCreateCol: function(data, coords) {
* return false;
* }
* });
* ```
* :::
*
* ::: only-for react
* ```jsx
* // Return `false` to cancel column inserting.
* <HotTable
* beforeCreateCol={(data, coords) => {
* return false;
* }}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* beforeCreateCol: (data, coords) => {
* // Return `false` to cancel column inserting.
* return false;
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings"></hot-table>
* ```
* :::
*/
'beforeCreateCol',
/**
* Fired after the order of columns has changed.
* This hook is fired by changing column indexes of any type supported by the {@link IndexMapper}.
*
* @event Hooks#afterColumnSequenceChange
* @param {'init'|'remove'|'insert'|'move'|'update'} [source] A string that indicates what caused the change to the order of columns.
*/
'afterColumnSequenceChange',
/**
* Fired after created a new column.
*
* @event Hooks#afterCreateCol
* @param {number} index Represents the visual index of first newly created column in the data source.
* @param {number} amount Number of newly created columns in the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
*/
'afterCreateCol',
/**
* Fired before created a new row.
*
* @event Hooks#beforeCreateRow
* @param {number} index Represents the visual index of first newly created row in the data source array.
* @param {number} amount Number of newly created rows in the data source array.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
* @returns {*|boolean} If false is returned the action is canceled.
*/
'beforeCreateRow',
/**
* Fired after created a new row.
*
* @event Hooks#afterCreateRow
* @param {number} index Represents the visual index of first newly created row in the data source array.
* @param {number} amount Number of newly created rows in the data source array.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
*/
'afterCreateRow',
/**
* Fired after all selected cells are deselected.
*
* @event Hooks#afterDeselect
*/
'afterDeselect',
/**
* Fired after destroying the Handsontable instance.
*
* @event Hooks#afterDestroy
*/
'afterDestroy',
/**
* Hook fired after `keydown` event is handled.
*
* @event Hooks#afterDocumentKeyDown
* @param {Event} event A native `keydown` event object.
*/
'afterDocumentKeyDown',
/**
* Fired inside the Walkontable's selection `draw` method. Can be used to add additional class names to cells, depending on the current selection.
*
* @event Hooks#afterDrawSelection
* @param {number} currentRow Row index of the currently processed cell.
* @param {number} currentColumn Column index of the currently cell.
* @param {number[]} cornersOfSelection Array of the current selection in a form of `[startRow, startColumn, endRow, endColumn]`.
* @param {number|undefined} layerLevel Number indicating which layer of selection is currently processed.
* @since 0.38.1
* @returns {string|undefined} Can return a `String`, which will act as an additional `className` to be added to the currently processed cell.
*/
'afterDrawSelection',
/**
* Fired inside the Walkontable's `refreshSelections` method. Can be used to remove additional class names from all cells in the table.
*
* @event Hooks#beforeRemoveCellClassNames
* @since 0.38.1
* @returns {string[]|undefined} Can return an `Array` of `String`s. Each of these strings will act like class names to be removed from all the cells in the table.
*/
'beforeRemoveCellClassNames',
/**
* Hook fired after `compositionstart` event is handled.
*
* @event Hooks#beforeCompositionStart
* @since 15.3.0
* @param {Event} event A native `composition` event object.
*/
'beforeCompositionStart',
/**
* Fired after getting the cell settings.
*
* @event Hooks#afterGetCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {object} cellProperties Object containing the cell properties.
*/
'afterGetCellMeta',
/**
* Fired after retrieving information about a column header and appending it to the table header.
*
* @event Hooks#afterGetColHeader
* @param {number} column Visual column index.
* @param {HTMLTableCellElement} TH Header's TH element.
* @param {number} [headerLevel=0] (Since 12.2.0) Header level index. Accepts positive (0 to n)
* and negative (-1 to -n) values. For positive values, 0 points to the
* topmost header. For negative values, -1 points to the bottom-most
* header (the header closest to the cells).
*/
'afterGetColHeader',
/**
* Fired after retrieving information about a row header and appending it to the table header.
*
* @event Hooks#afterGetRowHeader
* @param {number} row Visual row index.
* @param {HTMLTableCellElement} TH Header's TH element.
*/
'afterGetRowHeader',
/**
* Fired after the Handsontable instance is initiated.
*
* @event Hooks#afterInit
*/
'afterInit',
/**
* Fired after Handsontable's [`data`](@/api/options.md#data)
* gets modified by the [`loadData()`](@/api/core.md#loaddata) method
* or the [`updateSettings()`](@/api/core.md#updatesettings) method.
*
* Read more:
* - [Binding to data](@/guides/getting-started/binding-to-data/binding-to-data.md)
* - [Saving data](@/guides/getting-started/saving-data/saving-data.md)
*
* @event Hooks#afterLoadData
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
*/
'afterLoadData',
/**
* Fired after the [`updateData()`](@/api/core.md#updatedata) method
* modifies Handsontable's [`data`](@/api/options.md#data).
*
* Read more:
* - [Binding to data](@/guides/getting-started/binding-to-data/binding-to-data.md)
* - [Saving data](@/guides/getting-started/saving-data/saving-data.md)
*
* @event Hooks#afterUpdateData
* @since 11.1.0
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
*/
'afterUpdateData',
/**
* Fired after a scroll event, which is identified as a momentum scroll (e.g. on an iPad).
*
* @event Hooks#afterMomentumScroll
*/
'afterMomentumScroll',
/**
* Fired after a `mousedown` event is triggered on the cell corner (the drag handle).
*
* @event Hooks#afterOnCellCornerMouseDown
* @param {Event} event `mousedown` event object.
*/
'afterOnCellCornerMouseDown',
/**
* Fired after a `dblclick` event is triggered on the cell corner (the drag handle).
*
* @event Hooks#afterOnCellCornerDblClick
* @param {Event} event `dblclick` event object.
*/
'afterOnCellCornerDblClick',
/**
* Fired after clicking on a cell or row/column header. In case the row/column header was clicked, the coordinate
* indexes are negative.
*
* For example clicking on the row header of cell (0, 0) results with `afterOnCellMouseDown` called
* with coordinates `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellMouseDown
* @param {Event} event `mousedown` event object.
* @param {CellCoords} coords Coordinates object containing the visual row and visual column indexes of the clicked cell.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseDown',
/**
* Fired after clicking on a cell or row/column header. In case the row/column header was clicked, the coordinate
* indexes are negative.
*
* For example clicking on the row header of cell (0, 0) results with `afterOnCellMouseUp` called
* with coordinates `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellMouseUp
* @param {Event} event `mouseup` event object.
* @param {CellCoords} coords Coordinates object containing the visual row and visual column indexes of the clicked cell.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseUp',
/**
* Fired after clicking right mouse button on a cell or row/column header.
*
* For example clicking on the row header of cell (0, 0) results with `afterOnCellContextMenu` called
* with coordinates `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellContextMenu
* @since 4.1.0
* @param {Event} event `contextmenu` event object.
* @param {CellCoords} coords Coordinates object containing the visual row and visual column indexes of the clicked cell.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellContextMenu',
/**
* Fired after hovering a cell or row/column header with the mouse cursor. In case the row/column header was
* hovered, the index is negative.
*
* For example, hovering over the row header of cell (0, 0) results with `afterOnCellMouseOver` called
* with coords `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellMouseOver
* @param {Event} event `mouseover` event object.
* @param {CellCoords} coords Hovered cell's visual coordinate object.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseOver',
/**
* Fired after leaving a cell or row/column header with the mouse cursor.
*
* @event Hooks#afterOnCellMouseOut
* @param {Event} event `mouseout` event object.
* @param {CellCoords} coords Leaved cell's visual coordinate object.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseOut',
/**
* Fired after one or more columns are removed.
*
* @event Hooks#afterRemoveCol
* @param {number} index Visual index of starter column.
* @param {number} amount An amount of removed columns.
* @param {number[]} physicalColumns An array of physical columns removed from the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
*/
'afterRemoveCol',
/**
* Fired after one or more rows are removed.
*
* @event Hooks#afterRemoveRow
* @param {number} index Visual index of starter row.
* @param {number} amount An amount of removed rows.
* @param {number[]} physicalRows An array of physical rows removed from the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
*/
'afterRemoveRow',
/**
* Fired before starting rendering the cell.
*
* @event Hooks#beforeRenderer
* @param {HTMLTableCellElement} TD Currently rendered cell's TD element.
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string|number} prop Column property name or a column index, if datasource is an array of arrays.
* @param {*} value Value of the rendered cell.
* @param {object} cellProperties Object containing the cell's properties.
*/
'beforeRenderer',
/**
* Fired after finishing rendering the cell (after the renderer finishes).
*
* @event Hooks#afterRenderer
* @param {HTMLTableCellElement} TD Currently rendered cell's TD element.
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string|number} prop Column property name or a column index, if datasource is an array of arrays.
* @param {*} value Value of the rendered cell.
* @param {object} cellProperties Object containing the cell's properties.
*/
'afterRenderer',
/**
* Fired after the order of rows has changed.
* This hook is fired by changing row indexes of any type supported by the {@link IndexMapper}.
*
* @event Hooks#afterRowSequenceChange
* @param {'init'|'remove'|'insert'|'move'|'update'} [source] A string that indicates what caused the change to the order of rows.
*/
'afterRowSequenceChange',
/**
* Fired before the vertical viewport scroll. Triggered by the [`scrollViewportTo()`](@/api/core.md#scrollviewportto)
* method or table internals.
*
* @since 14.0.0
* @event Hooks#beforeViewportScrollVertically
* @param {number} visualRow Visual row index.
* @param {'auto' | 'top' | 'bottom'} [snapping='auto'] If `'top'`, viewport is scrolled to show
* the cell on the top of the table. If `'bottom'`, viewport is scrolled to show the cell on
* the bottom of the table. When `'auto'`, the viewport is scrolled only when the row is outside of
* the viewport.
* @returns {number | boolean} Returns modified row index (or the same as passed in the method argument) to which
* the viewport will be scrolled. If the returned value is `false`, the scrolling will be canceled.
*/
'beforeViewportScrollVertically',
/**
* Fired before the horizontal viewport scroll. Triggered by the [`scrollViewportTo()`](@/api/core.md#scrollviewportto)
* method or table internals.
*
* @since 14.0.0
* @event Hooks#beforeViewportScrollHorizontally
* @param {number} visualColumn Visual column index.
* @param {'auto' | 'start' | 'end'} [snapping='auto'] If `'start'`, viewport is scrolled to show
* the cell on the left of the table. If `'end'`, viewport is scrolled to show the cell on the right of
* the table. When `'auto'`, the viewport is scrolled only when the column is outside of the viewport.
* @returns {number | boolean} Returns modified column index (or the same as passed in the method argument) to which
* the viewport will be scrolled. If the returned value is `false`, the scrolling will be canceled.
*/
'beforeViewportScrollHorizontally',
/**
* Fired before the vertical or horizontal viewport scroll. Triggered by the [`scrollViewportTo()`](@/api/core.md#scrollviewportto)
* method or table internals.
*
* @since 14.0.0
* @event Hooks#beforeViewportScroll
*/
'beforeViewportScroll',
/**
* Fired after the horizontal scroll event.
*
* @event Hooks#afterScrollHorizontally
*/
'afterScrollHorizontally',
/**
* Fired after the vertical scroll event.
*
* @event Hooks#afterScrollVertically
*/
'afterScrollVertically',
/**
* Fired after the vertical or horizontal scroll event.
*
* @since 14.0.0
* @event Hooks#afterScroll
*/
'afterScroll',
/**
* Fired after one or more cells are selected (e.g. during mouse move).
*
* @event Hooks#afterSelection
* @param {number} row Selection start visual row index.
* @param {number} column Selection start visual column index.
* @param {number} row2 Selection end visual row index.
* @param {number} column2 Selection end visual column index.
* @param {object} preventScrolling A reference to the observable object with the `value` property.
* Property `preventScrolling.value` expects a boolean value that
* Handsontable uses to control scroll behavior after selection.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
* @example
* ::: only-for javascript
* ```js
* new Handsontable(element, {
* afterSelection: (row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
* // If set to `false` (default): when cell selection is outside the viewport,
* // Handsontable scrolls the viewport to cell selection's end corner.
* // If set to `true`: when cell selection is outside the viewport,
* // Handsontable doesn't scroll to cell selection's end corner.
* preventScrolling.value = true;
* }
* })
* ```
* :::
*
* ::: only-for react
* ```jsx
* <HotTable
* afterSelection={(row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
* // If set to `false` (default): when cell selection is outside the viewport,
* // Handsontable scrolls the viewport to cell selection's end corner.
* // If set to `true`: when cell selection is outside the viewport,
* // Handsontable doesn't scroll to cell selection's end corner.
* preventScrolling.value = true;
* }}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* afterSelection: (
* row,
* column,
* row2,
* column2,
* preventScrolling,
* selectionLayerLevel
* ) => {
* // If set to `false` (default): when cell selection is outside the viewport,
* // Handsontable scrolls the viewport to cell selection's end corner.
* // If set to `true`: when cell selection is outside the viewport,
* // Handsontable doesn't scroll to cell selection's end corner.
* preventScrolling.value = true;
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings"></hot-table>
* ```
* :::
*/
'afterSelection',
/**
* Fired after one or more cells are selected.
*
* The `prop` and `prop2` arguments represent the source object property name instead of the column number.
*
* @event Hooks#afterSelectionByProp
* @param {number} row Selection start visual row index.
* @param {string} prop Selection start data source object property name.
* @param {number} row2 Selection end visual row index.
* @param {string} prop2 Selection end data source object property name.
* @param {object} preventScrolling A reference to the observable object with the `value` property.
* Property `preventScrolling.value` expects a boolean value that
* Handsontable uses to control scroll behavior after selection.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
* @example
* ```js
* ::: only-for javascript
* new Handsontable(element, {
* afterSelectionByProp: (row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
* // setting if prevent scrolling after selection
* preventScrolling.value = true;
* }
* })
* ```
* :::
*
* ::: only-for react
* ```jsx
* <HotTable
* afterSelectionByProp={(row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
* // setting if prevent scrolling after selection
* preventScrolling.value = true;
* }}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* afterSelectionByProp: (
* row,
* column,
* row2,
* column2,
* preventScrolling,
* selectionLayerLevel
* ) => {
* // Setting if prevent scrolling after selection
* preventScrolling.value = true;
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings"></hot-table>
* ```
* :::
*/
'afterSelectionByProp',
/**
* Fired after one or more cells are selected (e.g. on mouse up).
*
* @event Hooks#afterSelectionEnd
* @param {number} row Selection start visual row index.
* @param {number} column Selection start visual column index.
* @param {number} row2 Selection end visual row index.
* @param {number} column2 Selection end visual column index.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
*/
'afterSelectionEnd',
/**
* Fired after one or more cells are selected (e.g. on mouse up).
*
* The `prop` and `prop2` arguments represent the source object property name instead of the column number.
*
* @event Hooks#afterSelectionEndByProp
* @param {number} row Selection start visual row index.
* @param {string} prop Selection start data source object property index.
* @param {number} row2 Selection end visual row index.
* @param {string} prop2 Selection end data source object property index.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
*/
'afterSelectionEndByProp',
/**
* Fired after the focus position within a selected range is changed.
*
* @since 14.3.0
* @event Hooks#afterSelectionFocusSet
* @param {number} row The focus visual row index position.
* @param {number} column The focus visual column index position.
* @param {object} preventScrolling A reference to the observable object with the `value` property.
* Property `preventScrolling.value` expects a boolean value that
* Handsontable uses to control scroll behavior after selection.
* @example
* ```js
* ::: only-for javascript
* new Handsontable(element, {
* afterSelectionFocusSet: (row, column, preventScrolling) => {
* // If set to `false` (default): when focused cell selection is outside the viewport,
* // Handsontable scrolls the viewport to that cell.
* // If set to `true`: when focused cell selection is outside the viewport,
* // Handsontable doesn't scroll the viewport.
* preventScrolling.value = true;
* }
* })
* ```
* :::
*
* ::: only-for react
* ```jsx
* <HotTable
* afterSelectionFocusSet={(row, column, preventScrolling) => {
* // If set to `false` (default): when focused cell selection is outside the viewport,
* // Handsontable scrolls the viewport to that cell.
* // If set to `true`: when focused cell selection is outside the viewport,
* // Handsontable doesn't scroll the viewport.
* preventScrolling.value = true;
* }}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* afterSelectionFocusSet: (row, column, preventScrolling) => {
* // If set to `false` (default): when focused cell selection is outside the viewport,
* // Handsontable scrolls the viewport to that cell.
* // If set to `true`: when focused cell selection is outside the viewport,
* // Handsontable doesn't scroll the viewport.
* preventScrolling.value = true;
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings"></hot-table>
* ```
* :::
*/
'afterSelectionFocusSet',
/**
* Fired before one or more columns are selected (e.g. During mouse header click or {@link Core#selectColumns} API call).
*
* @since 14.0.0
* @event Hooks#beforeSelectColumns
* @param {CellCoords} from Selection start coords object.
* @param {CellCoords} to Selection end coords object.
* @param {CellCoords} highlight Selection cell focus coords object.
* @example
* ::: only-for javascript
* ```js
* new Handsontable(element, {
* beforeSelectColumns: (from, to, highlight) => {
* // Extend the column selection by one column left and one column right.
* from.col = Math.max(from.col - 1, 0);
* to.col = Math.min(to.col + 1, this.countCols() - 1);
* }
* })
* ```
* :::
*
* ::: only-for react
* ```jsx
* <HotTable
* beforeSelectColumns={(from, to, highlight) => {
* // Extend the column selection by one column left and one column right.
* from.col = Math.max(from.col - 1, 0);
* to.col = Math.min(to.col + 1, this.countCols() - 1);
* }}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* beforeSelectColumns: (from, to, highlight) => {
* // Extend the column selection by one column left and one column right.
* from.col = Math.max(from.col - 1, 0);
* to.col = Math.min(to.col + 1, this.countCols() - 1);
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings"></hot-table>
* ```
* :::
*/
'beforeSelectColumns',
/**
* Fired after one or more columns are selected (e.g. during mouse header click or {@link Core#selectColumns} API call).
*
* @since 14.0.0
* @event Hooks#afterSelectColumns
* @param {CellCoords} from Selection start coords object.
* @param {CellCoords} to Selection end coords object.
* @param {CellCoords} highlight Selection cell focus coords object.
*/
'afterSelectColumns',
/**
* Fired before one or more rows are selected (e.g. during mouse header click or {@link Core#selectRows} API call).
*
* @since 14.0.0
* @event Hooks#beforeSelectRows
* @param {CellCoords} from Selection start coords object.
* @param {CellCoords} to Selection end coords object.
* @param {CellCoords} highlight Selection cell focus coords object.
* @example
* ::: only-for javascript
* ```js
* new Handsontable(element, {
* beforeSelectRows: (from, to, highlight) => {
* // Extend the row selection by one row up and one row bottom more.
* from.row = Math.max(from.row - 1, 0);
* to.row = Math.min(to.row + 1, this.countRows() - 1);
* }
* })
* ```
* :::
*
* ::: only-for react
* ```jsx
* <HotTable
* beforeSelectRows={(from, to, highlight) => {
* // Extend the row selection by one row up and one row bottom more.
* from.row = Math.max(from.row - 1, 0);
* to.row = Math.min(to.row + 1, this.countRows() - 1);
* }}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* beforeSelectRows: (from, to, highlight) => {
* // Extend the row selection by one row up and one row down.
* from.row = Math.max(from.row - 1, 0);
* to.row = Math.min(to.row + 1, this.countRows() - 1);
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings"></hot-table>
* ```
* :::
*/
'beforeSelectRows',
/**
* Fired after one or more rows are selected (e.g. during mouse header click or {@link Core#selectRows} API call).
*
* @since 14.0.0
* @event Hooks#afterSelectRows
* @param {CellCoords} from Selection start coords object.
* @param {CellCoords} to Selection end coords object.
* @param {CellCoords} highlight Selection cell focus coords object.
*/
'afterSelectRows',
/**
* Fired after cell meta is changed.
*
* @event Hooks#afterSetCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string} key The updated meta key.
* @param {*} value The updated meta value.
*/
'afterSetCellMeta',
/**
* Fired after cell meta is removed.
*
* @event Hooks#afterRemoveCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string} key The removed meta key.
* @param {*} value Value which was under removed key of cell meta.
*/
'afterRemoveCellMeta',
/**
* Fired after cell data was changed.
*
* @event Hooks#afterSetDataAtCell
* @param {Array} changes An array of changes in format `[[row, column, oldValue, value], ...]`.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
*/
'afterSetDataAtCell',
/**
* Fired after cell data was changed.
* Called only when [`setDataAtRowProp`](@/api/core.md#setdataatrowprop) was executed.
*
* @event Hooks#afterSetDataAtRowProp
* @param {Array} changes An array of changes in format `[[row, prop, oldValue, value], ...]`.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
*/
'afterSetDataAtRowProp',
/**
* Fired after cell source data was changed.
*
* @event Hooks#afterSetSourceDataAtCell
* @since 8.0.0
* @param {Array} changes An array of changes in format `[[row, column, oldValue, value], ...]`.
* @param {string} [source] String that identifies source of hook call.
*/
'afterSetSourceDataAtCell',
/**
* Fired after a theme is enabled, changed, or disabled.
*
* @since 15.0.0
* @event Hooks#afterSetTheme
* @param {string|boolean|undefined} themeName The theme name.
* @param {boolean} firstRun `true` if it's the initial setting of the theme, `false` otherwise.
*/
'afterSetTheme',
/**
* Fired after calling the [`updateSettings`](@/api/core.md#updatesettings) method.
*
* @event Hooks#afterUpdateSettings
* @param {object} newSettings New settings object.
*/
'afterUpdateSettings',
/**
* @description
* A plugin hook executed after validator function, only if validator function is defined.
* Validation result is the first parameter. This can be used to determinate if validation passed successfully or not.
*
* __Returning false from the callback will mark the cell as invalid__.
*
* @event Hooks#afterValidate
* @param {boolean} isValid `true` if valid, `false` if not.
* @param {*} value The value in question.
* @param {number} row Visual row index.
* @param {string|number} prop Property name / visual column index.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
* @returns {undefined | boolean} If `false` the cell will be marked as invalid, `true` otherwise.
*/
'afterValidate',
/**
* Fired before successful change of language (when proper language code was set).
*
* @event Hooks#beforeLanguageChange
* @since 0.35.0
* @param {string} languageCode New language code.
*/
'beforeLanguageChange',
/**
* Fired after successful change of language (when proper language code was set).
*
* @event Hooks#afterLanguageChange
* @since 0.35.0
* @param {string} languageCode New language code.
*/
'afterLanguageChange',
/**
* Fired by {@link Autofill} plugin before populating the data in the autofill feature. This hook is fired when
* {@link Options#fillHandle} option is enabled.
*
* @event Hooks#beforeAutofill
* @param {Array[]} selectionData Data the autofill operation will start from.
* @param {CellRange} sourceRange The range values will be filled from.
* @param {CellRange} targetRange The range new values will be filled into.
* @param {string} direction Declares the direction of the autofill. Possible values: `up`, `down`, `left`, `right`.
*
* @returns {boolean|Array[]} If false, the operation is cancelled. If array of arrays, the returned data
* will be passed into [`populateFromArray`](@/api/core.md#populatefromarray) instead of the default autofill
* algorithm's result.
*/
'beforeAutofill',
/**
* Fired by {@link Autofill} plugin after populating the data in the autofill feature. This hook is fired when
* {@link Options#fillHandle} option is enabled.
*
* @event Hooks#afterAutofill
* @since 8.0.0
* @param {Array[]} fillData The data that was used to fill the `targetRange`. If `beforeAutofill` was used
* and returned `[[]]`, this will be the same object that was returned from `beforeAutofill`.
* @param {CellRange} sourceRange The range values will be filled from.
* @param {CellRange} targetRange The range new values will be filled into.
* @param {string} direction Declares the direction of the autofill. Possible values: `up`, `down`, `left`, `right`.
*/
'afterAutofill',
/**
* Fired before aligning the cell contents.
*
* @event Hooks#beforeCellAlignment
* @param {object} stateBefore An object with class names defining the cell alignment.
* @param {CellRange[]} range An array of `CellRange` coordinates where the alignment will be applied.
* @param {string} type Type of the alignment - either `horizontal` or `vertical`.
* @param {string} alignmentClass String defining the alignment class added to the cell.
* Possible values: `htLeft` , `htCenter`, `htRight`, `htJustify`, `htTop`, `htMiddle`, `htBottom`.
*/
'beforeCellAlignment',
/**
* Fired before one or more cells are changed.
*
* Use this hook to silently alter the user's changes before Handsontable re-renders.
*
* To ignore the user's changes, use a nullified array or return `false`.
*
* @event Hooks#beforeChange
* @param {Array[]} changes 2D array containing information about each of the edited cells `[[row, prop, oldVal, newVal], ...]`. `row` is a visual row index.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
* @returns {undefined | boolean} If `false` all changes were cancelled, `true` otherwise.
* @example
* ::: only-for javascript
* ```js
* // to alter a single change, overwrite the value with `changes[i][3]`
* new Handsontable(element, {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0][3] = 10;
* }
* });
*
* // to ignore a single change, set `changes[i]` to `null`
* // or remove `changes[i]` from the array, by using `changes.splice(i, 1)`
* new Handsontable(element, {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0] = null;
* }
* });
*
* // to ignore all changes, return `false`
* // or set the array's length to 0, by using `changes.length = 0`
* new Handsontable(element, {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* return false;
* }
* });
* ```
* :::
*
* ::: only-for react
* ```jsx
* // to alter a single change, overwrite the desired value with `changes[i][3]`
* <HotTable
* beforeChange={(changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0][3] = 10;
* }}
* />
*
* // to ignore a single change, set `changes[i]` to `null`
* // or remove `changes[i]` from the array, by using changes.splice(i, 1).
* <HotTable
* beforeChange={(changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0] = null;
* }}
* />
*
* // to ignore all changes, return `false`
* // or set the array's length to 0 (`changes.length = 0`)
* <HotTable
* beforeChange={(changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* return false;
* }}
* />
* ```
* :::
* ::: only-for angular
*```ts
* // To alter a single change, overwrite the desired value with `changes[i][3]`
* settings1 = {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0][3] = 10;
* },
* };
*
* // To ignore a single change, set `changes[i]` to `null`
* // or remove `changes[i]` from the array, by using changes.splice(i, 1).
* settings2 = {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0] = null;
* },
* };
*
* // To ignore all changes, return `false`
* // or set the array's length to 0 (`changes.length = 0`)
* settings3 = {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* return false;
* },
* };
* ```
*
* ```html
* <hot-table [settings]="settings1"></hot-table>
* <hot-table [settings]="settings2"></hot-table>
* <hot-table [settings]="settings3"></hot-table>
* ```
*
* :::
*/
'beforeChange',
/**
* Fired right before rendering the changes.
*
* @event Hooks#beforeChangeRender
* @param {Array[]} changes Array in form of `[row, prop, oldValue, newValue]`.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
*/
'beforeChangeRender',
/**
* Fired before drawing the borders.
*
* @event Hooks#beforeDrawBorders
* @param {Array} corners Array specifying the current selection borders.
* @param {string} borderClassName Specifies the border class name.
*/
'beforeDrawBorders',
/**
* Fired before getting cell settings.
*
* @event Hooks#beforeGetCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {object} cellProperties Object containing the cell's properties.
*/
'beforeGetCellMeta',
/**
* Fired before cell meta is removed.
*
* @event Hooks#beforeRemoveCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string} key The removed meta key.
* @param {*} value Value which is under removed key of cell meta.
* @returns {*|boolean} If false is returned the action is canceled.
*/
'beforeRemoveCellMeta',
/**
* Fired before the Handsontable instance is initiated.
*
* @event Hooks#beforeInit
*/
'beforeInit',
/**
* Fired before the Walkontable instance is initiated.
*
* @event Hooks#beforeInitWalkontable
* @param {object} walkontableConfig Walkontable configuration object.
*/
'beforeInitWalkontable',
/**
* Fired before Handsontable's [`data`](@/api/options.md#data)
* gets modified by the [`loadData()`](@/api/core.md#loaddata) method
* or the [`updateSettings()`](@/api/core.md#updatesettings) method.
*
* Read more:
* - [Binding to data](@/guides/getting-started/binding-to-data/binding-to-data.md)
* - [Saving data](@/guides/getting-started/saving-data/saving-data.md)
*
* @event Hooks#beforeLoadData
* @since 8.0.0
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
* @returns {Array} The returned array will be used as Handsontable's new dataset.
*/
'beforeLoadData',
/**
* Fired before the [`updateData()`](@/api/core.md#updatedata) method
* modifies Handsontable's [`data`](@/api/options.md#data).
*
* Read more:
* - [Binding to data](@/guides/getting-started/binding-to-data/binding-to-data.md)
* - [Saving data](@/guides/getting-started/saving-data/saving-data.md)
*
* @event Hooks#beforeUpdateData
* @since 11.1.0
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
* @returns {Array} The returned array will be used as Handsontable's new dataset.
*/
'beforeUpdateData',
/**
* Hook fired before `keydown` event is handled. It can be used to stop default key bindings.
*
* __Note__: To prevent default behavior you need to call `false` in your `beforeKeyDown` handler.
*
* @event Hooks#beforeKeyDown
* @param {Event} event Original DOM event.
*/
'beforeKeyDown',
/**
* Fired after the user clicked a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellMouseDown
* @param {Event} event The `mousedown` event object.
* @param {CellCoords} coords Cell coords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
* @param {object} controller An object with properties `row`, `column` and `cell`. Each property contains
* a boolean value that allows or disallows changing the selection for that particular area.
*/
'beforeOnCellMouseDown',
/**
* Fired after the user clicked a cell.
*
* @event Hooks#beforeOnCellMouseUp
* @param {Event} event The `mouseup` event object.
* @param {CellCoords} coords Cell coords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
*/
'beforeOnCellMouseUp',
/**
* Fired after the user clicked a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellContextMenu
* @since 4.1.0
* @param {Event} event The `contextmenu` event object.
* @param {CellCoords} coords Cell coords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
*/
'beforeOnCellContextMenu',
/**
* Fired after the user moved cursor over a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellMouseOver
* @param {Event} event The `mouseover` event object.
* @param {CellCoords} coords CellCoords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
* @param {object} controller An object with properties `row`, `column` and `cell`. Each property contains
* a boolean value that allows or disallows changing the selection for that particular area.
*/
'beforeOnCellMouseOver',
/**
* Fired after the user moved cursor out from a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellMouseOut
* @param {Event} event The `mouseout` eve