Records

• May 18, 2022
• 9 minutes to read

The vertical grid arranges data into rows and columns. Rows correspond to fields in the underlying data source. Columns correspond to records. This topic explains how records are displayed in different layouts and how to customize their appearance.

Layouts

The vertical grid can display data in three different layouts:

• Multiple Records

  • The grid arranges records in multiple columns.
  • The horizontal scrollbar scrolls records.
  • The grid displays a vertical scrollbar if rows do not fit in height.

  

• Single Record

  • The grid displays only one record at a time.
  • The horizontal scrollbar flips records.
  • The grid displays a vertical scrollbar if rows do not fit in height.
  • The displayed record is automatically focused.

  

• Bands

  • The grid displays only one record at a time.
  • The horizontal scrollbar flips records.
  • The grid arranges the record in a band of columns if rows do not fit in height.
  • The displayed record is automatically focused.

  

Refer to the following topics for information on how to manage records in bound mode: Adding and Deleting Records and Focus and Scroll Records. Note that it is not possible to add, delete, or focus records in unbound mode.

Appearance

Use the following properties and events to customize records (columns):

• VGridControlBase.RecordWidth — gets or sets the column width.

• VGridControlBase.RecordsInterval — gets or sets the distance between columns.

  

• VGridControlBase.BandsInterval — gets or sets the distance between columns in a band.

  

• VGridControl.Appearance.RecordValue, VGridControl.Appearance.FocusedRecord and VGridControl.Appearance.FocusedCell — provide access to an element’s appearance settings.

  

• VGridControlBase.RecordCellStyle fires when a cell is about to be displayed and allows you to customize its appearance. Refer to the following topic for more information: Customizing Appearances of Individual Cells.
• VGridControlBase.CustomDrawRowValueCell fires when a cell is about to be displayed and allows you to draw the cell in a custom manner. Refer to the following topic for more information: Custom Painting.

Record Headers

In Multi-Record view mode (see VGridControl.LayoutStyle), Vertical Grid supports record headers in which you can display formatted field values, hyperlinks, and text. Use the OptionsView.ShowRecordHeaders property to enable record headers.

Run Demo: PC Market

You can specify record header content as follows:

• Set the record header format.
• Handle an event to dynamically supply record header text.
• Custom paint record headers.

Record Header Format

The VGridControl.RecordHeaderFormat property allows you to specify the format string used to generate header text for all records.

The record format supports the following elements:

• Static text.

• The syntax to insert the display values of text fields:

  {FieldName[,alignment]}

  The optional alignment setting is a signed integer that specifies the preferred width of the resulting string. See the following link for more information: Alignment Component.

  Examples:

  • {ModelPrice} — Returns the display text of the ‘ModelPrice’ row (field).
  • {CategoryID, 10} — Returns the display text of the ‘CategoryID’ row (field) with a 10-character requirement. If the length of the field’s display text is less than 10 characters, the resulting string is padded with leading spaces to meet this requirement.

• HTML-inspired formatting tags: b, i, size, href, image, br, and so on. Enable the OptionsView.AllowHtmlText setting to allow HTML tags.

  The br tag requires that you enable word wrap with the VGridControl.Appearance.RecordHeader.TextOptions.WordWrap setting.

  Do the following to allow users to click hyperlinks, and to respond to these actions:

  • Set the OptionsBehavior.HyperlinkClickMode property to Click or CtrlClick.
  • Handle the VGridControlBase.HyperlinkClick event to perform actions on hyperlink activation.

Example

The following format string displays a hyperlink, and values of the ‘ProcName’ and ‘ModelPrice’ fields in record headers.

C#

vGridControl1.OptionsView.AllowHtmlText = true;
vGridControl1.Appearance.RecordHeader.TextOptions.WordWrap = DevExpress.Utils.WordWrap.Wrap;
vGridControl1.RecordHeaderFormat = "<br><size=10><b>{ProcName}</b><br><br>" +
    "<size=12>{ModelPrice}</size><br><br>" +
    "<size=7><b><href=shoppingcart>ADD TO CART</href><br><br>";

VB.NET

VGridControl1.OptionsView.AllowHtmlText = True
VGridControl1.Appearance.RecordHeader.TextOptions.WordWrap = DevExpress.Utils.WordWrap.Wrap
VGridControl1.RecordHeaderFormat = "<br><size=10><b>{ProcName}</b><br><br>" &
    "<size=12>{ModelPrice}</size><br><br>" &
    "<size=7><b><href=shoppingcart>ADD TO CART</href><br><br>"

Example

In the following example, a Vertical Grid’s record headers contain hyperlinks that display employees’ e-mails. The VGridOptionsBehavior.HyperlinkClickMode property is set to CtrlClick to allow users to activate hyperlinks on a mouse click when the CTRL key is pressed down. The VGridControlBase.HyperlinkClick event handler starts a process that opens a clicked hyperlink.

C#

