Grid Columns
- 7 minutes to read
Important Notes
You cannot bind multiple Data Grid columns to the same data source field. If you need to do that, create Unbound Columns and handle the CustomUnboundColumnData event to manually copy data source values to unbound column cells. This limitation also applies to other data-aware controls (Data Grid, Tree List, Vertical Grid, etc.).
Column field names must be unique.
For information about the similar functionality in other data-aware controls, refer to these help articles: Columns (Tree List), Rows (Vertical Grid), Pivot Grid Fields (Pivot Grid).
Automatic Column Generation
When you bind a Data Grid to a data source, the control automatically generates a column for each bound data field (if the AutoPopulateColumns property is not disabled). For code-first data sources (for example, Entity Framework models), you can mark a property with the Display attribute and disable its AutoGenerateField parameter to skip column generation for this property. The “Display” attribute in the code below prevents the Data Grid from generating an “Additional Info” column.
[Display(AutoGenerateField = false, Description = "This column isn't created")]
public string AdditionalInfo { get; set; }
You can utilize many more attributes to re-arrange columns, modify captions of their headers, change their default in-place editors, etc. Refer to the following topic to learn more: Data Annotation Attributes.
If you replaced the previous data source with a new one, the Data Grid will not automatically regenerate columns. You need to do this manually by invoking the Data Grid Designer and clicking the “Retrieve Fields” button within the “Columns” tab.
To do the same in code, call the BaseView.PopulateColumns method either directly after changing a data source, or on the GridControl.DataSourceChanged event.
Note
In addition to regular columns that retrieve data from a source, Grid Control also supports unbound columns that display custom values. See this help topic to learn more: Unbound Columns.
See also: Obtaining Fields Available in Data Source.
Add and Remove Columns Manually
Columns associated with data fields declared in a data source are called bound columns. To add such columns manually, invoke the Data Grid designer, switch to the “Columns” tab and click the “Show Field List” button, then drag a data field into the column list. Data fields that have no corresponding grid columns are highlighted with bold text.
You can also utilize the “Add Column” and “Insert Column” buttons on the same designer page. In this case, you need to set every column’s GridColumn.FieldName property manually. Otherwise, a column is unbound and does not receive cell values from a data source.
To remove a column, utilize the “Remove Column” designer button, or click a column header at design time and press the “Delete” key. To remove a column in code, call the GridView.Columns.Remove or GridView.Columns.RemoveAt method.
Columns that you create in code are invisible even after you add them to the Columns collection. To display a column, enable its Visible property. You can also use the AddVisible method to create a column, bind it to the specified data field, and display it in the view.
// Create a new column.
GridColumn colPrice = new GridColumn();
// Bind the column to the 'Price' field in a data source.
colPrice.FieldName = "Price";
// Adds the column to the Columns collection. The column is hidden.
gridView.Columns.Add(colPrice);
// Creates a new column, binds it to the 'OrderDate' field in a data source,
// and displays it in the Grid View.
gridView.Columns.AddVisible("OrderDate");
Column Header
To modify a column header caption and add an image, select a column at design time and invoke its smart tag. If a column has no caption assigned, the column generates its caption based on the name of a related data field.
Related API
GridColumn.Caption — A column header caption.
GridColumn.Image — A column header image.
GridColumn.ImageIndex — Allows you to select an image from an image collection, assigned to the ColumnView.Images property.
GridColumn.ImageAlignment — Specifies the caption icon alignment.
GridOptionsView.ShowColumnHeaders — Allows you to hide all column headers.
GridOptionsView.ColumnHeaderAutoHeight — Enables multi-line headers that do not trim captions.
Hide Vertical Column Borders
You can hide column and row borders by disabling the GridOptionsView.ShowVerticalLines and GridOptionsView.ShowHorizontalLines settings.
Column Width
Data Grid squeezes all its columns into its current client area. Users can resize all columns except for the last one, and the total column width cannot exceed the width of the parent View.
Disable the GridOptionsView.ColumnAutoWidth property to allow grid columns to transcend the View bounds. A horizontal scroll bar is displayed automatically if columns occupy more space than the View provides.
You can call the GridControl.CalcBestSize method to obtain the optimal grid size required to fit its content (rows and columns).
Related API
GridColumn.MinWidth, GridColumn.Width, GridColumn.Resize — Allow you to manually set the column width. If the GridOptionsView.ColumnAutoWidth property is not disabled, the actual column width may differ from your custom settings.
GridColumn.VisibleWidth — Retrieves the actual column width.
GridView.ColumnWidthChanged — Occurs after the column width has been changed.
BaseView.IsSizingState / GridView.IsSizingState — Allow you to identify whether an end user is currently resizing a grid column.
OptionsColumn.FixedWidth — In column auto-width mode, enabling this setting prevents the column from automatically resizing.
Best Fit
To ensure a column or all the View’s columns have enough width for cells to display their content entirely, end users can right-click a column header and choose the “Best Fit” (or “Best Fit (all columns)”) option.
Related API
GridView.BestFitColumns — Applies best fit to all columns.
GridColumn.BestFit — Applies best fit to one specific column.
GridOptionsView.BestFitMaxRowCount — Best fit operations scan all grid rows to determine the optimal column width. This property allows you to limit the number of processed rows and thus, improve overall Grid performance.
GridOptionsView.BestFitMode — Allows you to select whether best fit operations prioritize precision or calculation speed.
Auto-Fill Column
A grid column assigned to the GridView.AutoFillColumn property automatically resizes to fill in any free space a View provides. In the animation below, the auto-fill column is “Address”.
Fixed Columns
Set a column’s Fixed property to Left or Right to anchor that column to the View’s corresponding side. Fixed columns remain visible while a user scrolls the View horizontally.
If you set the Fixed property to MiddleLeft, the column is not anchored until a user scrolls it to the View’s left side. When the column reaches the left side, it becomes fixed while other columns continue to scroll.
Use the FixedColumnHighlightMode property to distinguish the fixed columns from regular columns.
Note
The View ignores FixedColumnHighlightMode and FixedLineWidth properties if any column has the Fixed property set to MiddleLeft.
The Fixed Columns demo illustrates how to supply grid columns with custom pop-up menus that allow users to anchor columns at runtime.
Related API
End-User Capabilities
By default, end users can do the following:
Drag a right column edge to resize it.
Related API: OptionsColumn.AllowSize, GridOptionsCustomization.AllowColumnResizing.
Drag-and-drop column headers to re-arrange columns.
Related API: OptionsColumn.AllowMove, GridOptionsCustomization.AllowColumnMoving.
Hide columns by either dragging column headers down, or by right-clicking headers and selecting the “Hide This Column” option.
Related API: OptionsColumn.AllowShowHide, GridOptionsCustomization.AllowQuickHideColumns.
Right-click a column header and select the “Column Chooser” option to invoke a dialog that allows users to drag hidden columns back to the View.
Related API: GridView.CustomizationFormBounds, GridOptionsCustomization.CustomizationFormSearchBoxVisible, GridView.CustomizationForm, GridView.ShowCustomizationForm
Drag a column header into a group area to apply grouping.
Related API: OptionsColumn.AllowGroup, GridOptionsCustomization.AllowGroup
Click a column header to sort data by values of this column. Subsequent clicks change the sort order from ascending to descending and back.
Related API: OptionsColumn.AllowSort, GridOptionsCustomization.AllowSort
Click the filter button within the column header to filter grid data.
Related API: OptionsColumnFilter.AllowFilter, GridOptionsCustomization.AllowFilter
Identify and Access Grid Columns in Code
To retrieve specific columns, utilize the following API:
-
Stores all columns that belong to this View and provides access to them by indexes or related data field names.
-
Retrieves a column to which a currently focused cell belongs.
-
Returns a column by its visible index (the GridColumn.VisibleIndex property).