DataGridView Class

A data grid view.

Namespace: DevExpress.XamarinForms.DataGrid

Assembly: DevExpress.XamarinForms.Grid.dll

Declaration

public class DataGridView :
    View,
    IDataControllerOwner,
    ICustomCellTextProvider,
    IGridControlTest,
    IGridDataProvider,
    IStyledElement

Related API Members

The following members return DataGridView objects:

• CustomizeCellDisplayTextEventArgs.Source
• EditFormView.DataGridView
• EditRowViewModel.DataGridView
• GridColumnDataEventArgs.Source

Remarks

DataGridView is a data-aware control that presents data in a tabular format. To display data in a grid and allow users to manage it, bind the grid to a data source via the DataGridView.ItemsSource property. Note that the unbound mode (add and save records directly to a grid) is not supported and the grid cannot operate without a data source.

Columns

The grid represents data source’s fields as columns. It automatically generates columns based on the bound data source, or you can add columns to the grid and associate them with data fields manually. The AutoGenerateColumnsMode property allows you to prevent columns from being automatically created or set another mode of auto generating columns.

The grid stores its columns in the DataGridView.Columns collection. An individual column is a GridColumn class descendant that corresponds to the type of data this column displays. The following column types are supported:

Column Object	Description
TextColumn	A grid column used to display and edit text values.
NumberColumn	A grid column used to display and edit numeric values.
DateColumn	A grid column used to display and edit date values.
SwitchColumn	A grid column that displays Boolean values and allows a user to change a cell value by switching between two states.
ImageColumn	A grid column used to display images.
PickerColumn	A grid column that allows a user to edit a cell value by selecting an item from the predefined set.
TemplateColumn	A column type that allows you to define a custom template for column cells.

The GridColumn.FieldName property specifies a data source’s field to which the column is bound. Each column object provides a set of properties to adjust column settings (for example, data display format, column width, header caption, content alignment), and manage grid data (sort and group).

Unbound Columns

In addition to columns bound to data source fields, you can create unbound columns to display data values calculated based on values of other columns. To create an unbound column in the grid, add a column object that corresponds to the type of data the column should display to the DataGridView.Columns collection, and set the following column properties:

• FieldName - a unique string that does not match any field name in the grid’s underlying data source.
• UnboundType - the type of data the column should display (Boolean, DateTime, Decimal, Integer, String or Object).
• UnboundExpression - a formula (string expression) that automatically calculates the column’s values.
  The DataGridView.CustomUnboundColumnData event is another way to populate an unbound column with data. It allows you to implement custom logic of any complexity to provide cell values. Use also this event (not an expression), if you need to save changes that a user made in an unbound column.

Fixed Columns

The grid allows you to anchor (fix) columns to its left or right edge, so they always remain visible while a user scrolls the view horizontally. To fix a column, set its GridColumn.FixedStyle property to Start or End.

The grid’s FixedColumnSeparatorWidth property allows you to change the thickness of the line that separates fixed columns from scrollable columns.

Rows

Data rows in the grid represent records from the data source. To obtain the number to data rows in the grid, use the DataGridView.RowCount property.

The grid automatically adjusts the height of data rows to display the entire content of cells. If you specify the DataGridView.RowHeight property, all data rows have the same height.

When data is grouped, the grid also displays group rows to separate groups of data rows. End users can tap group rows to expand and collapse groups.

Row Handles

Grid rows are identified by unique integer values - row handles. Each row has a row handle, regardless of whether a row is currently visible (for example, a row might be scrolled off-screen or hidden within a collapsed group).

A row handle depends on the rows’s current location in the grid and changes dynamically when rows are reordered (for example, when data is sorted or grouped).

• Data row handles are zero-based indexes that correspond to row order from top to bottom.
• Group row handles are negative values that start with -1. The order matches the order of group rows from top to bottom.

The grid provides the following methods and properties to obtain row handles:

Method	Description
DataGridView.FindRow	Returns the handle of the first row that matches the specified criteria.
DataGridView.FindRowByValue	Searches for the value in the column and returns the handle of the corresponding row.
DataGridView.GetRowHandle	Returns the handle of the row that corresponds to the specified record in the data source.
DataGridView.SelectedRowHandle	Gets or sets the selected row handle.

You can pass row handles as parameters to the following methods that operate with rows:

