ColumnView.CustomUnboundColumnData Event

Fires for all cells of visible unbound columns. Allows you to manually supply data to these cells, and save values entered by users at runtime.

Namespace: DevExpress.XtraGrid.Views.Base

Assembly: DevExpress.XtraGrid.v23.2.dll

NuGet Packages: DevExpress.Win.Grid, DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Data")]
public event CustomColumnDataEventHandler CustomUnboundColumnData

VB.NET

<DXCategory("Data")>
Public Event CustomUnboundColumnData As CustomColumnDataEventHandler

Event Data

The CustomUnboundColumnData event's data class is CustomColumnDataEventArgs. The following properties provide information specific to this event:

Property	Description
Column	Gets the unbound column currently being processed.
IsGetData	Inherited from UnboundColumnDataEventArgs.
IsSetData	Inherited from UnboundColumnDataEventArgs.
ListSourceRowIndex	Gets the current row’s index in the data source.
Row	Gets the currently processed row.
Value	Inherited from UnboundColumnDataEventArgs.
ValueType	Gets the type of data stored in the unbound column.

Remarks

The CustomUnboundColumnData event fires only for visible unbound columns. It fires in two cases:

• When the Grid Control is loaded, it raises the CustomUnboundColumnData event to populate unbound columns. The event’s IsGetData parameter returns true, and the IsSetData parameter returns false. Assign a custom value for the currently processed cell to the event’s Value parameter.

• When a user changes an unbound column’s cell data. In this case, the event’s IsSetData parameter returns true, and the IsGetData parameter returns false. Read the Value parameter to get the modified cell value, and save this value to a source.

For a column that owns the currently processed cell, use the CustomColumnDataEventArgs.Column parameter. To identify the row, use the CustomColumnDataEventArgs.ListSourceRowIndex or CustomColumnDataEventArgs.Row parameter.

Note

If you need to get or set specific cell values while handling the CustomUnboundColumnData event, use methods provided by the bound data source. The event’s Row and ListSourceRowIndex parameters allow you to identify the current data row. To get values in a specific row in the data source, you can use the ColumnView.GetListSourceRowCellValue method or methods provided by row objects.

Note

The CustomUnboundColumnData event fires for each cell. However, due to the Grid control’s data processing algorithms, this event may fire multiple times for each cell. The grid control does not cache data you supply on the CustomUnboundColumnData event. If these data operations take too long, you need to manually cache data.

This event allows you to supply cell values only. Your CustomUnboundColumnData event handler must not dispose of the control’s data source, or modify column settings, the control’s layout and the object model.

Note

Server Mode does not support sorting, grouping, filtering, and summary calculation for unbound columns that receive cell values on the CustomUnboundColumnData event. These features are still supported for unbound columns that are populated with expressions (see GridColumn.UnboundExpression).

Refer to the Unbound Columns topic for more information.

Example 1

In the following example, it is assumed that the Grid Control is bound to a table that contains the “Quantity”, “UnitPrice”, and “Discount” columns. The code below adds an unbound column that calculates the total order amount according to the following expression: Quantity * UnitPrice * (1-Discount).

C#

using DevExpress.XtraGrid.Views.Base;
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.XtraGrid.Columns;

private void Form1_Load(object sender, EventArgs e) {
    // ...
    gridControl1.ForceInitialize();

    // Create an unbound column.
    GridColumn unboundColumn = gridView1.Columns.AddField("Total");
    unboundColumn.VisibleIndex = gridView1.Columns.Count;
    unboundColumn.UnboundDataType = typeof(decimal);
    // Disable column edit operations.
    unboundColumn.OptionsColumn.AllowEdit = false;
    // Specify format settings.
    unboundColumn.DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric;
    unboundColumn.DisplayFormat.FormatString = "c";
    // Customize appearance settings.
    unboundColumn.AppearanceCell.BackColor = Color.FromArgb(179, 226, 221);
}

