SandGrid User Guide
Introduction
Goals
SandGrid is a flexible data presentation control. It encapsulates most of the common data presentation formats and exposes hooks for a great deal of control over its behavior. Its hierarchical nature means it can replace the ListView, TreeView, DataGridView and other data list controls.
Grids and Elements
The core of SandGrid's functionality is in the InnerGrid class. This class is distinct from the actual presentation of data to enable the advanced nested grids feature. It is typically exposed by the SandGrid control itself, which always has one primary InnerGrid and directly exposes its properties. For this reason if you do not have to deal with nested grids you do not have to be aware there is a distinction between the SandGrid control and the grid(s) within.
Everything in a grid is derived from the GridElement class. This class is responsible for processing its own mouse messages and measuring and laying out its contents. This means that by deriving from elements one can cleanly extend their behavior, and this is taken advantage of with the virtual rows feature.
Every element knows its bounds onscreen and can request that it be redrawn or remeasured. It has its own Font settings, which automatically inherit from its logical parent in the grid. It knows about the grid in which is it situated and therefore can always call on its methods and properties.
Columns
All data display starts with the columns present in the grid. Because the grid is primarily designed to show tabular data, the columns are the starting point for formatting, parsing, and eventually displaying all data. The Columns collection of a grid exposes its columns, and you can add and remove them as you please. The GridColumn class is the standard column type and is the one you will use most, but there are several derived classes that extend it to operate better on certain types of data.
When using SandGrid you will usually either let the grid populate the Columns collection itself (in databinding) or will populate them manually, at design time or programmatically. There is always one column designated as the Primary Column. This is usually the first column added, and it is the contents of this column that are indented to show nesting of rows.
GridBooleanColumn offers a choice of formatting for boolean values. It can show a more friendly "Yes/No" display or can show a graphical check mark next to true values.
GridConditionalImageColumn is primarily used in data binding. It displays a different image depending on whether the value it encounters is true or false. You do not have to have an image for both cases. For example, if your were binding to a list of email messages, you might have a column that shows one of two images depending on whether the message has been read.
GridDateTimeColumn is specialized for DateTime values, and allows control over the formatting they get when displayed onscreen, e.g. short date, long date and custom formatting. Also when grouping by one of these columns you will see a friendly display of dates, such as in Outlook. It will show "Today", "Yesterday", "Last Week" instead of raw dates.
GridForeignKeyColumn is for use in binding scenarios when binding to tables in a DataSet. It will look up a friendly value to display from one table when it encounters a foreign key in the data it is presenting. This also works in reverse, and the column automatically shows a dropdown list of potential values when the editor is invoked.
GridIntegerColumn deals with integer values and allows standard format strings to be specified for presentation.
GridProgressBarColumn also deals with integer values but displays them as progress between a minimum and a maximum value defined at the column level. This is useful for displays of the progress of multiple items, for instance in a download or upload manager.
Rows and Cells
To display data you need both columns and rows. Rows are in charge of obtaining and persisting data values, and columns are in charge of formatting them to be suitable for display and subsequently displaying them. This architecture allows for extensibility at various levels.
Cells are only used when data is being entered in the control manually, or in databinding situations when selection on a per-cell basis is required. Cells are not required to view data in SandGrid, since rows and columns cooperate with each other to do everything required. In fact this is a performance and memory advantage.
When cells are needed they are added to the Cells collection of a row. They should match the columns with the same indices in the grid. For example, a GridDateTimeColumn will expect DateTime values so the obvious match is a GridDateTimeCell. Cells can specify their own formatting options.
When a data value is required the GetCellValue method is called on the row containing it. The row then either gets the value from the bound datasource, a cell, or some other location if virtual rows are being used.