Method	Description
DataGridView.GetCellValue	Gets the value of the specified cell.
DataGridView.SetCellValue	Assigns a value to the specified cell.
DataGridView.GetRow	Gets an object that provides access to the data of the specified row.
DataGridView.GetSourceRowIndex	Gets the index of the data source record to which the specified row handle corresponds.
DataGridView.DeleteRow	Deletes the specified data row.
DataGridView.ScrollToRow	Scrolls the grid to make the specified row visible.
DataGridView.GetGroup	Provides access to the information on the specified group of rows.
DataGridView.GetGroupRowValue	Gets the value of the specified group row.
DataGridView.CollapseGroupRow	Collapses the specified group of rows.
DataGridView.ExpandGroupRow	Expands the specified group of rows.

Cells

The grid displays data values in cells located at the intersection of columns and rows. You can use the following methods and properties to obtain and set cell values, and prevent users from changing cell values:

Method	Description
DataGridView.GetCellValue	Gets the value of the specified cell.
DataGridView.GetCellDisplayText	Gets the text displayed within the specified cell.
DataGridView.SetCellValue	Assigns a value to the specified cell.
DataGridView.IsReadOnly	Gets or sets whether the grid is read-only.

Edit Data

You can allow users to edit cell values via in-place editors or an edit form.

Related API

Member	Description
DataGridView.OpenEditor	Invokes an in-place editor for the specified cell.
DataGridView.CloseEditor	Closes a cell in-place editor.
DataGridView.EditorShowMode	Gets or sets a gesture by which a user can invoke an in-place editor for a data cell.
DataGridView.EndRowEdit	Occurs after an in-place editor is closed and a modified cell value is applied or canceled.
EditFormPage	The page that allows users to edit grid’s cell values.
EditFormView	Stores appearance settings of the grid’s edit form view.
EditRowViewModel	Contains information on a data row that a user currently edits via the edit form.

XAML

<dxg:DataGridView ItemsSource="{Binding Orders}" EditorShowMode="Tap">
    <!-- ... -->
</dxg:DataGridView>

Sort Data

Users can tap column headers to sort data in the grid.

Related API

Member	Description
DataGridView.AllowSort	Specifies whether end users can sort data in the grid.
GridColumn.AllowSort	Specifies whether end users can sort data by the column.
DataGridView.SortMode	Specifies whether the grid allows data sorting by multiple columns or by a single column only.
GridColumn.SortOrder	Gets or sets the column’s sort order.
GridColumn.SortIndex	Gets or sets the column’s position among sorted columns.
GridColumn.SortMode	Specifies whether the grid should sort data by column values or display text.
DataGridView.SortBy	Sorts data by the specified column.
DataGridView.ClearSorting	Clears the sorting applied to the grid.

XAML

<dxg:DataGridView x:Name="grid" ItemsSource="{Binding Orders}" 
                 SortMode="Multiple">
    <dxg:DataGridView.Columns>
        <dxg:TextColumn FieldName="Product.Name"
                        SortOrder="Descending" SortIndex="0"/>
        <!-- ... -->
        <dxg:NumberColumn FieldName="Quantity" 
                          SortOrder="Ascending" SortIndex="1"/>
        <!-- ... -->
        <dxg:SwitchColumn FieldName="Shipped" AllowSort="False"/>
    </dxg:DataGridView.Columns>
</dxg:DataGridView>

Group Data

The grid allows you to group data by a single column.

Groups of data rows (rows that have identical values in the specified column) are separated with group rows that a user can tap to expand or collapse groups. You can also display summary information about groups (for example, the sum of values, the number of records, the minimum or maximum value, etc.) on group rows.

Related API

Member	Description
GridColumn.IsGrouped	Gets or sets whether the grid’s data is grouped by the current column.
GridColumn.GroupInterval	Gets or sets how data rows are combined into groups.
DataGridView.GroupBy	Groups data in the grid by the specified column.
DataGridView.ClearGrouping	Ungroups data in the grid.
DataGridView.ShowGroupedColumns	Gets or sets whether the grid displays a column used to group data.
DataGridView.GetGroup	Provides access to the information on the specified group of rows.
DataGridView.GroupSummaries	Provides access to the collection of group summary items.
DataGridView.AllowGroupCollapse	Specifies whether end users can collapse and expand groups of rows.
DataGridView.CollapseGroupRow	Collapses the specified group of rows.
DataGridView.CollapseAllGroups	Collapses all groups of rows.
DataGridView.ExpandGroupRow	Expands the specified group of rows.
DataGridView.ExpandAllGroups	Expands all groups of rows.

XAML

<dxg:DataGridView x:Name="grid" ItemsSource="{Binding Orders}">
    <dxg:DataGridView.Columns>
         <!-- ... -->
        <dxg:DateColumn FieldName="Date" DisplayFormat="d"  
                        IsGrouped="true" GroupInterval="Date"/>
         <!-- ... -->
    </dxg:DataGridView.Columns>