// Return the total amount for a specific row.
decimal getTotalValue(GridView view, int listSourceRowIndex) {
    decimal unitPrice = Convert.ToDecimal(view.GetListSourceRowCellValue(listSourceRowIndex, "UnitPrice"));
    decimal quantity = Convert.ToDecimal(view.GetListSourceRowCellValue(listSourceRowIndex, "Quantity"));
    decimal discount = Convert.ToDecimal(view.GetListSourceRowCellValue(listSourceRowIndex, "Discount"));
    return unitPrice * quantity * (1 - discount);
}

// Specify data for the Total column.
private void gridView1_CustomUnboundColumnData(object sender, CustomColumnDataEventArgs e) {
   GridView view = sender as GridView;
   if (e.Column.FieldName == "Total" && e.IsGetData) e.Value = 
     getTotalValue(view, e.ListSourceRowIndex);
}

VB.NET

Imports DevExpress.XtraGrid.Views.Base
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.XtraGrid.Columns

Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
    ' ...
    GridControl1.ForceInitialize()

    ' Create an unbound column.
    Dim unboundColumn As GridColumn = GridView1.Columns.AddField("Total")
    unboundColumn.VisibleIndex = GridView1.Columns.Count
    unboundColumn.UnboundDataType = GetType(Decimal)
    ' Disable column edit operations.
    unboundColumn.OptionsColumn.AllowEdit = False
    ' Specify format settings.
    unboundColumn.DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric
    unboundColumn.DisplayFormat.FormatString = "c"
    ' Customize appearance settings.
    unboundColumn.AppearanceCell.BackColor = Color.FromArgb(179, 226, 221)

End Sub

' Return the total amount for a specific row.
Private Function getTotalValue(view As GridView, listSourceRowIndex As Integer) As Decimal
    Dim unitPrice As Decimal = Convert.ToDecimal(view.GetListSourceRowCellValue(listSourceRowIndex, "UnitPrice"))
    Dim quantity As Decimal = Convert.ToDecimal(view.GetListSourceRowCellValue(listSourceRowIndex, "Quantity"))
    Dim discount As Decimal = Convert.ToDecimal(view.GetListSourceRowCellValue(listSourceRowIndex, "Discount"))
    Return unitPrice * quantity * (1 - discount)
End Function

' Specify data for the Total column.
Private Sub GridView1_CustomUnboundColumnData(ByVal sender As Object,
ByVal e As CustomColumnDataEventArgs) Handles GridView1.CustomUnboundColumnData
    Dim view As GridView = TryCast(sender, GridView)
    If e.Column.FieldName = "Total" AndAlso e.IsGetData Then
        e.Value = getTotalValue(view, e.ListSourceRowIndex)
    End If
End Sub

Example 2

GridView does not cache values of an unbound column, because it is impossible to determine when the cache should be cleared automatically. GridView displays only values supplied by the CustomUnboundColumnData event. So, to display a specific value in a cell, you need to pass a corresponding value to the e.Value parameter based on the processed column and row. What you return as the e.Value parameter is what is displayed in GridView. Each time a cell needs to be updated, the CustomUnboundColumnData event is called. This example demonstrates how a simple caching mechanism can be implemented. In this project, you can manipulate GridView data (for example, sort, delete, and add records). This is because values of the ID column are used as key values. This column is read-only and contains only unique values, so rows can always be identified.

You can also use the GridColumn.UnboundExpression property to specify an unbound expression. Please refer to the Unbound Columns help topic for additional information.

View Example

Form1.cs

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using DevExpress.XtraGrid.Columns;

namespace WindowsApplication1
{
    public partial class Form1 : Form
    {
        private DataColumn _KeyField;
        private DataTable _Tbl;
        private MyCache _Cache = new MyCache("ID");
        private DataTable CreateTable(int RowCount)
        {
            _Tbl = new DataTable();
            _KeyField = _Tbl.Columns.Add("ID", typeof(int));
            _KeyField.ReadOnly = true;
            _KeyField.AutoIncrement = true;
            _Tbl.Columns.Add("Name", typeof(string));
            _Tbl.Columns.Add("Number", typeof(int));
            _Tbl.Columns.Add("Date", typeof(DateTime));
            for (int i = 0; i < RowCount; i++)
                _Tbl.Rows.Add(new object[] { null, String.Format("Name{0}", i), 3 - i, DateTime.Now.AddDays(i) });
            return _Tbl;
        }

