Use Printing System Commands
- 7 minutes to read
Various user actions in the 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.
Execute Commands
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();
}
Override Commands
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. You can add it to a Printing System’s list of handlers using 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 be able 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("C:\\Report.png", System.Drawing.Imaging.ImageFormat.Png);
// Prevent the default exporting procedure from being called.
handled = true;
}
public virtual bool CanHandleCommand(PrintingSystemCommand command, IPrintControl printControl) {
return command == PrintingSystemCommand.ExportGraphic;
}
}
Tip
See the following tutorials to learn how to add custom items to a Print Preview’s toolbar:
Change the Visibility of Commands
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();
}
You can hide some of the dock panels from the Print Preview by calling the PrintControl.ExecCommand method with the 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();
}