JavaScript Data Grid CellRange

Description

The CellRange class holds a set of cell coordinates (CellCoords instances) that form a selection range.

A single CellRange instance represents a single unit of selection that contains either a single cell or multiple adjacent cells.

To import the CellRange class:

import Handsontable, { CellRange } from '/handsontable';

// or, using modules
import Handsontable, { CellRange } from '/handsontable/base';

Methods

clone

Source code (opens new window)

cellRange.clone() ⇒ CellRange

Clones your CellRange instance.

containsHeaders

Source code (opens new window)

cellRange.containsHeaders() ⇒ boolean

Checks if your range overlaps headers range (negative coordinates).

expand

Source code (opens new window)

cellRange.expand(cellCoords) ⇒ boolean

Adds a cell to your range, at cellCoords coordinates.

The cellCoords coordinates must exceed a corner of your range.

Param Type Description
cellCoords CellCoords A new cell's coordinates.

expandByRange

Source code (opens new window)

cellRange.expandByRange(expandingRange) ⇒ boolean

Expand your range with another range (expandingRange).

Param Type Description
expandingRange CellRange A new range.

flipDirectionHorizontally

Source code (opens new window)

cellRange.flipDirectionHorizontally()

Flips the direction of your range horizontally (e.g., NW-SE changes to NE-SW).

flipDirectionVertically

Source code (opens new window)

cellRange.flipDirectionVertically()

Flips the direction of your range vertically (e.g., NW-SE changes to SW-NE).

forAll

Source code (opens new window)

cellRange.forAll(callback)

Runs a callback function on all cells within your range.

You can break the iteration by returning false in the callback function.

Param Type Description
callback function A callback function.

getAll

Source code (opens new window)

cellRange.getAll() ⇒ Array<CellCoords>

Gets the coordinates of all cells of your range.

getBordersSharedWith

Source code (opens new window)

cellRange.getBordersSharedWith(range) ⇒ Array<('top'|'right'|'bottom'|'left')>

Indicates which borders (top, right, bottom, left) are shared between your CellRangeinstance and another range that's within your range.

Param Type Description
range CellRange A range to compare with.

getBottomEndCorner

Source code (opens new window)

cellRange.getBottomEndCorner() ⇒ CellCoords