        public Form1()
        {
            InitializeComponent();
            gridControl1.DataSource = CreateTable(20);
            CreateUnboundColumn();
        }
        private void CreateUnboundColumn()
        {
            GridColumn col = gridView1.Columns.AddVisible("Unbound", "Unbound column");
            col.UnboundDataType = typeof(string);
        }

        private void gridView1_CustomUnboundColumnData(object sender, DevExpress.XtraGrid.Views.Base.CustomColumnDataEventArgs e)
        {
            if (e.IsGetData)
                e.Value = _Cache.GetValue(e.Row);
            if (e.IsSetData)
                _Cache.SetValue(e.Row, e.Value);
        }
    }
}

MyCache.cs

using System;
using System.Collections.Generic;
using System.Data;

namespace WindowsApplication1
{
    public class MyCache
    {

        private readonly string _KeyFieldName;
        Dictionary<object, object> valuesCache = new Dictionary<object, object>();

        public MyCache(string keyFieldName)
        {
            _KeyFieldName = keyFieldName;            
        }

        public object GetKeyByRow(object row)
        {
            return (row as DataRowView)[_KeyFieldName];
        }


        public object GetValue(object row)
        {
            return GetValueByKey(GetKeyByRow(row));
        }                                               

        public object GetValueByKey(object key)
        {
            object result = null;
            valuesCache.TryGetValue(key, out result);
            return result;
        }


        public void SetValue(object row, object value)
        {
            SetValueByKey(GetKeyByRow(row), value);
        }

        public void SetValueByKey(object key, object value)
        {
            valuesCache[key] = value;
        }
    }
}

Form1.vb

Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Text
Imports System.Windows.Forms
Imports DevExpress.XtraGrid.Columns

Namespace WindowsApplication1
    Partial Public Class Form1
        Inherits Form
        Private _KeyField As DataColumn
        Private _Tbl As DataTable
        Private _Cache As New MyCache("ID")
        Private Function CreateTable(ByVal RowCount As Integer) As DataTable
            _Tbl = New DataTable()
            _KeyField = _Tbl.Columns.Add("ID", GetType(Integer))
            _KeyField.ReadOnly = True
            _KeyField.AutoIncrement = True
            _Tbl.Columns.Add("Name", GetType(String))
            _Tbl.Columns.Add("Number", GetType(Integer))
            _Tbl.Columns.Add("Date", GetType(DateTime))
            For i As Integer = 0 To RowCount - 1
                _Tbl.Rows.Add(New Object() { Nothing, String.Format("Name{0}", i), 3 - i, DateTime.Now.AddDays(i) })
            Next i
            Return _Tbl
        End Function

        Public Sub New()
            InitializeComponent()
            gridControl1.DataSource = CreateTable(20)
            CreateUnboundColumn()
        End Sub
        Private Sub CreateUnboundColumn()
            Dim col As GridColumn = gridView1.Columns.AddVisible("Unbound", "Unbound column")
            col.UnboundDataType = GetType(String)
        End Sub

        Private Sub gridView1_CustomUnboundColumnData(ByVal sender As Object, ByVal e As DevExpress.XtraGrid.Views.Base.CustomColumnDataEventArgs) Handles gridView1.CustomUnboundColumnData
            If e.IsGetData Then
                e.Value = _Cache.GetValue(e.Row)
            End If
            If e.IsSetData Then
                _Cache.SetValue(e.Row, e.Value)
            End If
        End Sub
    End Class
End Namespace

MyCache.vb

Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic
Imports System.Data

