SandGrid User Guide
Selection
Focus
One element within a SandGrid control has the focus, and is said to be the focused element. Even when you have multiple, nested grids, only one element in the entire display can have the focus. Elements are notified when the focus enters and leaves them, and display hints such as a focus rectangle and a "current row" indicator to help visualize it. When the focus is within a nested grid its border becomes highlighted.
Keyboard and Mouse Selection
The selection is entirely separate from the focus but they typically go hand in hand in most data display controls. Each grid has its own selection, which can be single or multiple elements.
SandGrid offers the normal keyboard commands to control selection. The arrow keys are used to move the focus around and this normally carries the selection with it. If you hold the control key while moving, only the focus moves, leaving the selection intact. Pressing control-space adds or removes the focused element to or from the selection. Applying the shift key while moving extends the selection from where you started to the current focused element as you move it around. The other directional keys (PageUp, PageDown, Home and End) work in the same way.
Other keyboard commands are supported, such as Ctrl-A to apply a Select All command and Alt-Asterisk to progressively expand more and more levels of child nodes under the selection.
Mouse selection operates by combining a mouse click with the control and shift keys, again. Depending on the mouse behavior settings in operation on your grid you may be able to select a combination of rows, cells and columns. You can also click and drag to extend the selection.
Nested grids contain their own distinct selection from that of other grids, including the primary grid. With the keyboard, you can move the focus to a row that contains a nested grid, and it is indicated with a highlighted strip down the left of the grid. When the nested grid row is selected like this, you can press the right arrow key to move into the grid, where the directional keys work as expected within the confines of that grid.
Selection Granularity and Highlight Types
The selection granularity is a very important property of your grid and it indicates whether rows or cells are normally selected. This is not a hard and fast rule, for example even under cell selection in a spreadsheet you still want the user to be able to select entire rows. However, the selection granularity will govern what happens when you click on the grid and when you navigate using the keyboard.
Row selection is the norm for ListView and TreeView type uses of the grid, and there are a few different display types for a selected row. You can choose to highlight the entire row, a partial row or only the contents of the primary column. Full row highlighting is used in applications like Outlook and partial row highlighting is used in the ListView control when FullRowSelect is set. Partial row highlighting works by starting the selection at the contents of the primary column (e.g. after any image or indentation controls) and extending to the end. Highlighting of only the contents of the primary column is usually used in TreeView applications of the grid.
Selectable Elements
Any element derived class is selectable, and this includes rows, columns and cells. Clicking on a row will either select the row or the cell under the cursor, depending on the SelectionGranularity. A collection of the selected elements is exposed via the SelectedElements property. These could be instances of any element derived class, in any order.
When a row or column is selected, the cells under that element are not automatically selected. Instead, SandGrid offers a GetSelectedCells method that combines the selected elements to return an array of cells that are encompassed by the current selection. This distinction of functionality is ideal for use in spreadsheets where some operations are designed to operate on a range of cells, and some are designed to operate on rows or columns specifically.
Programmatic Selection
Every element in a grid has a Selected property. This property is only usable while the element is present in a grid, it has no meaning outside. The grid maintains a collection of selected elements internally which is kept in sync with this property. Setting the property to true while in single selection mode will unselect any other selected elements. A number of methods are exposed for programmatic manipulation of the selection.
SelectAll either selects all rows or all cells, depending on selection granularity. It does not select columns themselves, and does not select rows even when all their cells are selected.
ClearSelection ensures that no element is selected, and applies optimization to do this faster than looping through all selected elements unselecting them. It is therefore preferable to use this method rather than attempting to this manually.
SelectElement is a convenient method that will clear the selection, select the new element, and give it the focus too. This is the equivalent of navigating to a row or cell with the keyboard, without control or shift held down.
SelectedElementCount returns the number of elements in the current selection.
SelectionChanged is an event that is raised when the selection changes in a grid. The arguments passed to the event include which grid raised the event, in the case where nested grids are being used.