Vue Data GridRange Selection

Enterprise

Range selection allows Excel-like range selection of cells. Range selections are useful for visually highlighting data, copying data to the Clipboard, or for doing aggregations using the Status Bar.

Selecting Ranges

Range Selection is enabled using the following grid option property enableRangeSelection=true. When enabled, ranges can be selected in the following ways:

  • Mouse Drag: Click the mouse down on a cell and drag and release the mouse over another cell. A range will be created between the two cells and clear any existing ranges.

  • Ctrl & Mouse Drag: Holding ^ Ctrl key while creating a range using mouse drag outside an existing range will create a new range selection and keep any existing ranges.

  • Shift & Click: Clicking on one cell to focus that cell, then holding down ⇧ Shift while clicking another cell, will create a range between both cells.

  • Shift & Arrow Keys: Focusing a cell and then holding down ⇧ Shift and using the arrow keys will create a range starting from the focused cell.

  • Ctrl & Shift & Arrow Keys: Focusing a cell and then holding down ^ Ctrl + ⇧ Shift and using the arrow keys will create a range starting from the focused cell to the last cell in the direction of the Arrow pressed.

Range Deselection

It is possible to deselect part of existing ranges in the following ways:

  • Ctrl & Mouse Drag: Holding ^ Ctrl and dragging a range starting within an existing range will cause any cells covered by the new range to be deselected.

  • Ctrl & Click: Holding ^ Ctrl and clicking a cell will deselect just that cell.

Note that deselecting part of a range can split the range into multiple ranges, since individual ranges have the limitation of being rectangular.

The example below demonstrates simple range selection. Ranges can be selected in all the ways described above.

Suppress Multi Range Selection

By default multiple ranges can be selected. To restrict range selection to a single range, even if the ^ Ctrl key is held down, enable the following grid options property: suppressMultiRangeSelection=true.

The following example demonstrates single range selection:

Ranges with Pinning and Floating

It is possible to select a range that spans pinned and non-pinned sections of the grid. If you do this, the selected range will not have any gaps with regards to the column order. For example, if you start the drag on the left pinned area and drag to the right pinned area, then all of the columns in the center area will also be part of the range.

Likewise with floating, no row gaps will occur if a range spans into pinned rows. A range will be continuous between the floating top rows, the center, and the floating bottom rows.

The above two (pinning and floating) can be thought of as follows: if you have a grid with pinning and / or floating, then 'flatten out' the grid in your head so that all rows and columns are visible, then the range selection will work as you would expect in the flattened out version where only full rectangles can be selectable.

Range Selection Changed Event

The rangeSelectionChanged event tells you that the range selection has changed. The event has two properties, started and finished, which are true when the selection is starting or finishing.

For example, if selecting a range of 5 cells in a row, the user will click the first cell and drag to the last cell. This will result in up to 7 events. The first and last cell in the range will cause two events each. This is due to the first cell firing an event with started=true, finished=true upon mousedown with an additional event started=true, finished=false while in the range, and the last cell firing an event started=false, finished=false as soon as it is in the range and then again started=false, finished=true upon the end of range selection. All the intermediary events will have one event with both started and finished as false.

Range Selection API

The following methods are available on the GridApi for managing range selection.

getCellRanges()

Get the selected ranges using api.getCellRanges(). This will return back a list of cell range objects, each of which contains the details of one range.

The start is the first cell the user clicked on and the end is the cell where the user stopped dragging. Do not assume that the start cell's index is numerically before the end cell, as the user could have dragged up.

clearRangeSelection()

addCellRange(rangeSelection)

Adds a range to the selection. This keeps any previous ranges. If you wish to only have the new range selected, then call clearRangeSelection() first. The method takes the params of type CellRangeParams.