Namespace WindowsApplication1
    Public Class MyCache

        Private ReadOnly _KeyFieldName As String
        Private valuesCache As New Dictionary(Of Object, Object)()

        Public Sub New(ByVal keyFieldName As String)
            _KeyFieldName = keyFieldName
        End Sub

        Public Function GetKeyByRow(ByVal row As Object) As Object
            Return (TryCast(row, DataRowView))(_KeyFieldName)
        End Function


        Public Function GetValue(ByVal row As Object) As Object
            Return GetValueByKey(GetKeyByRow(row))
        End Function

        Public Function GetValueByKey(ByVal key As Object) As Object
            Dim result As Object = Nothing
            valuesCache.TryGetValue(key, result)
            Return result
        End Function


        Public Sub SetValue(ByVal row As Object, ByVal value As Object)
            SetValueByKey(GetKeyByRow(row), value)
        End Sub

        Public Sub SetValueByKey(ByVal key As Object, ByVal value As Object)
            valuesCache(key) = value
        End Sub
    End Class
End Namespace

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the CustomUnboundColumnData event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

winforms-grid-add-radio-group-column/CS/Helper/GridRadioGroupColumnHelper.cs#L69

{
    _GridView.CustomUnboundColumnData += _GridView_CustomUnboundColumnData;
}

winforms-grid-multiple-row-selection-web-style-checkboxes/CS/E1271/CheckMarkSelection.cs#L132

view.CustomDrawGroupRow += new RowObjectCustomDrawEventHandler(View_CustomDrawGroupRow);
view.CustomUnboundColumnData += new CustomColumnDataEventHandler(view_CustomUnboundColumnData);
view.KeyDown += new KeyEventHandler(view_KeyDown);

winforms-grid-display-summary-calculated-over-detail-rows-in-master-row/CS/WindowsApplication59/Form1.cs#L26

    col.Visible = true;
    gridView1.CustomUnboundColumnData+=new DevExpress.XtraGrid.Views.Base.CustomColumnDataEventHandler(gridView1_CustomUnboundColumnData);
}

winforms-grid-tokenedit-in-unbound-column/CS/Form1.cs#L58

gridView.Columns.Add(col);
gridView.CustomUnboundColumnData += OnGridViewCustomUnboundColumnData;
col.ColumnEdit = tokenEditRep;

VB.NET

winforms-grid-add-radio-group-column/VB/Helper/GridRadioGroupColumnHelper.vb#L70

Private Sub InitGridView()
    AddHandler _GridView.CustomUnboundColumnData, AddressOf _GridView_CustomUnboundColumnData
End Sub

winforms-grid-multiple-row-selection-web-style-checkboxes/VB/E1271/CheckMarkSelection.vb#L160

AddHandler view.CustomDrawGroupRow, New RowObjectCustomDrawEventHandler(AddressOf View_CustomDrawGroupRow)
AddHandler view.CustomUnboundColumnData, New CustomColumnDataEventHandler(AddressOf view_CustomUnboundColumnData)
AddHandler view.KeyDown, New KeyEventHandler(AddressOf view_KeyDown)

winforms-grid-display-summary-calculated-over-detail-rows-in-master-row/VB/WindowsApplication59/Form1.vb#L22

    col.Visible = True
    AddHandler gridView1.CustomUnboundColumnData, New DevExpress.XtraGrid.Views.Base.CustomColumnDataEventHandler(AddressOf gridView1_CustomUnboundColumnData)
End Sub

winforms-grid-tokenedit-in-unbound-column/VB/Form1.vb#L55

gridView.Columns.Add(col)
AddHandler gridView.CustomUnboundColumnData, AddressOf OnGridViewCustomUnboundColumnData
col.ColumnEdit = tokenEditRep

winforms-grid-display-icons-in-data-cells/VB/Form1.vb#L157

AddHandler gridView1.CustomDrawCell, AddressOf GridView1_CustomDrawCell
AddHandler gridView1.CustomUnboundColumnData, AddressOf GridView1_CustomUnboundColumnData
Dim checkEdit As RepositoryItemCheckEdit = TryCast(gridControl1.RepositoryItems.Add("CheckEdit"), RepositoryItemCheckEdit)