Back to Devexpress

GridColumn.Caption Property

windowsforms-devexpress-dot-xtragrid-dot-columns-dot-gridcolumn-f44c75f7.md

latest15.1 KB
Original Source

GridColumn.Caption Property

Gets or sets the column’s display caption.

Namespace : DevExpress.XtraGrid.Columns

Assembly : DevExpress.XtraGrid.v25.2.dll

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

Declaration

csharp
[DefaultValue("")]
[DXCategory("Appearance")]
[XtraSerializableProperty]
public virtual string Caption { get; set; }
vb
<DXCategory("Appearance")>
<DefaultValue("")>
<XtraSerializableProperty>
Public Overridable Property Caption As String

Property Value

TypeDefaultDescription
StringString.Empty

A String value specifying the column’s display caption.

|

Remarks

In Grid Views, columns’ captions are displayed in column headers. In Card and Layout Views, captions identify individual card fields.

By default, the Caption property is set to an empty string. In this instance, a friendly caption is generated for a column based on its GridColumn.FieldName property. Friendly captions are generated adding SPACE characters between parts of the field name starting with uppercase letters. For example, if the field name is “CustomerName”, the display caption will be “Customer Name”. To override the default display caption, assign it to the Caption property.

In Layout Views, the actual display captions are generated according to the pattern specified by the LayoutView.FieldCaptionFormat property.

To return the actual captions in Layout Views, use the LayoutView.GetFieldCaption method, while in other Views, use the GridColumn.GetCaption method.

If the GridOptionsView.AllowHtmlDrawHeaders property is set to true , you can use HTML tags to format the GridColumn.Caption and GridBand.Caption. For detailed information, see HTML Text Formatting.

Example 1

The following example shows how to format the GridColumn.Caption using HTML tags. HTML formatting is enabled via the GridOptionsView.AllowHtmlDrawHeaders property. The image below shows the result:

csharp
gridColumn1.Caption = "Delivery
<b>Date</b>";

gridView1.OptionsView.AllowHtmlDrawHeaders = true;
gridView1.Appearance.HeaderPanel.Options.UseTextOptions = true;
gridView1.Appearance.HeaderPanel.TextOptions.WordWrap = DevExpress.Utils.WordWrap.Wrap;
vb
gridColumn1.Caption = "Delivery
<b>Date</b>"

gridView1.OptionsView.AllowHtmlDrawHeaders = True
gridView1.Appearance.HeaderPanel.Options.UseTextOptions = True
gridView1.Appearance.HeaderPanel.TextOptions.WordWrap = DevExpress.Utils.WordWrap.Wrap

Example 2

The following example displays a hyperlink in the header of the ‘Change’ grid column. The GridView.HyperlinkClick event is handled to respond to a link click — which toggles the display mode of this column’s values.

csharp
private void Form1_Load(object sender, EventArgs e) {
    BindingList<Ticker> list = new BindingList<Ticker>();
    list.Add(new Ticker() { Symbol = "AVR", Price = 101.4m, AbsoluteChange = 2.3m });
    list.Add(new Ticker() { Symbol = "RVA", Price = 414.1m, AbsoluteChange = 3.2m });
    list.Add(new Ticker() { Symbol = "ARBV", Price = 532.7m, AbsoluteChange = -18.0m });

    gridControl1.DataSource = list;
    gridView1.OptionsView.AllowHtmlDrawHeaders = true;
    gridView1.OptionsBehavior.HyperlinkClickMode = DevExpress.Utils.Drawing.HyperlinkClickMode.CtrlClick;
    gridView1.HyperlinkClick += GridView1_HyperlinkClick;

    gridView1.Columns["AbsoluteChange"].Visible = false;
    gridView1.Columns["PercentageChange"].Visible = false;

    GridColumn changeColumn = gridView1.Columns.AddUnbound("Change", typeof(decimal));
    changeColumn.Visible = true;
    changeColumn.OptionsColumn.AllowEdit = false;
    updateChangeColumnDisplayMode();

    gridView1.Columns["Price"].DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric;
    gridView1.Columns["Price"].DisplayFormat.FormatString = "c2";
}

bool usePercentageFormat = false;

private void GridView1_HyperlinkClick(object sender, DevExpress.XtraGrid.Views.Grid.GridHyperlinkClickEventArgs e) {
    if (e.Link == "toggle-display-mode") {
        usePercentageFormat = !usePercentageFormat;
        updateChangeColumnDisplayMode();
    }
}

void updateChangeColumnDisplayMode() {
    GridColumn column = gridView1.Columns["Change"];
    if (column == null) return;
    column.DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric;
    if (usePercentageFormat) {
        column.Caption = "Change <a href=toggle-display-mode>(%)</a>";
        column.DisplayFormat.FormatString = "p2";
        // Display values from the PercentageChange field.
        column.UnboundExpression = "PercentageChange";
    }
    else {
        column.Caption = "Change <a href=toggle-display-mode>($)</a>";
        column.DisplayFormat.FormatString = "c2";
        // Display values from the AbsoluteChange field.
        column.UnboundExpression = "AbsoluteChange";
    }
}

