xtrareports-2571-desktop-reporting-winforms-reporting-winforms-reporting-print-preview-api-and-customization-use-printing-system-commands.md
Various user actions in Print Preview correspond to Printing System commands listed in the PrintingSystemCommand enumeration.
This document describes how to use these commands to manipulate Print Preview UI elements.
You can execute Printing System commands by calling the PrintControl.ExecCommand method that calls the PrintingSystemBase.ExecCommand method internally.
Tip
Before using this method, call the PrintControl.CanExecCommand method to ensure valid command execution.
This example illustrates how to execute Printing System commands in code.
using DevExpress.XtraPrinting;
using DevExpress.XtraPrinting.Control;
using DevExpress.XtraReports.UI;
// ...
private void button1_Click(object sender, System.EventArgs e) {
// Create a Print Tool with an assigned report instance.
ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());
// Access different Print Preview forms' Print Control.
PrintControl printControl = printTool.PreviewForm.PrintControl;
//PrintControl printControl = printTool.PreviewRibbonForm.PrintControl;
// Zoom the document, so that it fits the entire page into the Print Preview's dimensions.
if (printControl.CanExecCommand(PrintingSystemCommand.ViewWholePage)) {
printControl.ExecCommand(PrintingSystemCommand.ViewWholePage);
}
// Invoke the Hand tool to scroll the document using the mouse.
if (printControl.CanExecCommand(PrintingSystemCommand.HandTool)) {
printControl.ExecCommand(PrintingSystemCommand.HandTool, new object[] { true });
}
// Hide the Hand tool.
//if (printControlCanExecCommand(PrintingSystemCommand.HandTool)) {
// printControl.ExecCommand(PrintingSystemCommand.HandTool, new object[] { false });
//}
// Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog();
//printTool.ShowRibbonPreviewDialog();
}
Imports DevExpress.XtraPrinting
Imports DevExpress.XtraPrinting.Control
Imports DevExpress.XtraReports.UI
' ...
Private Sub button1_Click(sender As Object, e As System.EventArgs)
' Create a Print Tool with an assigned report instance.
Dim printTool As New ReportPrintTool(New XtraReport1())
' Access different Print Preview forms' Print Control.
Dim printControl As PrintControl = printTool.PreviewForm.PrintControl
'Dim printControl As PrintControl = printTool.PreviewRibbonForm.PrintControl
' Zoom the document, so that it fits the entire page into the Print Preview's dimensions.
If printControl.CanExecCommand(PrintingSystemCommand.ViewWholePage) Then
printControl.ExecCommand(PrintingSystemCommand.ViewWholePage)
End If
' Invoke the Hand tool to scroll the document using the mouse.
If printControl.CanExecCommand(PrintingSystemCommand.HandTool) Then
printControl.ExecCommand(PrintingSystemCommand.HandTool, New Object() {True})
End If
' Hide the Hand tool.
'If printControlCanExecCommand(PrintingSystemCommand.HandTool) Then
' printControl.ExecCommand(PrintingSystemCommand.HandTool, New Object() {False})
'End If
' Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog()
'printTool.ShowRibbonPreviewDialog()
End Sub
You can change the default behavior of Printing System commands by overriding them.
This example illustrates how to override a Printing System command.
A custom command handler must implement the ICommandHandler interface. To add it to a Printing System’s list of handlers, use the PrintingSystemBase.AddCommandHandler method.
using DevExpress.XtraPrinting;
using DevExpress.XtraReports.UI;
// ...
private void button1_Click(object sender, System.EventArgs e) {
// Create a Print Tool with an assigned report instance.
ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());
// Generate the report's document to access its Printing System.
printTool.Report.CreateDocument(false);
// Override the ExportGraphic command.
printTool.PrintingSystem.AddCommandHandler(new ExportToImageCommandHandler());
// Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog();
}
public class ExportToImageCommandHandler : ICommandHandler {
public virtual void HandleCommand(PrintingSystemCommand command,
object[] args, IPrintControl printControl, ref bool handled) {
if (!CanHandleCommand(command, printControl)) return;
// Export the document to PNG.
printControl.PrintingSystem.ExportToImage("Report.png", System.Drawing.Imaging.ImageFormat.Png);
// Prevent the default export procedure from being called.
handled = true;
}
public virtual bool CanHandleCommand(PrintingSystemCommand command, IPrintControl printControl) {
return command == PrintingSystemCommand.ExportGraphic;
}
}
Imports DevExpress.XtraPrinting
Imports DevExpress.XtraReports.UI
' ...
Private Sub button1_Click(sender As Object, e As System.EventArgs)
' Create a Print Tool with an assigned report instance.
Dim printTool As New ReportPrintTool(New XtraReport1())
' Generate the report's document to access its Printing System.
printTool.Report.CreateDocument(False)
' Override the ExportGraphic command.
printTool.PrintingSystem.AddCommandHandler(New ExportToImageCommandHandler())
' Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog()
End Sub
Public Class ExportToImageCommandHandler
Implements ICommandHandler
Private Sub HandleCommand(command As PrintingSystemCommand, args() As Object,
printControl As IPrintControl, ByRef handled As Boolean) _
Implements ICommandHandler.HandleCommand
If Not CanHandleCommand(command, printControl) Then
Return
End If
' Export the document to PNG.
printControl.PrintingSystem.ExportToImage("Report.png", System.Drawing.Imaging.ImageFormat.Png)
' Prevent the default export procedure from being called.
handled = True
End Sub
Private Function CanHandleCommand(command As PrintingSystemCommand,
printControl As IPrintControl) As Boolean _
Implements ICommandHandler.CanHandleCommand
Return command = PrintingSystemCommand.ExportGraphic
End Function
End Class
Consider that Interactive Features, such as sorting or drill-down, affect override commands as follows: when interactive features are enabled, the report document may be regenerated to apply changes. This affects custom commands causing them to suddenly stop working because these command are not recognized by the newly created PrintingSystem. To get around this issue, handle the DocumentViewerBase.DocumentChanged event.
Tip
See the following tutorials to learn how to add custom items to a Print Preview toolbar:
The Printing System defines UI elements‘ visibility corresponding to its commands (such as toolbar buttons or menu items). You can maintain their visibility in Print Preview using the PrintingSystemBase.SetCommandVisibility method.
This example illustrates how to change UI elements’ visibility in the Print Preview using Printing System commands.
using DevExpress.XtraPrinting;
using DevExpress.XtraReports.UI;
// ...
private void button1_Click(object sender, System.EventArgs e) {
// Create a Print Tool with an assigned report instance.
ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());
// Access the Print Tool's Printing System.
PrintingSystemBase printingSystem = printTool.PrintingSystem;
// Remove the Watermark command from the Print Preview UI.
if (printingSystem.GetCommandVisibility(PrintingSystemCommand.Watermark)
!= CommandVisibility.None) {
printingSystem.SetCommandVisibility(PrintingSystemCommand.Watermark,
CommandVisibility.None);
}
// Enable the Document Map command in the Print Preview UI.
printingSystem.SetCommandVisibility(PrintingSystemCommand.DocumentMap,
CommandVisibility.All);
// Disable document export to any format.
printingSystem.SetCommandVisibility(new PrintingSystemCommand[] {
PrintingSystemCommand.ExportCsv, PrintingSystemCommand.ExportTxt, PrintingSystemCommand.ExportDocx,
PrintingSystemCommand.ExportHtm, PrintingSystemCommand.ExportMht, PrintingSystemCommand.ExportPdf,
PrintingSystemCommand.ExportRtf, PrintingSystemCommand.ExportXls, PrintingSystemCommand.ExportXlsx,
PrintingSystemCommand.ExportGraphic },
CommandVisibility.None);
// Enable the "Export to CSV" and "Export to TXT" commands.
printingSystem.SetCommandVisibility(new PrintingSystemCommand[] {
PrintingSystemCommand.ExportCsv, PrintingSystemCommand.ExportTxt },
CommandVisibility.All);
// Disable export and mailing of documents.
printingSystem.SetCommandVisibility(new PrintingSystemCommand[] {
PrintingSystemCommand.SendFile },
CommandVisibility.None);
// Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog();
}
Imports DevExpress.XtraPrinting
Imports DevExpress.XtraReports.UI
' ...
Private Sub button1_Click(sender As Object, e As System.EventArgs)
' Create a Print Tool with an assigned report instance.
Dim printTool As New ReportPrintTool(New XtraReport1())
' Access the Print Tool's Printing System.
Dim printingSystem As PrintingSystemBase = printTool.PrintingSystem
' Remove the Watermark command from the Print Preview UI.
If printingSystem.GetCommandVisibility(PrintingSystemCommand.Watermark) <> CommandVisibility.None Then
printingSystem.SetCommandVisibility(PrintingSystemCommand.Watermark, CommandVisibility.None)
End If
' Enable the Document Map command in the Print Preview UI.
printingSystem.SetCommandVisibility(PrintingSystemCommand.DocumentMap, CommandVisibility.All)
' Disable document export to any format.
printingSystem.SetCommandVisibility(New PrintingSystemCommand() { _
PrintingSystemCommand.ExportCsv, PrintingSystemCommand.ExportTxt, PrintingSystemCommand.ExportDocx, _
PrintingSystemCommand.ExportHtm, PrintingSystemCommand.ExportMht, PrintingSystemCommand.ExportPdf, _
PrintingSystemCommand.ExportRtf, PrintingSystemCommand.ExportXls, PrintingSystemCommand.ExportXlsx, _
PrintingSystemCommand.ExportGraphic}, CommandVisibility.None)
' Enable the "Export to CSV" and "Export to TXT" commands.
printingSystem.SetCommandVisibility(New PrintingSystemCommand() { _
PrintingSystemCommand.ExportCsv, PrintingSystemCommand.ExportTxt}, _
CommandVisibility.All)
' Disable export and mailing of documents.
printingSystem.SetCommandVisibility(New PrintingSystemCommand() { _
PrintingSystemCommand.SendFile}, _
CommandVisibility.None)
' Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog()
End Sub
Dock panels can be hidden from the Print Preview by calling the PrintControl.ExecCommand method with a corresponding parameter.
Tip
Before using this method, call the PrintControl.CanExecCommand method to ensure valid command execution.
This example illustrates how to hide various dock panels from Print Preview and remove the corresponding buttons from its toolbar.
using DevExpress.XtraPrinting;
using DevExpress.XtraPrinting.Control;
using DevExpress.XtraReports.UI;
// ...
private void button1_Click(object sender, System.EventArgs e) {
// Create a Print Tool with an assigned report instance.
ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());
// Access different Print Preview forms' Print Control.
PrintControl printControl = printTool.PreviewForm.PrintControl;
//PrintControl printControl = printTool.PreviewRibbonForm.PrintControl;
// Hide the Thumbnails and Document Map panels.
if (printControl.CanExecCommand(PrintingSystemCommand.DocumentMap)) {
printControl.ExecCommand
(PrintingSystemCommand.DocumentMap, new object[] { false });
}
if (printControl.CanExecCommand(PrintingSystemCommand.Thumbnails)) {
printControl.ExecCommand
(PrintingSystemCommand.Thumbnails, new object[] { false });
}
// Show the Thumbnails and Document Map panels.
//if (printControl.CanExecCommand(PrintingSystemCommand.DocumentMap)) {
// printControl.ExecCommand
// (PrintingSystemCommand.DocumentMap, new object[] { true });
//}
//if (printControl.CanExecCommand(PrintingSystemCommand.Thumbnails)) {
// printControl.ExecCommand
// (PrintingSystemCommand.Thumbnails, new object[] { true });
//}
// Hide the Thumbnails and Document Map buttons.
printTool.PrintingSystem.SetCommandVisibility
(PrintingSystemCommand.DocumentMap, CommandVisibility.None);
printTool.PrintingSystem.SetCommandVisibility
(PrintingSystemCommand.Thumbnails, CommandVisibility.None);
// Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog();
//printTool.ShowRibbonPreviewDialog();
}
Imports DevExpress.XtraPrinting
Imports DevExpress.XtraPrinting.Control
Imports DevExpress.XtraReports.UI
' ...
Private Sub button1_Click(sender As Object, e As System.EventArgs)
' Create a Print Tool with an assigned report instance.
Dim printTool As New ReportPrintTool(New XtraReport1())
' Access different Print Preview forms' Print Control.
Dim printControl As PrintControl = printTool.PreviewForm.PrintControl
'Dim printControl As PrintControl = printTool.PreviewRibbonForm.PrintControl
' Hide the Thumbnails and Document Map panels.
If printControl.CanExecCommand(PrintingSystemCommand.DocumentMap) Then
printControl.ExecCommand( _
PrintingSystemCommand.DocumentMap, New Object() {False})
End If
If printControl.CanExecCommand(PrintingSystemCommand.Thumbnails) Then
printControl.ExecCommand( _
PrintingSystemCommand.Thumbnails, New Object() {False})
End If
' Show the Thumbnails and Document Map panels.
'If printControl.CanExecCommand(PrintingSystemCommand.DocumentMap) Then
' printControl.ExecCommand( _
' PrintingSystemCommand.DocumentMap, New Object() {True})
'End If
'If printControl.CanExecCommand(PrintingSystemCommand.Thumbnails) Then
' printControl.ExecCommand( _
' PrintingSystemCommand.Thumbnails, New Object() {True})
'End If
' Hide the Thumbnails and Document Map buttons.
printTool.PrintingSystem.SetCommandVisibility( _
PrintingSystemCommand.DocumentMap, CommandVisibility.None)
printTool.PrintingSystem.SetCommandVisibility( _
PrintingSystemCommand.Thumbnails, CommandVisibility.None)
' Show the report's Print Preview in a dialog window.
printTool.ShowPreviewDialog()
'printTool.ShowRibbonPreviewDialog()
End Sub