windowsforms-311-controls-and-libraries-tree-list-feature-center-print-tree-list.md
The XtraPrinting library allows you to print the TreeList control. Note that you can only print controls if the project references this library.
The ShowRibbonPrintPreview() method invokes the Preview window, which allows a user to do the following:
Commands in the window are displayed in the ribbon. You can also call the ShowPrintPreview() method, which invokes the print preview window where commands are displayed in bars.
A user can call the following commands in the ribbon:
Print — invokes the Print dialog, which allows a user to select a printer, specify the number of copies, define the page range, and print the control. You can call the PrintDialog() method to invoke this dialog.
Quick Print — prints the control without the Print dialog. You can call the Print() method to print the control without the Print dialog.
Options — invokes the Print Options window, which allows a user to specify the visual elements that should be printed (vertical grid lines, headers, etc.). You can use the OptionsPrint property to access these options in code.
The code below displays a notification if the control cannot be printed. To check whether it is possible to print the control, the code uses the IsPrintingAvailable property. The example also uses the following methods:
using DevExpress.XtraTreeList;
using DevExpress.XtraEditors;
private void ShowTreeListPreview(TreeList treeList) {
if (!treeList.IsPrintingAvailable) {
XtraMessageBox.Show("Print library not found", "Error");
return;
}
treeList.ShowRibbonPrintPreview();
}
private void PrintTreeList(TreeList treeList) {
if (!treeList.IsPrintingAvailable) {
XtraMessageBox.Show("Print library not found", "Error");
return;
}
treeList.Print();
}
Imports DevExpress.XtraTreeList
Imports DevExpress.XtraEditors
Sub ShowTreeListPreview(ByVal treeList As TreeList)
If Not treeList.IsPrintingAvailable Then
XtraMessageBox.Show("Print library not found", "Error")
Return
End If
treeList.ShowRibbonPrintPreview()
End Sub
Sub PrintTreeList(ByVal treeList As TreeList)
If Not treeList.IsPrintingAvailable Then
XtraMessageBox.Show("Print library not found", "Error")
Return
End If
treeList.Print()
End Sub
The Options command in the print preview invokes a window that allows a user to specify the visual elements to be printed. You can use the OptionsPrint property to access these options in code.
Use the Print Settings page in the TreeList Designer to specify print settings.
You can also use the Properties window in Visual Studio to access the OptionsPrint property.
You can use the following properties to specify the control’s appearance settings:
Use the Print Appearances page in the TreeList Designer to specify appearance settings.
You can also use the Properties window in Visual Studio to access the AppearancePrint property.
The code below sets the UsePrintStyles property to true to enable print appearance settings. The EvenRow property specifies the background color for even nodes.
treeList1.OptionsPrint.UsePrintStyles = true;
treeList1.AppearancePrint.EvenRow.BackColor = Color.FromArgb(255, 192, 128);
TreeList1.OptionsPrint.UsePrintStyles = True
TreeList1.AppearancePrint.EvenRow.BackColor = Color.FromArgb(255, 192, 128)
To customize the appearance of an individual cell, use the NodeCellStyle event. Also note that events used to draw cells on-screen (for example, CustomDrawNodeCell) are not in effect when the control is printed.
The control can display summaries in footers. You can apply a predefined summary function or use the GetCustomSummaryValue event for custom calculations. The GetPrintCustomSummaryValue event allows you to specify custom summaries in the printed control.
The code below displays the number of departments that exceed the specified budget in the summary footer. The code handles the following events:
Note that the ShowSummaryFooter option should be enabled. The SummaryFooter property should be set to Custom. The SummaryFooterStrFormat property specifies the text that contains the calculated value.
using DevExpress.XtraTreeList.Columns;
using DevExpress.XtraTreeList.Nodes;
using DevExpress.XtraTreeList.Nodes.Operations;
treeList1.OptionsView.ShowSummaryFooter = true;
colBUDGET.SummaryFooter = DevExpress.XtraTreeList.SummaryItemType.Custom;
colBUDGET.SummaryFooterStrFormat = "Departments exceeded the budget: {0}";
treeList1.GetPrintCustomSummaryValue += (s, e) => {
if (e.IsSummaryFooter && e.Column == colBUDGET) {
TreeListExceedLimitOperation operation =
new TreeListExceedLimitOperation("BUDGET", 500000);
treeList1.NodesIterator.DoOperation(operation);
e.CustomValue = operation.Result;
}
};
treeList1.GetCustomSummaryValue += (s, e) => {
if (e.IsSummaryFooter && e.Column == colBUDGET) {
TreeListExceedLimitOperation operation =
new TreeListExceedLimitOperation("BUDGET", 100000);
treeList1.NodesIterator.DoOperation(operation);
e.CustomValue = operation.Result;
}
};
// An operation that counts the number of nodes
// that have a specific value in a specific column
public class TreeListExceedLimitOperation : TreeListOperation {
private string fieldName;
private int upperLimit;
private int value;
public TreeListExceedLimitOperation(string fieldName, int upperLimit) {
this.fieldName = fieldName;
this.upperLimit = upperLimit;
value = 0;
}
// This method is called for each node in the control.
public override void Execute(TreeListNode node) {
int nodeValue = Convert.ToInt32(node[fieldName]);
if (nodeValue > upperLimit)
value++;
}
public int Result {
get { return value; }
}
}
Imports DevExpress.XtraTreeList.Columns
Imports DevExpress.XtraTreeList.Nodes
Imports DevExpress.XtraTreeList.Nodes.Operations
treeList1.OptionsView.ShowSummaryFooter = True
colBUDGET.SummaryFooter = DevExpress.XtraTreeList.SummaryItemType.Custom
colBUDGET.SummaryFooterStrFormat = "Departments exceeded the budget: {0}"
AddHandler treeList1.GetPrintCustomSummaryValue, Sub(s, e)
If e.IsSummaryFooter AndAlso e.Column Is colBUDGET Then
Dim operation As New TreeListExceedLimitOperation("BUDGET", 500000)
treeList1.NodesIterator.DoOperation(operation)
e.CustomValue = operation.Result
End If
End Sub
AddHandler treeList1.GetCustomSummaryValue, Sub(s, e)
If e.IsSummaryFooter AndAlso e.Column Is colBUDGET Then
Dim operation As New TreeListExceedLimitOperation("BUDGET", 100000)
treeList1.NodesIterator.DoOperation(operation)
e.CustomValue = operation.Result
End If
End Sub
' An operation that counts the number of nodes
' that have a specific value in a specific column
Public Class TreeListExceedLimitOperation
Inherits TreeListOperation
Private fieldName As String
Private upperLimit As Integer
Private value As Integer
Public Sub New(ByVal fieldName As String, ByVal upperLimit As Integer)
Me.fieldName = fieldName
Me.upperLimit = upperLimit
value = 0
End Sub
' This method is called for each node in the control.
Public Overrides Sub Execute(ByVal node As TreeListNode)
Dim nodeValue As Integer = Convert.ToInt32(node(fieldName))
If nodeValue > upperLimit Then
value += 1
End If
End Sub
Public ReadOnly Property Result() As Integer
Get
Return value
End Get
End Property
End Class
A preview section is a non-editable note displayed across all columns under a node. To display preview sections, enable the ShowPreview option.
You can use the PreviewFieldName property or the GetPreviewText event to specify the text displayed in the preview sections.
To print preview sections, enable the PrintPreview option. You can also handle the GetPrintPreviewText event to specify custom text in the printed control.
To specify the preview appearance, use the Preview setting. You can use the Appearance or AppearancePrint property to access this setting.
The code below handles the TreeList.GetPreviewText and TreeList.GetPrintPreviewText events to specify different preview section content for the control when it is displayed on-screen and when it is printed (text is displayed on two lines).
using DevExpress.XtraTreeList;
treeList1.OptionsView.ShowPreview = true;
private void treeList1_GetPreviewText(object sender, GetPreviewTextEventArgs e) {
e.PreviewText = "Office location: " + e.Node["Location"].ToString() +
"; Contact phone: " + e.Node["Phone"].ToString();
}
private void treeList1_GetPrintPreviewText(object sender, GetPreviewTextEventArgs e) {
e.PreviewText = "Office location: " + e.Node["Location"].ToString() +
"\nContact phone: " + e.Node["Phone"].ToString();
}
Imports DevExpress.XtraTreeList
treeList1.OptionsView.ShowPreview = True
Private Sub TreeList1_GetPreviewText(ByVal sender As Object, _
ByVal e As GetPreviewTextEventArgs) Handles TreeList1.GetPreviewText
e.PreviewText = "Office location: " + e.Node("Location") + _
"; Contact phone: " + e.Node("Phone")
End Sub
Private Sub TreeList1_GetPrintPreviewText(ByVal sender As Object, _
ByVal e As GetPreviewTextEventArgs) Handles TreeList1.GetPrintPreviewText
e.PreviewText = "Office location: " + e.Node("Location") + _
vbCrLf + "Contact phone: " + e.Node("Phone")
End Sub
You can also use the PrintableComponentLink to print the control. The link accesses advanced settings — the paper size, margins, headers, footers, etc. See the following help topic for an example: How to: Set Paper Format and Add Custom Information to the Report when Printing/Exporting a Control.
See Also
How to: Set Paper Format and Add Custom Information to the Report when Printing/Exporting a Control