private void Form1_Load(object sender, EventArgs e) {
    BindingList<Message> list = new BindingList<Message>();
    list.Add(new Message() { Date = DateTime.Now, Email = "[e-mail]", From = "John Heart", PlainText = "Hello All   Please remember that I’ve rescheduled...", Subject = "DevAV Annual Performance Review" });
    list.Add(new Message() { Date = DateTime.Now, Email = "[e-mail]", From = "Violet Bailey", PlainText = "Good Day Morgan   I’ve been asked by the sales team...", Subject = "Artwork for packaging" });
    vGridControl1.DataSource = list;
    vGridControl1.OptionsView.ShowRecordHeaders = true;
    vGridControl1.OptionsView.AllowHtmlText = true;
    vGridControl1.RecordHeaderFormat = "<b>{From}</b><br><a href=mailto:{Email}>{Email}</a>";
    vGridControl1.Appearance.RecordHeader.TextOptions.WordWrap = DevExpress.Utils.WordWrap.Wrap;
    vGridControl1.RecordWidth = 150;
    vGridControl1.OptionsBehavior.HyperlinkClickMode = DevExpress.Utils.Drawing.HyperlinkClickMode.CtrlClick;
    vGridControl1.HyperlinkClick += VGridControl1_HyperlinkClick;
}

private void VGridControl1_HyperlinkClick(object sender, DevExpress.XtraVerticalGrid.Events.HyperlinkClickEventArgs e) {
    if (e.Link.StartsWith("mailto:"))
        System.Diagnostics.Process.Start(e.Link);
}

public class Message {
    public DateTime Date { get; set; }
    public string From { get; set; }
    public string Email { get; set; }
    public string Subject { get; set; }
    public string PlainText { get; set; }
}

VB.NET

Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
    Dim list As New BindingList(Of Message)()
    list.Add(New Message() With {.Date = DateTime.Now, .Email = "[e-mail]", .From = "John Heart", .PlainText = "Hello All   Please remember that I’ve rescheduled...", .Subject = "DevAV Annual Performance Review"})
    list.Add(New Message() With {.Date = DateTime.Now, .Email = "[e-mail]", .From = "Violet Bailey", .PlainText = "Good Day Morgan   I’ve been asked by the sales team...", .Subject = "Artwork for packaging"})
    VGridControl1.DataSource = list
    VGridControl1.OptionsView.ShowRecordHeaders = True
    VGridControl1.OptionsView.AllowHtmlText = True
    VGridControl1.RecordHeaderFormat = "<b>{From}</b><br><a href=mailto:{Email}>{Email}</a>"
    VGridControl1.Appearance.RecordHeader.TextOptions.WordWrap = DevExpress.Utils.WordWrap.Wrap
    VGridControl1.RecordWidth = 150
    VGridControl1.OptionsBehavior.HyperlinkClickMode = DevExpress.Utils.Drawing.HyperlinkClickMode.CtrlClick
    AddHandler VGridControl1.HyperlinkClick, AddressOf VGridControl1_HyperlinkClick
End Sub

Private Sub VGridControl1_HyperlinkClick(ByVal sender As Object, ByVal e As DevExpress.XtraVerticalGrid.Events.HyperlinkClickEventArgs)
    If e.Link.StartsWith("mailto:") Then
        System.Diagnostics.Process.Start(e.Link)
    End If
End Sub

Public Class Message
    Public Property [Date]() As DateTime
    Public Property From() As String
    Public Property Email() As String
    Public Property Subject() As String
    Public Property PlainText() As String
End Class

Dynamically Specify Record Header Text

Handle the VGridControl.CustomRecordHeaderDisplayText event to dynamically supply display text for record headers. Use the DisplayText event parameter for this purpose.

The record header text you supply can contain HTML-inspired formatting tags if the OptionsView.AllowHtmlText setting is enabled.

Example

The following example handles the VGridControl.CustomRecordHeaderDisplayText event to assign different text to different record headers. Headers of records that correspond to out-of-stock products display the “Out of stock” string. Other headers display a product’s brand and model information formatted with HTML tags.

C#

vGridControl.OptionsView.ShowRecordHeaders = true;
vGridControl.OptionsView.AllowHtmlText = true;
vGridControl.Appearance.RecordHeader.TextOptions.WordWrap = WordWrap.Wrap;
//...
private void vGridControl_CustomRecordHeaderDisplayText(object sender, Events.CustomRecordHeaderDisplayTextEventArgs e) {
    VGridControl vGrid = sender as VGridControl;
    bool inStock = (bool)vGrid.GetCellValue("InStock", e.Record);
    if (inStock) {
        string maker = (string)vGrid.GetCellDisplayText(erTrademark.Properties, e.Record);
        string model = (string)vGrid.GetCellDisplayText(erName.Properties, e.Record);
        e.DisplayText = $"<size=+1>{maker}<br><size=+2><color=green><b>{model}</b>";
    }
    else
        e.DisplayText = "<color=gray>Out of stock</color>";
}

VB.NET

