Group configurations define how same-level groups in the grid or detail are configured. By default, all group configurations contain a GroupHeaderControl in their header sections; however, the default configuration can be modified by providing a new group configuration to a grid or detail configuration's DefaultGroupConfiguration property (see Example 1). A group configuration can also be provided on either a DataGridGroupDescription or column and will be applied to all groups that are created from the values of the column.
Through the ItemContainerStyle and ItemContainerStyleSelector properties, different styles can be applied to the data items in the groups to which the configuration is applied. The style of the group-level indicators for the groups to which the configuration will be applied can be defined through a group configuration's GroupLevelIndicatorStyle property.
Each item that is added to the header or footer sections of a group configuration must be added as DataTemplates or GroupHeaderFooterItemTemplates, which must have a DataTemplate as an immediate child and whose VisibleWhenCollapsed property can be set to true (by default false) to keep the item visible when its containing group is collapsed. A group configuration's InitiallyExpanded property can also be set to provide an initial expansion state for all groups to which the configuration will be applied.
By default, group configurations contain a GroupHeaderControl in their header section that allow groups to be collapsed and expanded. In XAML, the content of a header or footer section can be cleared by setting the DefaultHeadersFootersType property of a group configuration to None. If left to GroupHeaderControl, any items that are added to a header or footer section will be added after the default headers and footers.
When the DefaultHeadersFootersType property is set to StatGroupHeaderControl or StatGroupHeaderControlWithGroupLabel, the group header is replaced by a StatRow that will display itself whenever the group is expanded or collapsed. More information is available in the Embedded StatRow section in the Statistical Functions page.
Each template that is added to a header or footer section will create a container for itself in every individual group. A specific container can be identified through the use of a GroupHeaderFooterItem, which is created from the CollectionViewGroup in which the container is located and the template that was used to create it.
Group configurations will be queried in the following order:
Group is located in a detail | Group is located in a grid |
---|---|
|
|
If neither a group configuration, group-configuration selector, nor default group configuration has been explicitly provided, the built-in group configuration will be used.
If a detail configuration has been explicitly provided for a specific detail description, the group configurations provided by the DefaultDetailConfigurations will never be queried.
All examples in this topic assume that the grid is bound to the Orders table of the Northwind database, unless stated otherwise.
Example 1: Defining a default group configuration
The following example demonstrates how to provide a default group configuration.
XAML |
Copy Code |
---|---|
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid"> <Grid.Resources> <xcdg:DataGridCollectionViewSource x:Key="cvs_orders" Source="{Binding Source={x:Static Application.Current}, Path=Orders}"> <xcdg:DataGridCollectionViewSource.GroupDescriptions> <xcdg:DataGridGroupDescription PropertyName="ShipCountry"/> <xcdg:DataGridGroupDescription PropertyName="ShipCity"/> </xcdg:DataGridCollectionViewSource.GroupDescriptions> </xcdg:DataGridCollectionViewSource> </Grid.Resources> <xcdg:DataGridControl x:Name="OrdersGrid" ItemsSource="{Binding Source={StaticResource cvs_orders}}"> <xcdg:DataGridControl.DefaultGroupConfiguration> <xcdg:GroupConfiguration> <xcdg:GroupConfiguration.Footers> <DataTemplate> <xcdg:InsertionRow/> </DataTemplate> </xcdg:GroupConfiguration.Footers> </xcdg:GroupConfiguration> </xcdg:DataGridControl.DefaultGroupConfiguration> </xcdg:DataGridControl> </Grid> |
Example 2: Programmatically toggling group expansion
The following example demonstrates how to handle the PreviewMouseLeftButtonDown event on the GroupHeaderControl objects contained in the headers of the child groups to toggle the expansion state of child groups using the ToggleGroupExpansion method. The group whose state is to be toggled will be retrieved using the GetParentGroupFromItem method.
XAML |
Copy Code |
---|---|
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid"> <Grid.Resources> <xcdg:DataGridCollectionViewSource x:Key="cvs_orders" Source="{Binding Source={x:Static Application.Current}, Path=Orders}"> <xcdg:DataGridCollectionViewSource.GroupDescriptions> <xcdg:DataGridGroupDescription PropertyName="ShipCountry"/> <xcdg:DataGridGroupDescription PropertyName="ShipCity"/> </xcdg:DataGridCollectionViewSource.GroupDescriptions> </xcdg:DataGridCollectionViewSource> <Style TargetType="{x:Type xcdg:GroupHeaderControl}"> <EventSetter Event="PreviewMouseLeftButtonDown" Handler="HeaderDown"/> </Style> </Grid.Resources> <xcdg:DataGridControl x:Name="OrdersGrid" ItemsSource="{Binding Source={StaticResource cvs_orders}}"/> </Grid> |
The following code provides the implementation of the PreviewMouseLeftButtonDown event in which we will retrieve the item represented by the GroupHeaderControl (GroupHeaderFooterItem) using the GetItemFromContainer method, which will then be used to retrieve the parent group (GetParentGroupFromItem) whose state is to be toggled.
VB.NET |
Copy Code |
---|---|
Private Sub HeaderDown( ByVal sender As Object, ByVal e As MouseButtonEventArgs ) Dim headerControl As GroupHeaderControl = TryCast( sender, GroupHeaderControl ); If headerControl Is Nothing Then Return End If Dim context As DataGridContext = DataGridControl.GetDataGridContext( headerControl ) Dim item As Object = context.GetItemFromContainer( headerControl ) ) If Not item Is Nothing Then Dim group As CollectionViewGroup = context.GetParentGroupFromItem( item ) If Not group Is Nothing context.ToggleGroupExpansion( group ) End If End If End Sub |
C# |
Copy Code |
---|---|
private void HeaderDown( object sender, MouseEventArgs e ) { GroupHeaderControl headerControl = sender as GroupHeaderControl; if( headerControl == null ) return; DataGridContext context = DataGridControl.GetDataGridContext( headerControl ); object item = context.GetItemFromContainer( headerControl ); if( item != null ) { CollectionViewGroup group = context.GetParentGroupFromItem( item ); if( group != null ) { context.ToggleGroupExpansion( group ); } } } |
Example 3: Changing the group-header text
The following example demonstrates how to change the information displayed in each GroupHeaderControl by creating an implicit DataTemplate targeting the Group data type.
XAML |
Copy Code |
---|---|
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid"> <Grid.Resources> <xcdg:DataGridCollectionViewSource x:Key="cvs_orders" Source="{Binding Source={x:Static Application.Current}, Path=Orders}"> <xcdg:DataGridCollectionViewSource.GroupDescriptions> <xcdg:DataGridGroupDescription PropertyName="ShipCountry"/> </xcdg:DataGridCollectionViewSource.GroupDescriptions> </xcdg:DataGridCollectionViewSource> <DataTemplate DataType="{x:Type xcdg:Group}"> <StackPanel Orientation="Horizontal"> <TextBlock Text="The "/> <TextBlock Text="{Binding Value}"/> <TextBlock Text=" group contains "/> <TextBlock Text="{Binding Items.Count}"/> <TextBlock Text=" items."/> </StackPanel> </DataTemplate> </Grid.Resources> <xcdg:DataGridControl x:Name="OrdersGrid" ItemsSource="{Binding Source={StaticResource cvs_orders}}"/> </Grid> |
Example 4: Providing a group-configuration selector
The following example demonstrates how to provide a FieldNameGroupConfigurationSelector that will apply the defined group configuration to all groups that are created from the values of the column corresponding to the specified field name.
XAML |
Copy Code |
---|---|
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid"> <Grid.Resources> <xcdg:DataGridCollectionViewSource x:Key="cvs_orders" Source="{Binding Source={x:Static Application.Current}, Path=Orders}"> <xcdg:DataGridCollectionViewSource.GroupDescriptions> <xcdg:DataGridGroupDescription PropertyName="ShipCountry" /> <xcdg:DataGridGroupDescription PropertyName="ShipCity" /> </xcdg:DataGridCollectionViewSource.GroupDescriptions> </xcdg:DataGridCollectionViewSource> </Grid.Resources> <xcdg:DataGridControl x:Name="OrdersGrid" ItemsSource="{Binding Source={StaticResource cvs_orders}}"> <xcdg:DataGridControl.GroupConfigurationSelector> <xcdg:FieldNameGroupConfigurationSelector> <xcdg:FieldNameGroupConfigurationSelectorItem FieldName="ShipCity"> <xcdg:FieldNameGroupConfigurationSelectorItem.GroupConfiguration> <xcdg:GroupConfiguration> <xcdg:GroupConfiguration.Footers> <DataTemplate> <xcdg:InsertionRow /> </DataTemplate> </xcdg:GroupConfiguration.Footers> </xcdg:GroupConfiguration> </xcdg:FieldNameGroupConfigurationSelectorItem.GroupConfiguration> </xcdg:FieldNameGroupConfigurationSelectorItem> </xcdg:FieldNameGroupConfigurationSelector> </xcdg:DataGridControl.GroupConfigurationSelector> </xcdg:DataGridControl> </Grid> |