KB Article T961089
Visible to All Users

Data Grid Columns - WinForms Cheat Sheet

Other DevExpress WinForms Cheat Sheets


Columns in Grid Views, Banded Grid Views, and Advanced Banded Grid Views are represented by GridColumn objects. The GridColumn class contains settings that allow you to specify a bound field's name, a column's caption, position, visibility, display format, read-only status, in-place editor used to edit and display column cells, etc.



Column creation and binding

How to create columns and bind them to fields in a data source

  • When you bind Data Grid to a data source, the control automatically generates columns for all data source fields (provided that the grid contains no columns). Disable the AutoPopulateColumns property to prevent automatic column creation.
  • To retrieve columns from the bound data source manually, open the Data Grid Designer, switch to the "Columns" page, and click the "Retrieve Fields" button. When you replace the grid's data source with a new one, the control does not automatically re-generate columns if it already contains columns. In this case, you need to manually retrieve columns.
    Clipboard-File-1.png
  • To create one or more columns manually, use the "Add Column" and "Insert Column" buttons in the Data Grid Designer's "Columns" page. Don't forget to set the GridColumn.FieldName property for all created columns.
  • To retrieve columns from the data source in code, call the View's PopulateColumns method.
  • To create one or more columns manually in code, use methods of the VIew's Columns collection (a (GridColumnCollection class object). For instance, use the AddVisible(String) method to create a column and make it visible.

How to bind a column to a data source field

When Data Grid automatically generates columns or you use the PopulateColumns method, the grid creates columns and automatically binds them to fields in the underlying data source (GridControl.DataSource).
When you create columns manually, use the GridColumn.FieldName property to bind a column to a data source field.


How to prevent automatic column creation at the data source level

For code-first data sources, you can mark a property with the Display attribute and disable its AutoGenerateField parameter to skip generating a column for this property:

C#
[Display(AutoGenerateField = false, Description = "This column isn't created")] public string AdditionalInfo { get; set; }

Access grid columns in code

How to access columns

The ColumnView.Columns collection stores all hidden and visible columns. This property allows you to access individual columns by indexes or related data field names.
Use the VisibleColumns property to access visible columns.


How to obtain a column to which a focused cell belongs

Use the ColumnView.FocusedColumn property.


How to obtain a column by its visible index

Use the ColumnView.GetVisibleColumn method or the VisibleColumns property.


Column visibility

How to get and set a column's visibility status and visible position

  • Use the GridColumn.Visible property to show/hide a column. The GridColumn.VisibleIndex property allows you to specify the visible position. If you set the VisibleIndex property to -1, this column will be hidden.

  • Your end-users can use the Column Chooser (Customization Form) to hide and restore columns.


How to prevent displaying a column's header in the Column Chooser when this column is hidden

Headers of hidden columns are accessible from the Column Chooser. To prevent a specific hidden column from being accessed in the Column Chooser, disable the GridColumn.OptionsColumn.ShowInCustomizationForm option.


How to prevent a column from being hidden when you drag it from the column header panel

Disable the GridOptionsCustomization.AllowQuickHideColumns option. In this case, end-users can only hide columns if they drag column headers onto the Column Chooser form.


How to respond to changing a column's position within the View

Handle the ColumnView.ColumnPositionChanged event.


How to show/hide the Column Chooser in code

To show or hide the Column Chooser, use the GridView.ShowCustomization and GridView.DestroyCustomization methods.


How to hide columns (corresponding editors) in the built-in Edit Form

Use the GridColumn.OptionsEditForm.Visible property to specify the visibility of editors that correspond to grid columns in the Edit Form.

If you need to dynamically change column visibility in the Edit Form, please note that a View caches the Edit Form and the layout of columns for performance reasons. To change column visibility settings after the Edit Form has already been displayed, you need to force the grid to recreate this form. To do this, assign an empty user control to GridView.OptionsEditForm.CustomEditFormLayout and then set this property to Null:

C#
private void RecreateEditForm() { using (var u = new UserControl()) { gridView1.OptionsEditForm.CustomEditFormLayout = u; } gridView1.OptionsEditForm.CustomEditFormLayout = null; }

How to hide columns in detail Views

