%@ Page language="c#" AutoEventWireup="false" %>
SandGrid User Guide
Working with Rows
A row is responsible for obtaining data specific to any cell (i.e. under any column) and also for persisting that data. It is therefore the most popular extensibility point for SandGrid, since inheriting from it you can avoid the overhead of having to manually populate it with cells and instead dynamically obtain data from wherever you like. Rows are not always visible; they can belong to a group which is not expanded, or to a parent row which is not expanded, or be explicitly filtered out of view.
Rows can have a visible header, and when the header is visible a degree of user interaction is possible with it.
When checkboxes have been enabled in the grid by setting the CheckBoxes property to true, each row will have a checkbox. The user is free to toggle this value themselves, and when they do so the BeforeCheck and AfterCheck events are raised. The operation can be cancelled in the former event. The CheckState propery of the row represents the checked state and can be changed programmatically where needed.
Every row has a Height property. The default value of this property is derived from the height of the system default control font, therefore scaling up correctly when large fonts or high DPI is enabled. If you choose to use different row heights, ensure that you take these factors into account when specifying them.
Automatic sizing of rows is possible by setting the Height property to zero. When doing this it is important to be aware that there is a speed penalty for doing so; whenever data changes every cell in the row will need to be re-measured in order to calculate the height of the row overall. It is not recommended that you use automatic sizing of rows except for small sets of data.
If the AllowRowResize property is set to true and row headers are visible, the user can resize rows. This is generally useful in spreadsheet-type scenarios where they will be entering data themselves and there is a need to adjust the amount of room available.
We have already discussed how adding rows to the Rows collection property of the grid populates the grid. In addition, rows can be added to other rows via the NestedRows collection property on every row. This can be done recursively to create tree-like structures of visible data. When a row is a child of another row, its data is still divided into the same columns because the row is considered part of the same grid.
When a tree structure is established by having certain rows as children of other rows, the user can expand and collapse the tree if the ShowTreeButtons property of the grid is set. This can also be done programmatically using the Expanded property of a row. Tree lines are drawn to show the relationship of rows to other rows, unless the ShowTreeLines property of the grid has been set to false. When the expansion of a row is triggered the BeforeExpand and AfterExpand events are raised on the grid. When it is collapsed, the BeforeCollapse and AfterCollapse events are raised.
Sometimes you will want to populate a tree on the fly as it is expanded, as an optimization. SandGrid supports a ContentsUnknown boolean property for rows, and if set, a plus button is shown next to the row even if it has not yet been populated with child rows. When the plus button is clicked the BeforeExpand event is fired as normal, and in the handler for the event you can run special code to populate the row with child rows if that property is set - and then toggle the property to false. This useful property prevents you having to implement a solution where a placeholder row is used instead.
Each row in a grid can have a checkbox displayed in the primary column. To enable this set the CheckBoxes property of your grid to true. The checkbox in a row cannot be automatically bound to any property on your datasource but you can update it manually with the Checked or CheckState property of each row.
The user is also free to check and uncheck any row. When they click in the box, the BeforeCheck event is raised on the grid. If the handler for this event does not cancel the event the Checked property is toggled and finally the AfterCheck event is raised on the grid.
SandGrid does not support an interactive method of the user filtering rows. However, advanced consumers of the grid may with to dynamically change the visibility of rows depending on the state of other UI in their application, where grouping and collapsing of groups is not sufficient.
We support SetFilteredOut and GetFilteredOut methods on GridRow to achieve this.
We provide one specialised kind of row in SandGrid: NestedGridRow. This is a normal row in that it can be added to any grid, directly or as a child of another row.
A nested grid row does not display any data from its parent grid. Instead, it hosts an entirely separate grid, starting from the primary column of the parent grid and stretching as far as it needs to, to accommodate the nested grid. The child grid is exposed with the NestedGrid property and it is a fully-featured grid, with its own Rows and Columns collection properties and the same means of populating it as a regular top-level grid.
When using data binding with relationships, SandGrid automatically creates nested grids when it discovers relationships in your data that lead to expansions on top-level data being possible. You can respond to the DataBindingComplete event to discover when data binding has finished (the handler is passed the grid so can determine whether it's a nested or top-level grid) to perform such actions as customising the newly-generated nested child, hiding columns etc.
You will notice that all events raised by SandGrid include the grid that raised the event in their arguments. Obviously you only need to check this when using nested grids.