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

SandGrid User Guide

Manipulating Data

Back to Table of Contents

Simple Sorting

SandGrid includes native sorting methods for manually populated data or virtual rows, and will use the sorting methods exposed by your data sources when databinding. These sort method are functionally rather different but the same APIs are used for controlling them.

When a column is clickable and its AutoSort property it set, the column is automatically sorted when its header is clicked. When single-column sorting is enabled (the default) clicking a column header sorts by that column, or reverses the sort order if already sorting by that column. When multi-column sorting is enabled, subsequently shift-clicking other column headers adds those columns to the sort too, in increasingly lower priority: the first column clicked is sorted first.

A simple API is used for simple sorting. The SortColumn property of the grid indicates the column being sorted, and the SortDirection property indicates whether it's being sorted in an adcending or descending order. Set the SortColumn property to a null reference to remove any sort from the grid. These properties can be set at design-time.

The current sort is indicated by the column(s) responsible, with a glyph in the header showing sort direction and optionally a shaded background too.

Advanced Sorting

To programmatically set a complicated multi-column sort, use the SetSort method. It accepts two corresponding arrays, one of the columns to use in the sort and one of their respective sort directions. Sorting is applied from the first column to the last. If you attempt to apply this type of sorting to a databound grid whose datasource that does not support it, SandGrid will fall back to simple sorting by the primary column.

Sorting cannot be performed by SandGrid natively when virtual mode is enabled, since that would require loading all data into the grid. You can still sort a large virtual mode grid, though: respond to the SortChanged event and perform the relevant sorting on your large datasource, then force SandGrid to repopulate all virtual rows by calling the Clear method on the Rows collection. If you need to, you can directly change the sort indicators displayed in each column header with the SetSortIndicator method.

Grouping

Grouping is actually an extension to sorting. To enable grouping by values in a column, set the GroupColumn propery on the grid. The GroupDirection property can be used to dictate direction. When a group column is specified it always takes precedence as the first sort column, with the specified sort column following. For instance, if your group column is a date column and sort column is a string column, rows are sorted into dates first, grouped, then sorted by the string within the date groups.

SandGrid supports collapsible group headings. When grouping is enabled, group headings are displayed that typically show the name of the group and sometimes show summary information about the rows in the group. If the AllowGroupCollapse property in the grid is set to true, the headings will also display an expand/collapse button that can be toggled by the user. A list of the current group headings in the grid can be enumerated over programmatically with the Groups property. When a reference to a group heading is obtained it can then be expanded or collapsed, or you can get a list of rows that lie within it.

There is more than one behaviour for user interaction with a group heading. This is determined by the GroupHeadingClickBehavior property of the grid. Possible values are None, SelectAll (where all owned rows are selected when the heading is clicked), ExpandCollapse (where the expansion is toggled) and Select (where the heading itself is selected).

Formatting

This is the process the raw data in a cell goes through before it arrives at its destination, usually the screen. A value will always be formatted before it gets to the screen or other destination. The term refers to data formatting rather than graphical formatting, which is covered elsewhere.

The ValueFormatting event of the SandGrid control is fired first in the formatting process. This event will give you the row and column intersection, the value itself and the desired destination type. You can then modify the value if required to assist SandGrid in the transformation. In most cases the destination type is String - for display on screen and exporting. Sometimes an editor will request a different type, though. For example, the SandGridDateTimeEditor requests a DateTime value.

After the event has been fired SandGrid checks the type of value it has, and if its type is the same as the destination type formatting ends there. If some conversion needs to happen, though, the column's FormatValue method is called and it's up to the column to perform any formatting. This includes converting a null value to whatever null representation is in effect (usually ""). The default GridColumn class simply calls the ToString method of the value.

Although the term Formatting suggests transformation of one datatype to another, the mechanism can also be used for simple substitution of values. Perhaps you want a completely different value displayed from what is actually stored. Formatting events are the key to making this happen, as they are raised regardless of whether the underlying datatype matches the destination type.

Parsing

This is the opposite process to formatting, and is used much less frequently. Whereas formatting happens every thing a value is drawn, parsing happens when a formatted value obtained from an editor needs to be parsed back into its native form for storage.

The ValueParsing event of the SandGrid control is again called first, with the formatted value straight from the editor. This gives the host application a chance to transform the value to the required destination type, which will be the datatype the column holds.

After the event has been fired the type is checked, and if it has already been converted the process stops. Otherwise, the ParseValue method of the column is called. In the case of the GridIntegerColumn, for example, the method will call int.Parse if it is passed a string. A null value will be passed straight through.

Next: Selection