Records

  • 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.

    image

  • 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.

    image

  • 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.

    image

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):

Record Headers

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.

Vertical Grid - 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:

Example

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

Vertical Grid - RecordHeaderFormat

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.

Vertical Grid - Hyperlink Click

private void Form1_Load(object sender, EventArgs e) {
    BindingList<Message> list = new BindingList<Message>();
    list.Add(new Message() { Date = DateTime.Now, Email = "jheart@dx-email.com", 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 = "violetb@dx-email.com", 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; }
}

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.

VerticalGrid - CustomRecordHeaderDisplayText

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>";
}

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.

VGrid - CustomDrawRecordHeader

See the following demo for the complete code:

Run Demo: PC Market

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);
    }
    //...
}

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.

VGrid- Compare Records

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.

VGrid - Record Comparison

Show Comparison View

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

VGrid-ShowComparison

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

vGrid - Comparison View

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.

vGrid - Hide and Clear Comparison View

See Also