public class Ticker {
    public string Symbol { get; set; }
    public decimal Price { get; set; }
    public decimal AbsoluteChange { get; set; }
    public decimal PercentageChange {
        get {
            if (Price > 0) return AbsoluteChange / Price;
            else return 0;
        }
    }
}
vb
Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
    Dim list As New BindingList(Of Ticker)()
    list.Add(New Ticker() With {
            .Symbol = "AVR",
            .Price = 101.4D,
            .AbsoluteChange = 2.3D
        })
    list.Add(New Ticker() With {
            .Symbol = "RVA",
            .Price = 414.1D,
            .AbsoluteChange = 3.2D
        })
    list.Add(New Ticker() With {
            .Symbol = "ARBV",
            .Price = 532.7D,
            .AbsoluteChange = -18D
        })

    GridControl1.DataSource = list
    GridView1.OptionsView.AllowHtmlDrawHeaders = True
    GridView1.OptionsBehavior.HyperlinkClickMode = DevExpress.Utils.Drawing.HyperlinkClickMode.CtrlClick
    AddHandler GridView1.HyperlinkClick, AddressOf GridView1_HyperlinkClick

    GridView1.Columns("AbsoluteChange").Visible = False
    GridView1.Columns("PercentageChange").Visible = False

    Dim changeColumn As GridColumn = GridView1.Columns.AddUnbound("Change", GetType(Decimal))
    changeColumn.Visible = True
    changeColumn.OptionsColumn.AllowEdit = False
    updateChangeColumnDisplayMode()

    GridView1.Columns("Price").DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric
    GridView1.Columns("Price").DisplayFormat.FormatString = "c2"
End Sub

Private usePercentageFormat As Boolean = False

Private Sub GridView1_HyperlinkClick(sender As Object, e As DevExpress.XtraGrid.Views.Grid.GridHyperlinkClickEventArgs)
    If e.Link = "toggle-display-mode" Then
        usePercentageFormat = Not usePercentageFormat
        updateChangeColumnDisplayMode()
    End If
End Sub

Private Sub updateChangeColumnDisplayMode()
    Dim column As GridColumn = GridView1.Columns("Change")
    If column Is Nothing Then
        Return
    End If
    column.DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric
    If usePercentageFormat Then
        column.Caption = "Change <a href=toggle-display-mode>(%)</a>"
        column.DisplayFormat.FormatString = "p2"
        ' Display values from the PercentageChange field.
        column.UnboundExpression = "PercentageChange"
    Else
        column.Caption = "Change <a href=toggle-display-mode>($)</a>"
        column.DisplayFormat.FormatString = "c2"
        ' Display values from the AbsoluteChange field.
        column.UnboundExpression = "AbsoluteChange"
    End If
End Sub

Public Class Ticker
    Public Property Symbol() As String
    Public Property Price() As Decimal
    Public Property AbsoluteChange() As Decimal
    Public ReadOnly Property PercentageChange() As Decimal
        Get
            If Price > 0 Then
                Return AbsoluteChange / Price
            Else
                Return 0
            End If
        End Get
    End Property
End Class

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

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.

winforms-reporting-create-grid-based-report/CS/ConvertGridToReportExample/XtraReport1.cs#L27

csharp
{
    columnArrayList.Add(gView.Columns[i].Caption);
}

XAF-how-to-add-an-unbound-column-to-gridlisteditor-to-execute-a-custom-action-for-a-record/CS/EFCore/ButtonInListEF/ButtonInListEF.Win/Controllers/SimpleBusinessActionGridListViewController.cs#L58

csharp
buttonColumn.UnboundType = UnboundColumnType.Boolean;
buttonColumn.Caption = ButtonColumnCaption;
buttonColumn.AppearanceHeader.TextOptions.HAlignment = HorzAlignment.Center;

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

csharp
column.FieldName = "CheckMarkSelection";
column.Caption = "Mark";
column.OptionsColumn.ShowCaption = false;

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

csharp
RadioGroupColumn.ColumnEdit = RadioRepositoryItem;
RadioGroupColumn.Caption = "Radio";
RadioGroupColumn.UnboundType = DevExpress.Data.UnboundColumnType.Boolean;

winforms-grid-display-text-editor-in-column-header/CS/WindowsApplication1/MyGridColumnRenameHelper.cs#L93

csharp
if (!IsEditing) return;
editedColumn.Caption = headerEdit.Text;
headerEdit.Hide();

winforms-reporting-create-grid-based-report/VB/ConvertGridToReportExample/XtraReport1.vb#L25

vb
If gView.Columns(i).Visible AndAlso gView.Columns(i).GroupIndex < 0 Then
    columnArrayList.Add(gView.Columns(i).Caption)
End If

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

vb
column.FieldName = "CheckMarkSelection"
column.Caption = "Mark"
column.OptionsColumn.ShowCaption = False

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

vb
RadioGroupColumn.ColumnEdit = RadioRepositoryItem
RadioGroupColumn.Caption = "Radio"
RadioGroupColumn.UnboundType = DevExpress.Data.UnboundColumnType.Boolean

winforms-grid-display-text-editor-in-column-header/VB/WindowsApplication1/MyGridColumnRenameHelper.vb#L89

vb
End If
editedColumn.Caption = headerEdit.Text
headerEdit.Hide()

See Also

AbsoluteIndex

CustomizationCaption

GetCaption()

GetTextCaption()

Columns

FieldCaptionFormat

GetFieldCaption(GridColumn)

AllowMultilineHeaders

AllowHtmlDrawHeaders

AllowHtmlCaptions

HTML-inspired Text Formatting

GridColumn Class

GridColumn Members

DevExpress.XtraGrid.Columns Namespace