WPF Datagrid to FlexGrid Migration Guide

ComponentOne WPF Edition includes two very similar datagrid controls, C1DataGrid and C1FlexGrid. The history is that C1DataGrid was initially provided as a port from Silverlight. The WPF and Silverlight platforms shared code heavily, so it was an efficient way to provide UI controls for two platforms. FlexGrid was, and is still to this day, our most popular WinForms control, so around 2011 we decided to provide a version of it for WPF to help developers migrate from WinForms to WPF. Ten years later we still provide both datagrids, despite the confusion it may have provided new users.

But now the time has come and we have decided that FlexGrid is the future of .NET datagrids for the GrapeCity ComponentOne product line. We announced earlier in our .NET 5 roadmap that C1DataGrid is not being carried forward. We now support FlexGrid in every .NET platform including WinUI, Blazor, Xamarin and (coming soon) MAUI, so it only makes sense for us to focus our development and investment in one datagrid.

If you are planning to migrate to .NET 5 or higher we recommend switching to FlexGrid. The purpose of this article is to provide guidance on migrating from the C1DataGrid control for WPF to C1FlexGrid for .NET 5.0/+.

How to Use this Migration Guide

This guide highlights some high-level differences, and then dives a bit deeper into each major feature and points out some differences in API or markup to help your migration go smoother. You may browse by major feature, or search (CTRL+F) the guide by a particular C1DataGrid property, event, or method to find the related FlexGrid API. For brevity sake, features and API that are the exact same in both grids are omitted, so if you don't find what you're looking for then it may be the simplest to migrate.

If you prefer to learn by sample, then I encourage you to take a look at the FlexGridExplorer sample for WPF which shows full code examples for every feature. The sample can be downloaded with the product and you can find it on GitHub.

WPF DataGrid High-Level Comparison

The table below shows which versions of .NET that have been shipped and how much support exists for both WPF datagrid controls.

The ComponentOne DataGrid control is still provided for .NET Framework 4.0-4.8 but we do not have plans to support it for higher versions of .NET. You may continue to use the .NET Framework version of C1DataGrid in any .NET 5 or higher application with the following limitations: (1) Your application will depend on .NET Framework (2) You may experience designer limitations and errors.

High-Level Feature Comparison

Before migrating, you can check that FlexGrid will support the major features that you need. The following table reflects the latest version of FlexGrid for .NET 5.0/+ at the time of this publication. Features marked with ( *) are in the roadmap for future updates.

	C1DataGrid	C1FlexGrid
Add New Row
Cell Merging
CheckList Selection
Column & Row Freezing
Column Footers
Column Reordering
Conditional Filtering
Conditional Formatting/Custom Cells
Custom Columns/Templates
Custom Filters
Deferred Scrolling
Empty Grid View
Export to Excel, CSV
Filter Row
Full-Text Filtering
Grouping/Summaries
Grouping Panel
Hierarchical Grid/Row Details
Hyperlinks
Mouse Over
Multi-Value Filtering
Paging
Printing
Removing Rows
Row reordering/drag & drop
Selection
Star-sizing/Responsive Column Sizing
Top & Bottom Row Templates
Validation
Virtualization/On-demand loading

While FlexGrid supports most features, there are a few small differences between the controls. The key features that are not currently planned to be supported in FlexGrid are deferred scrolling, grouping panel UI and top/bottom row templates. The grouping panel UI is considered no longer in trend, and end-users can group by any column using the menu ("Group by this column"). The add new row feature, which relied upon top/bottom row templates in C1DataGrid is supported in FlexGrid. The following sections detail the differences for each major feature that is supported in FlexGrid.

DataGrid vs FlexGrid Fundamentals

Package Comparison

When you are ready to migrate, the first step is to add the necessary references to your application. Identify which C1DataGrid or C1FlexGrid .NET Framework libraries you were referencing,and add the corresponding .NET 5 packages in the table below to achieve the same functionality. The FlexGrid .NET Framework libraries are also provided below for reference.

*For .NET Core+, data transformations are handled by the C1DataCollection component. This .NET Standard component is similar to the C1CollectionView in .NET Framework.

XAML Declaration & Data Binding

The next step is to replicate the data binding and column generation in FlexGrid. C1DataGrid and FlexGrid are both bound to using the ItemsSource property. Columns may be auto-generated, or declared and bound in XAML using the column’s Binding property.

DataGrid vs FlexGrid Row & Column API

The next step is to copy the code. There are some differences in API for the common column and row classes. Both datagrids support cell access by row and column index (grid[row,col]) so you'll only have to change class types.

Column Types Comparison

Although both grids support the same types of columns and cell content, C1DataGrid and FlexGrid have different column type class names. Below lists the column types, and which column type to use in FlexGrid. The generic GridColumn is meant to be used in most cases.

Template Columns vs Cell Templates