</dxg:DataGridView>

Filter Data

You can filter data in the grid against single or multiple columns. When a filter is applied, the grid displays a subset of data records that meet the specified criteria.

Related API

Member	Description
DataGridView.FilterExpression DataGridView.FilterString	Use any of these properties to apply a filter to the grid (a filter expression can consist of multiple conditions applied to multiple columns).
DataGridView.ActualFilterString	Gets the string that specifies a filter currently used in the grid.
DataGridView.ClearFilter	Clears the filter applied to data in the grid.

XAML

<dxg:DataGridView ItemsSource="{Binding Orders}"  
                  FilterString="Contains([Product.Name], 'Choco')">
    <!-- ... -->
</dxg:DataGridView>

Data Summaries

The grid allows you to display summary information about groups of rows or particular columns. For example, you can display the sum of values, the number of records, the minimum or maximum value, etc.

Two summary types are supported: total summaries (calculated over all rows in a column and displayed below this column) and group summaries (calculated over all rows in a group and displayed in a group row).

Related API

A grid stores its total and group summaries in the DataGridView.TotalSummaries and DataGridView.GroupSummaries collections.
An individual summary (group or total) is a GridColumnSummary object that contains the following summary settings:

Property	Description
GridColumnSummary.FieldName	Gets or sets the field name of the column for which a summary should be calculated.
GridColumnSummary.Type	Gets or sets the aggregate function type. There are five predefined aggregate functions for grid data summaries: Sum, Min, Max, Average and Count.
GridColumnSummary.DisplayFormat	Gets or sets the pattern used to format the summary value.

To implement and apply a custom aggregate function, set the GridColumnSummary.Type property to Custom and handle the DataGridView.CalculateCustomSummary event.

XAML

<dxg:DataGridView x:Name="grid" ItemsSource="{Binding Orders}" 
                 CalculateCustomSummary="OnCalculateCustomSummary">
    <!-- ... -->
    <dxg:DataGridView.GroupSummaries>
        <dxg:GridColumnSummary FieldName="Total" Type="Max"/>
    </dxg:DataGridView.GroupSummaries>

    <dxg:DataGridView.TotalSummaries>
        <dxg:GridColumnSummary FieldName="Total" Type="Sum" 
                                DisplayFormat="Total: {0:C0}"/>
        <dxg:GridColumnSummary FieldName="Shipped" Type="Custom" 
                                DisplayFormat="Not Shipped: {0}"/>
    </dxg:DataGridView.TotalSummaries>
</dxg:DataGridView>

C#

int count;
// ...

void OnCalculateCustomSummary(object sender, CustomSummaryEventArgs e) {
    if (e.FieldName.ToString () == "Shipped")
        if (e.IsTotalSummary){
            if (e.SummaryProcess == CustomSummaryProcess.Start) {
                count = 0;
            }
            if (e.SummaryProcess == CustomSummaryProcess.Calculate) {
                if (!(bool)e.FieldValue)
                    count++;
                e.TotalValue = count;
            }
        }
}

Pull to Refresh

You can set up the grid so that it allows users to initiate content refresh with the pull-down gesture.

To enable this functionality, set the IsPullToRefreshEnabled property to true. Then, either define a refresh command in a view model and bind it to the PullToRefreshCommand property, or handle the PullToRefresh event. Use the IsRefreshing property to notify the grid that the pull-to-refresh activity is completed and the refresh indicator should be hidden.

Load More

You can set up the grid so that it adds a set of new data items when a user scrolls to the last row.

To enable this functionality, set the IsLoadMoreEnabled property to true. Then, either define a load-more command in a view model and bind it to the LoadMoreCommand property, or handle the LoadMore event. Use the IsRefreshing property to notify the grid that the load-more activity is completed and the loading indicator should be hidden. The DataGridView.IndicatorColor property allows you to change the indicator color.

Swipe Actions

You can extend the grid’s UI with additional elements (buttons) that appear when a user swipes a data row (from left to right or from right to left) and perform custom actions on tap.

To define a swipe action in the grid, do the following.

1. Add a SwipeItem object to the DataGridView.StartSwipeItems or DataGridView.EndSwipeItems collection.
2. Use this object’s properties (for example, Image, Caption, FontColor or BackgroundColor) to customize the button appearance.
   If you add multiple swipe buttons to the grid and need to apply the same appearance settings to all of them, assign a SwipeItemStyle object with the specified properties to DataGridView.SwipeItemStyle.
