KB Article T906256
Visible to All Users

Show Values from External Sources. Calculated Field Values. Unbound Mode - WinForms Cheat Sheet

Other DevExpress WinForms Cheat Sheets


DevExpress Data-Aware controls (Data Grid, Tree List, Gantt Control, Scheduler, Vertical Grid, etc.) display data from a bound data source as-is. It means that you can use your data source's API to shape (sort, filter, combine multiple sources into one, etc.) data before binding a DevExpress control to it.

If shaping data on a data source level is not an option, use Unbound Columns (Unbound Fields, Unbound Rows):

Component Approach
Data Grid (All Views) Unbound Columns
Tree List, Gantt Control Unbound Columns
Vertical Grid Unbound Rows
Scheduler Custom Fields
Pivot Grid Unbound Fields
PropertyGridControl CustomPropertyDescriptors

Populate Unbound Columns and Rows

Unbound columns and rows obtain their data in one of the following ways:

  • by evaluating an UnboundExpression. This method best suites scenarios when you need to display data calculated from other column (row) values. Unbound columns (rows) that use expressions are read-only.
  • via the ~CustomUnboundColumnData event. This method allows you to assign any custom data in cells.

Since unbound columns and rows are not connected to a data source, a data-aware control does not store their values. You need to save the values of these columns'/rows' cells manually.

API:

Component Expression (read only) Event Data Type
Data Grid GridColumn.UnboundExpression ColumnView.CustomUnboundColumnData GridColumn.UnboundDataType
Tree List, Gantt Control TreeListColumn.UnboundExpression TreeList.CustomUnboundColumnData TreeListColumn.UnboundDataType
Vertical Grid BaseRow.Properties.UnboundExpression VGridControl.CustomUnboundData RowProperties.UnboundDataType
Pivot Grid PivotGridField.UnboundExpression PivotGrid.CustomUnboundFieldData PivotGridFieldBase.UnboundType

Unbound Sources

To use data-aware controls in unbound mode you can connect them to an UnboundSource. The idea of this source is similar to the idea of Unbound Columns - handle the UnboundSource.ValueNeeded and UnboundSource.ValuePushed events to obtain data from your data storage, save modified data back, and call UnboundSource.Add, UnboundSource.Move, UnboundSource.InsertAt, UnboundSource.RemoveAt and other methods to manage the data and notify the bound control that the data has changed.


Examples

How to show data from different tables, combine multiple data sources into a single data source?

Add the required number of ~UnboundColumns and populate them in the ~CustomUnboundColumnData event handler.


How to calculate column values using other columns' values?

Add a new ~UnboundColumn and then either specify its ~UnboundExpression or handle the ~.CustomUnboundColumnData event to populate this column with data manually.


How to convert and display data source values of one type in a column of another type, e.g. display string or numeric values in a DateTime column?

Use Unbound Columns to accomplish this task. Add a new ~UnboundColumn, set its UnboundDataType property to the required type and handle the ~.CustomUnboundColumnData event. In this event handler, convert values from the data source to the values of the required type. For instance, convert values stored in the string or numeric format to DateTime values:

Code Example
C#
string stringDateFieldName = "DateString"; //hide the stringDate column this.stringDateColumn.Visible = false; //set the UnboundDataType property of an unbound column to the DateTime type this.gridView1.Columns["Date"].UnboundDataType = typeof(DateTime); //handle the CustomUnboundColumnData event this.gridView1.CustomUnboundColumnData += GridView1_CustomUnboundColumnData; private void GridView1_CustomUnboundColumnData(object sender, DevExpress.XtraGrid.Views.Base.CustomColumnDataEventArgs e) { GridView view = sender as GridView; if (e.IsGetData) { //convert value of the stringDate field to a DateTime value string stringDate = view.GetListSourceRowCellValue(e.ListSourceRowIndex, stringDateFieldName).ToString(); e.Value = DateTime.Parse(stringDate); } else { //set value of the stringDate column to a DateTime value converted to a string string stringDate = e.Value.ToString(); view.SetRowCellValue(view.GetRowHandle(e.ListSourceRowIndex), stringDateFieldName, stringDate); } }

Since the type of the unbound column is correct, Grid will perform all data-aware operations (sorting, grouping, filtering) with values of this type. For instance, Grid will display the DateTime Excel Filter for the unbound column of the DateTIme type and filter this column by dates.


How to calculate individual cell values using a formula (expression)?

Data-aware controls (Gantt Control, Data Grid, Tree List, Vertical Grid, etc.) do not support value expressions for individual cells. Consider using our Spreadsheet control where each cell can include different types of cell values or formulas.


How to bind several columns to the same field in the data source? Can these columns display different values?

Data aware controls (Data Grid, Tree List, Gantt Control, Scheduler, Vertical Grid, etc.) require that each column has a unique data field. To overcome this limitation, create ~UnboundColumns and handle the ~CustomUnboundColumnData event to populate these columns with data manually. Data you pass can be retrieved from the same data field and formatted in any way your needs dictate.


How to display detail data in data-aware control's columns?

Only the Data Grid supports Master-Detail data representation. If, however, you don't need to display data as Master-Detail and need to show it in separate columns, or use a data-aware control that doesn't support master-detail mode, create several ~UnboundColumns and handle the ~CustomUnboundColumnData event to supply data to these columns from the master object.


How to bind a CheckBoxSelectorField to a field in a separate data source?

You can add a new ~UnboundColumn and handle the ~CustomUnboundColumnData event to store selection in a separate data source. Then set the CheckBoxSelectorField property to the FieldName of the unbound column.


Help us improve this article

Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.