Templated or custom cells were created in C1DataGrid using the special DataGridTemplateColumn type and then providing the template using the CellTemplate and CellEditingTemplate properties. In FlexGrid, these properties exist on the base column type, so any column's cell content can be customized with a template.

Rows & Columns Comparison

The following row and column API differences are listed below. Some features, like reordering rows,are made easier in FlexGrid by just setting the AllowDragging property.

DataGrid vs FlexGrid Feature Comparison

Hierarchical Grid with Row Details Comparison

C1DataGrid and FlexGrid support nesting datagrids to create a hierarchical datagrid using the Row Details feature. FlexGrid uses a behavior to support the feature for better performance.

Editing & New Row Comparison

Both C1DataGrid and FlexGrid support the ability to add new rows to the datagrid. Editing is enabled on the column (see Column Types Comparison), or disabled at the grid level. Data bound editing can be enabled in either datagrid by setting the Binding Mode = TwoWay.

For events related to adding new rows, see Events topic.

Column Filtering Comparison

There are several different types of filtering supported in FlexGrid and C1DataGrid. Each grid provides similar filtering features built into the column headers. C1DataGrid provides built-in conditional and with some code you could enable multi-value filtering. FlexGrid provides built-in multi-value and conditional filtering that requires no additional code, however the UI is different (better).

Full-Text Filtering Comparison

Full-text filtering works like a search box that filters against all columns at once. Both C1DataGrid and FlexGrid support full-text filtering using a behavior with the same options: MatchWholeWord, MatchCase, MatchNumbers, TreatSpacesAsAndOperator.
FlexGrid makes it easier to bind the behavior to the textbox control by setting the FilterEntry property.

Filter Row Comparison

C1DataGrid supported a special type of top/bottom row called C1DataGridFilterRow. When migrating to C1FlexGrid, the top & bottom row concept is not supported in C1FlexGrid. Use the new C1GridFilterRow class to define and configure the filter row, along with freezing to keep the row in place while scrolling.

Custom Filtering Comparison

While FlexGrid supports custom filters just like C1DataGrid, FlexGrid does provide more specialized filters for different data types, so there is now less need for custom filters.

FlexGrid supports custom filtering just like C1DataGrid does using some extra code, classes and converters. Below is an example showing a custom color filter for a FlexGrid GridColumn by utilizing the FilterLoading event.

<c1:GridColumn Binding="Color" FilterLoading="OnColorFilterLoading" />

The FilterLoading event allows you to customize the filter as well as display an Apply and Clear button.

private void OnColorFilterLoading(object sender, C1.WPF.Grid.GridColumnFilterLoadingEventArgs e)
{
   e.DataFilter.Filters.Clear();
   var colorFilter = new ColorFilter() { PropertyName = "Color" };
   colorFilter.SetColors(DataProvider.Colors.Select(x => (Color)ColorConverter.ConvertFromString(x)).ToList());
   e.DataFilter.Filters.Add(colorFilter);
   e.ShowClearButton = true;
}

You can find the full sample code in the FlexGridExplorer sample installed with the product or on GitHub.

Grouping & Summaries Comparison

FlexGrid makes grouping and displaying aggregated summaries easier. Instead of the old-fashioned grouping panel, end-users can now group a column through its menu. You can even display outline buttons by setting the new ShowOutlineBar property.

By default, grouping is disabled in FlexGrid and should be enabled on the column itself. The following differences exist for grouping API.

Column Summaries

C1DataGrid supported displayed summaries (aggregates) in grouped rows. It was enabled using a behavior and setting the column’s DataGridAggregate. C1FlexGrid makes this easier by just setting the Aggregate property on the column.

<c1:FlexGrid x:Name="grid" AutoGenerateColumns="False" ShowOutlineBar="True">
    <c1:FlexGrid.Columns>
        <c1:GridColumn Binding="Active" Width="Auto"/>
        <c1:GridColumn Binding="Name" Width="*"/>
        <c1:GridColumn Binding="OrderTotal" Width="Auto" Format="C" Aggregate="Sum" HorizontalAlignment="Right"/>
    </c1:FlexGrid.Columns>
</c1:FlexGrid>

Selection & Mouse Over Comparison

FlexGrid supports the same selection and mouse over effects as C1DataGrid, with just a few API name changes and simplifications.

The Selection API is mostly different in how you access a range of cells. In FlexGrid, the Selection members will give you the row and column indices for the selected range. You can use those index values to obtain the values from the grid (using flexGrid[row,col] notation).

The MouseOverBrush in FlexGrid behaves like the FluidMouseOver behavior in DataGrid where the brush is combined with row and selection brushes to create a blended effect.

Scrolling & Paging Comparison

C1DataGrid supported two scrolling modes: Real-time and deferred. FlexGrid supports real-time scrolling by default. The alternative scrolling method for FlexGrid is to use virtualization to load rows as the user scrolls. Paging is supported in FlexGrid using the C1PagedDataCollection component (part of C1DataCollection) and C1DataPager UI control. If you have a license for WPF Edition or Studio Enterprise, then C1DataCollection is included.