There are several ways to hide columns in detail Views:

  • Design time: create a detail View and hide specific columns.
  • Runtime: Handle the GridView.MasterRowExpanded event. In this event handler, obtain a detail View using the GridView.GetDetailView method. Hide specific columns in this View.
  • Runtime: Handle the GridControl.ViewRegistered event. Use the event's parameter to access a detail View and hide the View's columns.

See also:
Access Views
Get Started: Create a Data Grid with Master and Detail Views


Column appearance

How to modify a column header

Use the following properties to change the column header caption, display an image in the header, and modify the column header's height and visibility.

API Description
GridColumn.Caption A column header caption
GridColumn.ImageOptions A column header image
GridColumn.ImageAlignment Image alignment
GridOptionsView.ShowColumnHeaders Column header panel visibility
ColumnPanelRowHeight Column header panel height
GridOptionsView.ColumnHeaderAutoHeight Enables multi-line captions

How to hide column and row borders

Use the GridOptionsView.ShowVerticalLines and GridOptionsView.ShowHorizontalLines settings.


Column size

How to allow grid columns to go beyond View boundaries

Disable the GridOptionsView.ColumnAutoWidth property. A horizontal scroll bar is displayed automatically if columns occupy more space than the View provides.


How to control column size

Use the following API:

API Description
GridColumn.MinWidth, GridColumn.Width, GridColumn.Resize Allow you to manually set column width. In case the GridOptionsView.ColumnAutoWidth property is enabled, the actual column width will differ from your custom settings.
GridColumn.VisibleWidth Retrieves the actual column width.
GridView.ColumnWidthChanged Occurs after column width has been changed.
BaseView.IsSizingState / GridView.IsSizingState Allows you to identify whether or not an end-user is currently resizing a grid column.
OptionsColumn.FixedWidth In column auto-width mode, enable this option to prevent automatic resizing for a column.

How to adjust column widths in an optimal way

End-users can right-click a column header and choose the "Best Fit" (or "Best Fit (all columns)") option.
You can also accomplish this task in code with the following API:

API Description
GridView.BestFitColumns Resizes all visible columns so that they completely display their content.
GridColumn.BestFit Resizes a specific column to the minimum width required to display the column content completely.
GridOptionsView.BestFitMaxRowCount The number of data rows whose content is processed to apply best fit to columns.
GridOptionsView.BestFitMode Gets or sets whether column best-fit resizing operations should prioritize precision or speed.

How to specify a column that will fill an empty View space

Use the GridView.AutoFillColumn property.


How to anchor a column at the View's left or right edge (fixed/frozen columns)

Fixed columns remain visible while a user scrolls the View horizontally. Set a column's Fixed property to Left or Right to fix a column.


End-User capabilities

How to control end-user capabilities

End-User Capabilities Related API
Resize columns (drag a column's right edge) OptionsColumn.AllowSize, GridOptionsCustomization.AllowColumnResizing
Re-arrange columns using drag-and-drop OptionsColumn.AllowMove, GridOptionsCustomization.AllowColumnMoving
Hide columns (drag column headers down, or use "Hide This Column" option in the column header context menu) OptionsColumn.AllowShowHide, GridOptionsCustomization.AllowQuickHideColumns
Search in the Column Chooser GridOptionsCustomization.CustomizationFormSearchBoxVisible
Group data by a column (drag a column header into the group panel) OptionsColumn.AllowGroup, GridOptionsCustomization.AllowGroup
Sort by a column (click a column header to sort data; subsequent clicks change the sort order from ascending to descending and back) OptionsColumn.AllowSort, GridOptionsCustomization.AllowSort
Filter the column's data (click the filter button within the column header) OptionsColumnFilter.AllowFilter, GridOptionsCustomization.AllowFilter

How to allow users to show/hide columns but disallow column drag-and-drop

Set the GridOptionsCustomization.AllowColumnMoving property to true and handle the GridView.DragObjectOver event as described in the following ticket: GridView - How to disable column reordering but keep the column grouping and hiding functionalities.


How to allow users to search for columns by their names

Although Data Grid doesn't offer a built-in UI to search for columns, you can implement this functionality manually, as follows. Add a separate search box (ButtonEdit) and perform a column search by the entered text when the ButtonEdit control's button is clicked. Then, call the GridView.MakeColumnVisible(GridColumn) method in your code to scroll the View and make the column visible to the user.

See also

Columns
Unbound Columns

Help us improve this article

Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.