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 Control key while creating a range using mouse drag will create a new range selection and keep any existing ranges.
- Shift & Click: Clicking on one cell to focus that cell, then hold 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.
Range Selection Example
The example below demonstrates simple range selection. Ranges can be selected in all ways described above.
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 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 with only full rectangles can be selectable.
Range Changed Event
There is one event rangeSelectionChanged to tell you 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 10 cells in a row, the user will click the first
cell and drag to the last cell. This will result in up to 11 events. The first event
started=true, the last will have
all the intermediary events will have both of these values as false.
Range Selection API
Get the selected ranges using
api.getCellRanges(). This will return back
a list of cell range objects, each object contain the details of one range. The
structure of the cell range is as follows:
The start and end will be the cells the user started the drag on. 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 of dragged up.
Clears the range selection.
Adds a range to the selection. This keeps any previous ranges. If you wish to have this range
exclusively, then call clearRangeSelection() first. The method takes the following params:
Ranges are normally bounded by a start and end row. However it is also possible to define a range unbounded by rows (ie to contain all rows). For an unbounded range, do not provided start or end row positions.
Row positions are defined by a row index and pinned. Row indexes start at zero and increment. Pinned can be either 'top' (row is in pinned top section), 'bottom' (row in in pinned bottom section) or undefined (row is in the main body). See Row Pinning for information on row pinning.
Ranges are defined by a list of columns. Pass in either a) a list of columns or b) a start and end column and let the grid work out the columns in between. Passing a list of columns instead of a start and end column has the advantage that the columns do not need to be contiguous.
There is a grid callback
processCellForClipboard() that allows you to format cells before
going to the clipboard. This can be useful if, for example, you are pasting to Excel and you need to
format dates so that Excel can understand them.
The callback params has the following attributes:
value, node, column, api, columnApi, context, type.
Copy Range Down
When you have more than one row selected in a range, pressing keys Ctrl + D will copy the range down.
Advanced Range Selection Example
The example below demonstrates a more complex range selection scenario. The example listens
rangeSelectionChanged event and creates a sum of all the number values
that are in the range (it ignores all non-number values). The
is used to update the eager and lazy figures separately.
The example also shows use of
by making all the athlete names upper case when copying into the clipboard and lowercase when
copying it from the clipboard.
Range Selection Example - Suppress Multi
This example differs from above as
suppressMultiRangeSelection=true which only allows
one range selection even if ctrl key is held down.