Skip to main content

ColumnView.CustomUnboundColumnData Event

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

Namespace: DevExpress.XtraGrid.Views.Base

Assembly: DevExpress.XtraGrid.v22.1.dll

Declaration

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

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

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, 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 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 parameters.

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 provide on the CustomUnboundColumnData event. If these data operations take too long, you need to manually cache data.

This event allows you to provide cell values only. Your CustomUnboundColumnData event handler must not dispose of the control’s data source, modify column settings, the control’s layout and 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 document 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).

CD_UnboundColumns_example

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 the 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);
}

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 just displays values provided 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 a 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 perform all supported operations with GridView, such as sorting/deleting/adding records, and the unbound column will display proper values. 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 be always identified.

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

View Example

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);
        }
    }
}
See Also