Printing Overview
- Nov 16, 2018
- 5 min to read
The Grid Control provides methods for printing displayed data, showing a preview window and invoking a print dialog. This topic demonstrates how to customize the printed version of the Grid Control, and lists ways with which the grid control can be printed. This topic consists of the following subsections.
NOTE
Custom painting, alpha blending and color gradient features are not supported in the grid control's printout.
NOTE
In Large Data Sources: Server and Instant Feedback Modes, a print/export document is not regenerated each time it is sent to the print/export output. This means that if a print/export document has been generated and it's not empty, subsequent changes to the grid's layout (changing filter, sort and group settings, modifying cell values, etc.) are not applied when you send the grid's data to the print/export output the next time. To apply the changes made, call the BaseView.CreateDocument method before sending the grid's data to the print/export output.
#Printing Basics
Although the Grid Control provides direct methods for printing displayed data, these methods delegate the printing functionality to the DevExpress Printing Library. If this library cannot be found, the printing and export functionality is not available. To ensure that Grid Control printing/exporting is permitted, check the GridControl.IsPrintingAvailable property's value.
To print data from the Grid Control, use the following methods.
| Member | Description |
|---|---|
| GridControl.Print | Prints the grid control's GridControl.DefaultView (the GridControl.MainView or the currently maximized detail View) without showing a print preview or print dialog. |
| GridControl.PrintDialog | Displays the standard Print dialog to print the data displayed in the Grid Control's GridControl.DefaultView. |
| GridControl.ShowPrintPreview | Opens the Print Preview window with a Bars UI. |
| GridControl.ShowRibbonPrintPreview | Displays the Print Preview window with a Ribbon UI. |
These methods print and show a print preview of the data displayed by the Grid Control's Default View (the GridControl.MainView or the currently maximized detail View).
A detail View can be printed as follows:
- along with the Main View, if you expand this detail and enable the GridOptionsPrint.PrintDetails option;
- separately from the Main View, if you zoom to (maximize) this detail. See Master-Detail Relationships to learn more.
The following example shows how to preview grid data.
private void ShowGridPreview(DevExpress.XtraGrid.GridControl grid) {
// Check whether or not the Grid Control can be printed.
if(!grid.IsPrintingAvailable) {
MessageBox.Show("The 'DevExpress.XtraPrinting' Library is not found", "Error");
return;
}
// Opens the Preview window.
grid.ShowPrintPreview();
}
The image below illustrates the Preview window for a sample grid.
Refer to the XtraPrinting Library documentation for more information on the functionality provided by the print preview window.
To customize general print/export settings (e.g., page orientation and margins), handle the BaseView.PrintInitialize event.
#Modifying Print Appearances
By default, a printed grid utilizes the same appearances as when it is displayed onscreen (these appearance settings can be customized for each View using the BaseView.Appearance property).
However, each View provides print appearances used to paint the View's visual elements (buttons, headers, cells, etc.) in print output.
To use print appearances instead of display appearances when the grid is printed, set the View's OptionsPrint.UsePrintStyles option to true.
Use the View's BaseView.AppearancePrint object to adjust print appearances. This object provides multiple properties with which you can specify the appearance settings for various View elements (for Grid Views - data and group rows, even and odd data rows, filter panel, footer panel, etc.; for Card Views - card caption, field value, etc.).
The following image illustrates the print appearances for a Grid View in the Properties window.
The code below shows how to enable print appearances and customize the background color of even rows.
gridView1.OptionsPrint.UsePrintStyles = true;
// Enable AppearancePrint.EvenRow property settings.
gridView1.OptionsPrint.EnableAppearanceEvenRow = true;
// Set the background color for even rows.
gridView1.AppearancePrint.EvenRow.BackColor = Color.LightYellow;
The result is displayed in the image below.
The printing appearances can also be customized in the Print Appearances Page of the Grid Designer.
#Printing Options
Each View provides a set of options that specify the View elements to be printed, as well as the appearance settings to be used to paint these elements when the grid control is printed. These options can be accessed as follows.
-
At design time, using the Print Settings Page of the Grid Designer.
-
At design time and in code, with the OptionsPrint property (see GridView.OptionsPrint, BandedGridView.OptionsPrint and CardView.OptionsPrint, LayoutView.OptionsPrint and TileView.OptionsPrint).
-
By an end-user at runtime, in the Print Options dialog invoked by clicking the "Options" menu command in the Preview window.
SEE ALSO
Advanced Grid Printing and Exporting
How to: Print a Grid and Show its Print Preview
How to: Customize Print Settings When Printing GridControl
How to: Set Paper Format and Add Custom Information to the Report when Printing/Exporting a Control
We are updating the DevExpress product documentation website and this page is part of our new experience. During this transition period, product documentation remains available in our previous format at documentation.devexpress.com. Learn More...
Advanced Grid Printing and Exporting
- Jun 26, 2019
- 6 min to read
The report generation feature provides an advanced way to print and export your WinForms Grid Control data. You can easily generate a report from the grid data either at design time or at runtime, taking into account the grid layout. During report generation, it is possible to specify print appearance settings and control which grid elements are added to the report.
You can then modify the generated report as required, delegate report customization to an end-user, send the report to a printer or export it to various formats, and allow the end-user to do this manually.
NOTE
The report generation feature is supported for the following GridControl Views: GridView, BandedGridView and AdvBandedGridView.
The following sections provide details on how to generate and use grid reports.
- Supported Grid Features
- Limitations
- Generating a Report at Design Time
- Scenarios of Using the Generated Report
- Generating a Report in Code
#Supported Grid Features
The report generation engine takes into account the following grid features and settings.
- Binding settings of columns.
- Unbound columns, whose values are calculated based on expressions. See GridColumn.UnboundExpression.
- Group, sort and filter settings.
- Group and total summaries.
- Appearance of columns (GridColumn.AppearanceHeader and GridColumn.AppearanceCell).
- Appearance of rows
- Conditional formatting rules that are based on expressions.
- Grid bands (when exporting data from BandedGridView and AdvBandedGridView).
- Sparklines (embedded into grid cells)
- Boolean column values are presented by check boxes in the output report.
#Limitations
The following features are not supported by the report generation engine.
- Unbound columns populated using the ColumnView.CustomUnboundColumnData event.
- Any customization made using grid events.
- Conditional formatting rules that are not based on expressions.
#Generating a Report at Design Time
To generate a report based on GridControl's data at design time, do the following.
-
Locate the ReportGenerator component in the Toolbox and drag-and-drop it onto the application form.
-
Click the ReportGenerator's smart tag and select Generate Report.
-
On the first page of the invoked Report Wizard, select the GridControl's View for which the report is to be generated and click Next.
NOTE
Currently, reports can only be generated for GridViews, BandedGridViews and AdvBandedGridViews.
-
The next wizard page allows you to select the grid elements to be included in the report.
- Print Column Headers - Specifies whether to add column headers to the report.
- Print Total Summary Footer - Specifies whether to add the summary footer to the report.
The preview pane immediately reflects the changes made to the options. Click Next.
-
This wizard page allows you to specify data grouping-specific settings.
- Print Group Rows - Specifies whether to include group rows in the report.
- Print Group Summary Footer - Specifies whether to add group footers to the report.
-
In the Styles wizard page, choose whether dedicated print styles or default styles should be used when generating a report. The preview shows how these options change the report's appearance.
- Use Print Appearances - Specifies whether dedicated print appearance settings (GridView.AppearancePrint) or regular appearance settings (GridView.Appearance) are used when generating a report.
- Enable Even Row Print Appearance - Specifies whether even rows in the resulting report are painted using the appearance settings provided by the GridViewPrintAppearances.EvenRow property. This option is in effect if the Use Print Appearances setting is enabled.
- Enable Odd Row Print Appearance - Specifies whether odd rows in the resulting report are painted using the appearance settings provided by the GridViewPrintAppearances.OddRow property. This option is in effect if the Use Print Appearances setting is enabled.
- Print Vertical Lines - Specifies the visibility of vertical grid lines in the report.
- Print Horizontal Lines - Specifies the visibility of horizontal grid lines in the report.
-
In the next page, specify the title for the generated report and click Finish to complete the wizard.
#Scenarios of Using the Generated Report
The generated report is automatically added to the current project under the specified name and opened in the advanced Report Designer, which is fully integrated into the Visual Studio IDE. The report's declaration can be found in the file with the same name as the report name.
The report designer provides rich creating, editing and publishing capabilities including the following.
- Print, Print Preview, and Export actions
- Modifying report element layouts
- Modifying report element appearances
- Applying data grouping, sorting and filtering
- Adding totals
- Adding page numbers and system information
- etc.
See the Visual Studio Report Designer document for more information about report design-time customization.
After the report is generated and customized, you can show the report's print preview to your end-users.
It is possible to delegate report customization to end-users. They can use the End-User Report Designer to manually modify the report, show a Print Preview, export the report, etc. For more information, refer to the Report Designer document.
The following code creates a new instance of the generated report class and opens it in the End-User Report Designer.
using DevExpress.XtraReports.UI;
//...
MyReport report = new MyReport();
ReportDesignTool designTool = new ReportDesignTool(report);
designTool.ShowDesignerDialog();
#Generating a Report in Code
At runtime, a report can be generated using the static ReportGenerator.GenerateReport method of the ReportGenerator class.
using DevExpress.XtraReports.ReportGeneration;
// ...
XtraReport report = ReportGenerator.GenerateReport(gridView1);
When generating a report in code, you can also take into account dedicated report generation options (those that are available in the Report Generation Wizard). To do this, create a ReportGenerationOptions class instance, set its appropriate properties and pass it as the last parameter to the GenerateReport method.
ReportGenerationOptions options = new ReportGenerationOptions();
options.PrintGroupSummaryFooter = DefaultBoolean.False;
// ...
XtraReport report = ReportGenerator.GenerateReport(gridView1, options);
To take advantage of binding expressions, use the ReportGenerator.GenerateReport method with the useExpressionBindings Boolean parameter set to true. Binding expressions provide advanced capabilities for further customization of the generated report. See Data Binding Modes to learn more.
//...
XtraReport report = ReportGenerator.GenerateReport(gridView1, options, true);
We are updating the DevExpress product documentation website and this page is part of our new experience. During this transition period, product documentation remains available in our previous format at documentation.devexpress.com. Learn More...