<%@ Page language="c#" AutoEventWireup="false" %> SandGrid Documentation

SandGrid User Guide


Back to Table of Contents


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 distinct from the focus but they typically go hand in hand in most data display controls, especially with user interaction with the grid. In the case of nested grids, each grid has its own independent selection. By default multiple selection is enabled, but this can be turned off with the AllowMultipleSelection property of the grid. We also support a HideSelection property that hides the selection in grids that do not have the focus.

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, columns and group headings. Clicking and dragging in an empty area of the grid will generate a "rubber band" that you can draw out to enclose any elements you like, which will become selected.

When you focus a nested grid row, a narrow focus bar on the left of the nested grid indicates the row has the focus. From this position you can press the right arrow key to move into the nested grid, where the directional keys work as expected within the confines of that grid. Pressing the left arrow moves back out of the nested grid to the row hosting it.

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 the user clicks on the grid and navigates using the keyboard. Cell selection is only possible in a grid that actually contains GridCell objects; if you are using virtual rows it cannot be used.

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 of the row. Highlighting of only the contents of the primary column is usually used in TreeView applications of the grid, or to approximate a ListView with FullRowSelect set to false.

Selectable Elements

Any GridElement-derived class is selectable, and this includes rows, columns, cells and group headings. Clicking on a row will either select the row or the cell under the cursor, depending on the selection granularity (see above). A collection of the selected elements is exposed via the SelectedElements property. These could be instances of any GridElement-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 SelectedElements.GetCells 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

To select a row, cell or column, simply set its Selected property to true. This very easy method of controlling what is selected can only be used for elements present in a grid. 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:

InnerGrid.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, and is the best way to enforce a single-element selection.

InnerGrid.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.

SelectedElements.Clear ensures that no element is selected, using an optimized codepath much faster than looping through all selected elements unselecting them.

SelectedElements.Count returns the number of elements in the current selection.

SandGrid.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, which you will need to know in the case where nested grids are being used.

Operating on the Selection

When the selection changes, either programmatically or because the user did something, often you will need to analyse it and do something with the results. The SelectedElements collection exists for this purpose. It is read-only and whenever its contents change the SelectionChanged event of the grid is raised.

There are multiple types of object that could conceivably be held in the selection: GridRow, GridCell, GridColumn and GridGroup. In the simple case the user will be selecting a row, and so it is a simple matter to quickly analyse the selection to ensure it is holding one item and then test the item to see if it's a GridRow.

if (sandGrid1.SelectedElements.Count == 1)
	GridRow selectedRow = sandGrid1.SelectedElements[0] as GridRow;
	if (selectedRow != null)
		// Do something with the row

The other common scenario is where you need to obtain a collection of cells encompassed by the selection. If the user has selected a column or a row, you may only be interested in the cells within that selection, not the column or row itself. A spreadsheet-type application would certainly be like this. We provide the GetCells method to always return an array of cells no matter what items are in the selection. The following example would make all selected cells red, regardless of whether cells, rows or columns are directly selected.

foreach (GridCell cell in sandGrid1.SelectedElements.GetCells())
	cell.ForeColor = Color.Red;

Next: Specialised Columns