Gets the bottom right (in LTR) or bottom left (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getBottomLeftCorner

Source code (opens new window)

cellRange.getBottomLeftCorner() ⇒ CellCoords

Gets the bottom left corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getBottomRightCorner

Source code (opens new window)

cellRange.getBottomRightCorner() ⇒ CellCoords

Gets the bottom right corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getBottomStartCorner

Source code (opens new window)

cellRange.getBottomStartCorner() ⇒ CellCoords

Gets the bottom left (in LTR) or bottom right (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getCellsCount

Source code (opens new window)

cellRange.getCellsCount() ⇒ number

Returns the number of cells within your range (excluding column and row headers).

getDirection

Source code (opens new window)

cellRange.getDirection() ⇒ string

Gets the direction of the selection.

Returns: string - Returns one of the values: 'NW-SE', 'NE-SW', 'SE-NW', 'SW-NE'.

getHeight

Source code (opens new window)

cellRange.getHeight() ⇒ number

Returns the height of your range (as a number of rows, excluding row headers).

getHorizontalDirection

Source code (opens new window)

cellRange.getHorizontalDirection() ⇒ string

Gets the horizontal direction of the selection.

Returns: string - Returns one of the values: W-E (west->east), E-W (east->west).

getInner

Source code (opens new window)

cellRange.getInner() ⇒ Array<CellCoords>

Gets the coordinates of the inner cells of your range.

getOppositeCorner

Source code (opens new window)

cellRange.getOppositeCorner(coords) ⇒ CellCoords

Gets the coordinates of a range corner opposite to the provided coords.

For example: if the coords coordinates match the bottom-right corner of your range, the coordinates of the top-left corner of your range are returned.

Param Type Description
coords CellCoords Coordinates to check.

getOuterBottomEndCorner

Source code (opens new window)

cellRange.getOuterBottomEndCorner() ⇒ CellCoords

Gets the bottom right (in LTR) or bottom left (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the top and start coordinates are pointed to that header.

getOuterBottomLeftCorner

Source code (opens new window)

cellRange.getOuterBottomLeftCorner() ⇒ CellCoords

Gets the bottom left corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the top and left coordinates are pointed to that header.

getOuterBottomRightCorner

Source code (opens new window)

cellRange.getOuterBottomRightCorner() ⇒ CellCoords

Gets the bottom right corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the top and left coordinates are pointed to that header.

getOuterBottomStartCorner

Source code (opens new window)

cellRange.getOuterBottomStartCorner() ⇒ CellCoords

Gets the bottom left (in LTR) or bottom right (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the top and start coordinates are pointed to that header.

getOuterHeight

Source code (opens new window)

cellRange.getOuterHeight() ⇒ number

Returns the height of your range (as a number of rows, including row headers).

getOuterTopEndCorner

Source code (opens new window)

cellRange.getOuterTopEndCorner() ⇒ CellCoords

Gets the top right (in LTR) or top left (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the top and start coordinates are pointed to that header.

getOuterTopLeftCorner

Source code (opens new window)

cellRange.getOuterTopLeftCorner() ⇒ CellCoords

Gets the top left corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the top and left coordinates are pointed to that header.

getOuterTopRightCorner

Source code (opens new window)

cellRange.getOuterTopRightCorner() ⇒ CellCoords

Gets the top right corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the top and left coordinates are pointed to that header.

getOuterTopStartCorner

Source code (opens new window)

cellRange.getOuterTopStartCorner() ⇒ CellCoords

Gets the top left (in LTR) or top right (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the top and start coordinates are pointed to that header.

getOuterWidth

Source code (opens new window)

cellRange.getOuterWidth() ⇒ number

Returns the width of your range (as a number of columns, including column headers).

getTopEndCorner

Source code (opens new window)

cellRange.getTopEndCorner() ⇒ CellCoords

Gets the top right (in LTR) or top left (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getTopLeftCorner

Source code (opens new window)

cellRange.getTopLeftCorner() ⇒ CellCoords

Gets the top-left corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getTopRightCorner

Source code (opens new window)

cellRange.getTopRightCorner() ⇒ CellCoords

Gets the top right corner coordinates of your range, both in the LTR and RTL layout direction.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getTopStartCorner

Source code (opens new window)

cellRange.getTopStartCorner() ⇒ CellCoords

Gets the top-left (in LTR) or top-right (in RTL) corner coordinates of your range.

If the corner contains header coordinates (negative values), the corner coordinates are normalized to 0.

getVerticalDirection

Source code (opens new window)

cellRange.getVerticalDirection() ⇒ string

Gets the vertical direction of the selection.

Returns: string - Returns one of the values: N-S (north->south), S-N (south->north).

getWidth

Source code (opens new window)

cellRange.getWidth() ⇒ number

Returns the width of your range (as a number of columns, excluding column headers).

includes

Source code (opens new window)

cellRange.includes(cellCoords) ⇒ boolean

Checks if another set of coordinates (cellCoords) is within the from and to coordinates of your range.

Param Type Description
cellCoords CellCoords Coordinates to check.

includesRange

Source code (opens new window)

cellRange.includesRange(cellRange) ⇒ boolean

Checks if another range (cellRange) is within your range.

Param Type Description
cellRange CellRange A range to check.

isCorner

Source code (opens new window)

cellRange.isCorner(coords) ⇒ boolean

Checks if a set of coordinates (coords) matches one of the 4 corners of your range.

Param Type Description
coords CellCoords Coordinates to check.

isEqual

Source code (opens new window)

cellRange.isEqual(cellRange) ⇒ boolean

Checks if another range (cellRange) is equal to your range.

Param Type Description
cellRange CellRange A range to check.

isNorthWestOf

Source code (opens new window)

cellRange.isNorthWestOf(cellCoords) ⇒ boolean

Checks if coordinates point is north-west of your range.

Param Type Description
cellCoords CellRange Coordinates to check.

isOverlappingHorizontally

Source code (opens new window)

cellRange.isOverlappingHorizontally(cellRange) ⇒ boolean

Checks if another range (cellRange) overlaps your range horizontally.

For example: returns true if the last column of your range is 5 and the first column of the cellRange range is 3.

Param Type Description
cellRange CellRange A range to check.

isOverlappingVertically

Source code (opens new window)

cellRange.isOverlappingVertically(cellRange) ⇒ boolean

Checks if another range (cellRange) overlaps your range vertically.

For example: returns true if the last row of your range is 5 and the first row of the cellRange range is 3.

Param Type Description
cellRange CellRange A range to check.

isSingle

Source code (opens new window)

cellRange.isSingle() ⇒ boolean

Checks if your range is just a single cell or header.

isSingleCell

Source code (opens new window)

cellRange.isSingleCell() ⇒ boolean

Checks if your range is just a single cell.

isSingleHeader

Source code (opens new window)

cellRange.isSingleHeader() ⇒ boolean

Checks if your range is just a single header.

isSouthEastOf

Source code (opens new window)

cellRange.isSouthEastOf(cellCoords) ⇒ boolean

Checks if coordinates point is south-east of your range.

Param Type Description
cellCoords CellCoords Coordinates to check.

isValid

Source code (opens new window)

cellRange.isValid(tableParams) ⇒ boolean

Checks if the coordinates in your CellRange instance are valid in the context of given table parameters.

See the isValid() method of the CellCoords class.

Param Type Description
tableParams object An object with a defined table size.
tableParams.countRows number The total number of rows.
tableParams.countCols number The total number of columns.
tableParams.countRowHeaders number A number of row headers.
tableParams.countColHeaders number A number of column headers.

overlaps

Source code (opens new window)

cellRange.overlaps(cellRange) ⇒ boolean

Checks if another range (cellRange) overlaps your range.

Range A overlaps range B if the intersection of A and B (or B and A) is not empty.

Param Type Description
cellRange CellRange A range to check.

setDirection

Source code (opens new window)

cellRange.setDirection(direction)

Sets the direction of the selection.

Param Type Description
direction string One of the values: 'NW-SE', 'NE-SW', 'SE-NW', 'SW-NE'.

setFrom

Source code (opens new window)

cellRange.setFrom(coords) ⇒ CellRange

Sets the coords coordinates as the start of your range.

Param Type Description
coords CellCoords Coordinates to use.

setHighlight

Source code (opens new window)

cellRange.setHighlight(coords) ⇒ CellRange

Highlights cell selection at the coords coordinates.

Param Type Description
coords CellCoords Coordinates to use.

setTo

Source code (opens new window)

cellRange.setTo(coords) ⇒ CellRange

Sets the coords coordinates as the end of your range.

Param Type Description
coords CellCoords Coordinates to use.

toObject

Source code (opens new window)

cellRange.toObject() ⇒ Object

Converts your CellRange instance into an object literal with the following properties:

  • from
    • row
    • col
  • to
    • row
    • col

Returns: Object - An object literal with from and to properties.

Last update: Mar 27, 2024