Below is a code snippet for paging in FlexGrid. For the full code implementation of the VirtualModeDataCollection, check out the samples for On Demand and Paging in the FlexGridExplorer.

// xaml
<c1:FlexGrid x:Name="grid" />
<c1:C1DataPager x:Name="pager" Padding="4" Background="White"/>

// code
var pagedCollection = new C1PagedDataCollection<object>(new VirtualModeDataCollection() { PageSize = 10 });
grid.ItemsSource = pagedCollection;
pager.Source = pagedCollection;

Cell Freezing and Merging

The following differences exist in the API for freezing cells.

Cell merging is a feature new to FlexGrid which allows you to specify merge rules for the grid. By setting the AllowMerging property, you can enforce cells, row headers or column headers to merge when adjacent cells are equal. You can also manage cell merging in both column and row directions by defining your own Merge Manager. See the Custom Merging sample in FlexGridExplorer.

Export & Printing Comparison

Printing for both grids is handled by the Print method with the same parameters (document name, scale mode, page margins and max number of pages). The supported scale modes are also the same (actual size, page width, single page). In addition, FlexGrid supports a print preview by calling the PrintPreview method that will launch a new window. Both grids support the GetPageImages method which can be used for custom printing scenarios.

FlexGrid supports saving to Html, Csv, Text, Pdf and Excel formats (XLSX and XLSM).

Styling & Appearance Comparison

Gridlines styling is now done in FlexGrid using a variety of different properties. The GridLinesVisibility property remain the same.

The following table shows which style & appearance related API is different or not implemented in FlexGrid.

FlexGrid supports more precision over styling with additional brushes for column and row headers. Also, FlexGrid supports CellStyles, which means you can more easily theme the datagrid using various styles like AlternatingRowStyle, ColumnHeaderStyle, CellStyle, GroupRowStyle, NewRowStyle, ColumnHeaderSelectedStyle, SelectionStyle and more. The CellStyles encapsulate all the style elements. Below is a Cell Style example.

<UserControl.Resources>
    <Style x:Key="altStyle" TargetType="Control">
        <Setter Property="Background" Value="Red" />
        <Setter Property="Foreground" Value="White"/>
    </Style>
</UserControl.Resources>

<c1:FlexGrid AlternatingRowStyle="{StaticResource altStyle}">

Conditional Formatting Comparison

Conditional formatting for C1DataGrid was handled in the LoadedCellPresenter event, which fired for every cell and you could check for a certain column and then modify the presented content. FlexGrid handles it similarly but with a separate class called CellFactory. The CellFactory has separated logic for the cell background (container) and foreground (bound value). It works by defining your own CellFactory class, overriding the PrepareCell or BindCellContent event, and then setting an instance of this class to the FlexGrid's CellFactory property.

Below is a code snippet, but for the full sample check out the FlexGridExplorer.

flexGrid.CellFactory = new MyCellFactory();

public class MyCellFactory : GridCellFactory
{
    public override void PrepareCell(GridCellType cellType, GridCellRange range, GridCellView cell, Thickness internalBorders)
    {
        base.PrepareCell(cellType, range, cell, internalBorders);
        var orderCountColumn = Grid.Columns["OrderCount"];
        if (cellType == GridCellType.Cell && range.Column == orderCountColumn.Index)
        {
            var cellValue = Grid[range.Row, range.Column] as int?;
            if (cellValue.HasValue)
            {
                cell.Background = new SolidColorBrush(cellValue < 50.0 ? Colors.Red : Colors.Green);
            }
        }
    }
}

Working Around Missing Behaviors

C1DataGrid provided several behaviors, which are ways to enable advanced features through XAML markup and less C# code. Some behaviors are carried over in FlexGrid (such as the FullTextFilter behavior), but these behaviors below are handled differently in FlexGrid.

Events

The following Events are different in FlexGrid, or they do not exist.

Conclusion - Why Migrate to FlexGrid?

In addition to enjoying the performance benefits with .NET 5.0/+, enjoy the following overall improvements with FlexGrid:

• If you plan to migrate to .NET 5.0/+ enjoy the major performance enhancements from the platform as seen in our .NET 5 benchmarks.
• Even if you're not planning to migrate .NET, the FlexGrid for .NET Framework is faster than C1DataGrid in a most areas.
• Overall improvements to column menus and filtering. Users can now sort, group, and apply different types of filters from the column menu instead of just filtering.
• Overall improvements to style and appearance related customization. FlexGrid delivers a more modern fluent/material style.
• Better for unbound scenarios and managing data row by row, cell by cell.
• More flexibility with custom cell templates - you can provide a cell template or editing template for any specialized column type.
• Some different features like cell merging down columns and custom cell merging in both directions, checklist selection, row animation, empty grid view (what displays when there are no rows) and outline grouping buttons.

If you have any questions or see any topic that you'd like more details off, let us know in the comments.

Download Now!