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.
-
- How to get and set a column's visibility status and visible position
- How to prevent displaying a column's header in the Column Chooser when this column is hidden
- How to prevent a column from being hidden when you drag it from the column header panel
- How to respond to changing a column's position within the View
- How to show/hide the Column Chooser in code
- How to hide columns (corresponding editors) in the built-in Edit Form
- How to hide columns in detail Views
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.
- 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.