3. Handle the SwipeItem.Tap event to assign a custom action to a button.

XAML

<dxg:DataGridView x:Name="grid" ItemsSource="{Binding Orders}">
    <!-- ... -->
    <dxg:DataGridView.StartSwipeItems>
            <dxg:SwipeItem Caption="Customer" BackgroundColor="#797bff" Image="person.png" 
                           Tap="Swipe_ShowCustomerInfo" />
    </dxg:DataGridView.StartSwipeItems>
    <dxg:DataGridView.EndSwipeItems>
            <dxg:SwipeItem Caption="Delete" BackgroundColor="#ff3b30" Image="delete.png" 
                           Tap="Swipe_Delete"/>
    </dxg:DataGridView.EndSwipeItems>

    <dxg:DataGridView.SwipeItemStyle>
        <dxg:SwipeItemStyle Width="100"/>
    </dxg:DataGridView.SwipeItemStyle>
</dxg:DataGridView>

C#

using DevExpress.XamarinForms.DataGrid;
// ...

private void Swipe_ShowCustomerInfo(object sender, SwipeItemTapEventArgs e) {
    var customer = (e.DataObject as Order).Customer;
    string customerName = customer.Name;
    string customerPhone = customer.Phone;
    DisplayAlert("Customer", "Name: " + customerName + "\n" + "Phone: " + customerPhone, "OK");
}

private void Swipe_Delete(object sender, SwipeItemTapEventArgs e) {
    grid.DeleteRow(e.RowHandle);
}

Grid Appearance

The following properties allow you to customize the appearance of grid elements (cells, columns headers, summaries, etc.):

Property	Description
DataGridView.BorderColor	Gets or sets the grid border color.
DataGridView.BorderThickness	Gets or sets the grid border thickness.
DataGridView.CellStyle	Gets or sets the data cell appearance settings.
DataGridView.GroupRowStyle	Gets or sets the group row appearance settings.
DataGridView.HeaderStyle	Gets or sets the column header appearance settings.
DataGridView.TotalSummaryStyle	Gets or sets the total summary panel appearance settings.
DataGridView.SwipeItemStyle	Gets or sets the swipe item appearance settings.

You can also create styles for the following target types:

Class	Description
CellStyle	Stores the data cell appearance settings.
GroupRowStyle	Stores the group row appearance settings.
HeaderStyle	Stores the column header appearance settings.
TotalSummaryStyle	Stores the total summary panel’s appearance settings.
SwipeItemStyle	Stores the swipe item appearance settings.

XAML

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="DataGridExample.MainPage"
             xmlns:dxg="clr-namespace:DevExpress.XamarinForms.DataGrid;assembly=DevExpress.XamarinForms.Grid">
    <dxg:DataGridView x:Name="grid" ItemsSource="{Binding Orders}" 
                      RowHeight="35" TotalSummaryHeight="35">
        <!-- Specify grid columns and total summaries here. -->

        <!--Customize the appearance of grid cells.-->
        <dxg:DataGridView.CellStyle>
            <dxg:CellStyle Padding="5,5,5,5" BackgroundColor="#333333" BorderColor="#515151"
                           FontSize="8" FontColor="White" 
                           SelectionColor="#f78a09" SelectionFontColor="Black"/>
        </dxg:DataGridView.CellStyle>

        <!--Customize the appearance of column headers.-->
        <dxg:DataGridView.HeaderStyle>
            <dxg:HeaderStyle BackgroundColor="#333333" BorderColor="#515151" 
                             FontSize="12" FontColor="#929292" FontAttributes="Bold" 
                             HorizontalLineThickness="2"/>
        </dxg:DataGridView.HeaderStyle>

        <!--Customize the appearance of the total summary panel displayed at the bottom of the grid.-->
        <dxg:DataGridView.TotalSummaryStyle>
            <dxg:TotalSummaryStyle Padding="2,5,2,5" BackgroundColor="#666666" BorderColor="#515151"
                                   FontSize="8" FontColor="#f78a09"/>
        </dxg:DataGridView.TotalSummaryStyle>
    </dxg:DataGridView>
</ContentPage>

Implements

INotifyPropertyChanged

Xamarin.Forms.IAnimatable

Xamarin.Forms.IViewController

Xamarin.Forms.IVisualElementController

Xamarin.Forms.IElementController

Xamarin.Forms.Internals.IGestureController

IStyledElement

Inheritance

Object

Xamarin.Forms.BindableObject

Xamarin.Forms.Element

Xamarin.Forms.NavigableElement

Xamarin.Forms.VisualElement

View

DataGridView