vGridControl.OptionsView.ShowRecordHeaders = True
vGridControl.OptionsView.AllowHtmlText = True
vGridControl.Appearance.RecordHeader.TextOptions.WordWrap = WordWrap.Wrap
'...
Private Sub VGridControl1_CustomRecordDisplayText(sender As Object, e As Events.CustomRecordDisplayTextEventArgs) Handles VGridControl1.CustomRecordDisplayText
    Dim vGrid As VGridControl = TryCast(sender, VGridControl)
    Dim inStock As Boolean = CBool(vGrid.GetCellValue("InStock", e.Record))

    If inStock Then
        Dim maker As String = CStr(vGrid.GetCellDisplayText(erTrademark.Properties, e.Record))
        Dim model As String = CStr(vGrid.GetCellDisplayText(erName.Properties, e.Record))
        e.DisplayText = $"<size=+1>{maker}<br><size=+2><color=green><b>{model}</b>"
    Else
        e.DisplayText = "<color=gray>Out of stock</color>"
    End If
End Sub

Custom Paint Record Headers

The VGridControl.CustomDrawRecordHeader event allows you to custom paint record headers.

Example

The following VGridControl.CustomDrawRecordHeader event handler paints the record header element using default settings, and then draws a rounded rectangle with text within the header.

See the following demo for the complete code:

Run Demo: PC Market

C#

void OnCustomDrawRecordHeader(object sender, Events.CustomDrawRecordHeaderEventArgs e) {
    //skip code...
    // Draw the record header element using default settings.
    e.DefaultDraw();
    // Set the 'Handled' parameter to true to indicate that no default processing is required 
    // after the event handler is complete.
    e.Handled = true;
    //...
    int dataSourceRowIndex = vGrid.GetDataSourceRecordIndex(e.Record);
    bool addedToCart = Orders.Contains(dataSourceRowIndex);
    var color = addedToCart ? DXSkinColors.FillColors.Success : DXSkinColors.FillColors.Question;
    e.Cache.FillRoundedRectangle(color, linkRect, new CornerRadius(9));
    using (var format = new StringFormat() { Alignment = StringAlignment.Center, LineAlignment = StringAlignment.Center })
    using (var font = new Font(linkBlock.Font.FontFamily, linkBlock.Font.Size, FontStyle.Bold)) {
        var text = addedToCart ? linkBlock.Text : defaultCartLinkText;
        e.Cache.DrawString(text, font, Brushes.White, linkRect, format);
    }
    //...
}

VB.NET

Private Sub OnCustomDrawRecordHeader(ByVal sender As Object, ByVal e As Events.CustomDrawRecordHeaderEventArgs)
    'skip code...
    ' Draw the record header element using default settings.
    e.DefaultDraw()
    ' Set the 'Handled' parameter to true to indicate that no default processing is required 
    ' after the event handler is complete.
    e.Handled = True
    '...
    Dim dataSourceRowIndex As Integer = vGrid.GetDataSourceRecordIndex(e.Record)
    Dim addedToCart As Boolean = Orders.Contains(dataSourceRowIndex)
    Dim color = If(addedToCart, DXSkinColors.FillColors.Success, DXSkinColors.FillColors.Question)
    e.Cache.FillRoundedRectangle(color, linkRect, New CornerRadius(9))
    Using format = New StringFormat() With {.Alignment = StringAlignment.Center, .LineAlignment = StringAlignment.Center}
        Using font = New Font(linkBlock.Font.FontFamily, linkBlock.Font.Size, FontStyle.Bold)
            Dim text = If(addedToCart, linkBlock.Text, defaultCartLinkText)
            e.Cache.DrawString(text, font, Brushes.White, linkRect, format)
        End Using
    End Using
    '...
End Sub

Record Header Related API

• VGridControl.RecordHeaderHeight — Allows you to set a custom record header panel height.
• VGridOptionsHintEx.ShowRecordHeaderHints — Specifies whether to display hints when a user hovers the mouse pointer over a record header.
• VGridOptionsPrint.PrintRecordHeaders — Specifies whether to print record headers.
• VGridOptionsMenuEx.EnableRecordHeaderMenu — Enables a context menu that allows users to compare records.

Header Appearance

Use the properties exposed by the VGridControl.Appearance object to customize the appearance settings of record headers in different states.

Compare Records

If record headers are enabled, built-in header check boxes and a context menu allow users to select records for comparison, and then compare selected records side-by-side.

Related API

• VGridOptionsView.ShowRecordHeaders
• VGridOptionsBehavior.AllowRecordComparison
• VGridOptionsMenuEx.EnableRecordHeaderMenu

Select/Deselect Records

Do one of the following:

• Toggle a record header’s built-in check box.
• Select the ‘Add to Comparison’/‘Remove from Comparison’ command in the header context menu.

Related API

• VGridControl.AddToComparison
• VGridControl.RemoveFromComparison
• VGridControl.IsInComparison

Show Comparison View

Select the ‘Show Comparison’ command in the header context menu:

As a result, the grid only displays the selected records:

Related API

• VGridControl.ShowComparison

Hide or Clear Comparison View

Use the following commands to switch back to the normal view:

• Hide Comparison — Switches back to the normal view while keeping the record selection status.
• Clear Comparison — Switches back to the normal view and resets the record selection status.

Related API

• VGridControl.ClearComparison
• VGridControl.HideComparison