xtrareports-16128-feature-guide-to-devexpress-reports-add-extra-information-add-watermarks-to-a-report.md
DevExpress Reporting allows you to display text and picture watermarks on report pages. You can also specify an expression that assigns different watermarks to pages.
This tutorial includes information about the following tasks:
How to add watermarks.
How to specify watermark settings.
How to manage watermarks at runtime.
How to use pre-printed forms.
How to define watermark accessibility settings.
Click the report’s smart tag. Click the Watermark property’s ellipsis button.
In the invoked Watermark collection editor, select the Text Settings tab to add a text watermark, or the Picture Settings tab to add a picture watermark.
Specify the following settings:
TextThe watermark’s text.DirectionThe incline of the watermark’s text.FontThe font of the watermark’s text.Color The foreground color of the watermark’s text.Size The size of the watermark’s text.Bold Formats the watermark’s text as bold.Italic Formats the watermark’s text as italic.PositionSpecifies whether a watermark should be printed behind or in front of page content.Transparency The transparency of the watermark’s text.RoleSpecifies the role of a text watermark in the exported PDF document. This value is used by assistive technologies.DescriptionSpecifies the description of a text watermark used by assistive technologies.Id The unique identifier of a watermark used to specify the watermark in the WatermarkId property (See the Manage Watermark Collection section for details).Page Range The range of pages which contain a watermark.
Click OK to add a watermark to the watermark collection. The added watermark is automatically displayed in the report in Preview mode.
Note
A report can display only one watermark on a report page.
Specify an image. Click the Load image option’s Browse button.
In the invoked Select Picture dialog, select the file that contains the watermark image and click Open.
Specify the following picture options:
Size ModeThe mode in which a picture watermark is displayed.TilingSpecifies whether a picture watermark should be tiled.Horizontal Alignment Specifies the horizontal alignment of the watermark.Vertical AlignmentSpecifies the vertical alignment of the watermark.PositionSpecifies whether a watermark should be printed behind or in front of page content.TransparencyThe transparency of the watermark’s image.RoleSpecifies the role of an image watermark in the exported PDF document. This value is used by assistive technologies.DescriptionSpecifies the description of an image watermark used by assistive technologies.IdThe unique identifier of a watermark used to specify the watermark in the WatermarkId property (See the Manage Watermark Collection section for details).Page RangeThe range of pages which contain a watermark.
Note
The Transparency property is unavailable when users specify an SVG image.
Click OK to add a watermark to the watermark collection. The added watermark is automatically displayed in the report in Preview mode.
Note
A report can display only one watermark on a report page.
You can show a picture watermark on the report’s body at design time as a preprinted form template.
The image below demonstrates a preprinted form template.
Add a template image to a report as a watermark image. Set the report’s XtraReport.DrawWatermark property to True in the Properties window.
Place report controls on the report’s body according to the preprinted form layout.
A picture watermark supports the following formats:
You can display both text and a picture in one Watermark. Use the PageWatermark.TextPosition and PageWatermark.ImagePosition properties of the watermark to specify whether the text and picture should be displayed behind or in front of page content.
For example, create a watermark and specify its text and picture settings.
Set position of the text to In front :
Set position of the picture to Behind :
As a result, the image is displayed behind the table, while the text is in front of the content:
The XtraReport.Watermarks property holds a WatermarkCollection that contains all Watermark objects in the report.
This example demonstrates how to add a watermark to a report. The SetTextWatermark method demonstrates the properties you can use to add a text watermark to a report; the SetPictureWatermark method demonstrates properties required to set a picture as the report’s watermark.
using System.Drawing;
using DevExpress.XtraPrinting.Drawing;
using DevExpress.XtraReports.UI;
using DevExpress.Drawing;
// ...
public void SetTextWatermark(XtraReport report) {
// Create a new watermark.
XRWatermark textWatermark = new XRWatermark();
// Specify watermark settings.
textWatermark.Text = "CUSTOM WATERMARK TEXT";
textWatermark.TextDirection = DirectionMode.ForwardDiagonal;
textWatermark.Font = new DXFont(textWatermark.Font.Name, 40);
textWatermark.ForeColor = Color.DodgerBlue;
textWatermark.TextTransparency = 150;
textWatermark.TextPosition = WatermarkPosition.InFront;
textWatermark.PageRange = "1,3-5";
textWatermark.Id = "Watermark1";
// Add the watermark to the collection.
report.Watermarks.Add(textWatermark);
}
public void SetPictureWatermark(XtraReport report) {
XRWatermark pictureWatermark = new XRWatermark();
pictureWatermark.ImageSource = ImageSource.FromFile("Watermark.png");
pictureWatermark.ImageAlign = ContentAlignment.TopCenter;
pictureWatermark.ImageTiling = false;
pictureWatermark.ImageViewMode = ImageViewMode.Stretch;
pictureWatermark.ImageTransparency = 150;
pictureWatermark.ImagePosition = WatermarkPosition.Behind;
pictureWatermark.PageRange = "2,4";
pictureWatermark.Id = "Watermark2";
report.Watermarks.Add(pictureWatermark);
}
Imports System.Drawing
Imports DevExpress.XtraPrinting.Drawing
Imports DevExpress.XtraReports.UI
Imports DevExpress.Drawing
' ...
Public Sub SetTextWatermark(ByVal report As XtraReport)
' Create a new watermark.
Dim textWatermark As New XRWatermark()
' Specify watermark settings.
textWatermark.Text = "CUSTOM WATERMARK TEXT"
textWatermark.TextDirection = DirectionMode.ForwardDiagonal
textWatermark.Font = New DXFont(textWatermark.Font.Name, 40)
textWatermark.ForeColor = Color.DodgerBlue
textWatermark.TextTransparency = 150
textWatermark.TextPosition = WatermarkPosition.InFront
textWatermark.PageRange = "1,3-5"
textWatermark.Id = "Watermark1"
' Add the watermark to the collection.
report.Watermarks.Add(textWatermark)
End Sub
Public Sub SetPictureWatermark(ByVal report As XtraReport)
Dim pictureWatermark As New XRWatermark()
pictureWatermark.ImageSource = ImageSource.FromFile("Watermark.png")
pictureWatermark.ImageAlign = ContentAlignment.TopCenter
pictureWatermark.ImageTiling = False
pictureWatermark.ImageViewMode = ImageViewMode.Stretch
pictureWatermark.ImageTransparency = 150
pictureWatermark.ImagePosition = WatermarkPosition.Behind
pictureWatermark.PageRange = "2,4"
pictureWatermark.Id = "Watermark2"
report.Watermarks.Add(pictureWatermark)
End Sub
WatermarkId allows you to specify a watermark from the collection to display in the report. This property has a priority over the watermark’s PageRange property.
Create two watermarks in the Watermarks collection editor.
Set WatermarkId to Watermark2 (the Watermark.Id property value).
The image below shows the result.
The following code snippet adds two watermarks in WatermarkCollection and displays the second watermark in a report:
using DevExpress.Drawing;
using DevExpress.XtraPrinting.Drawing;
using DevExpress.XtraReports.UI;
// ...
XtraReportCategories report = new XtraReportCategories();
report.Watermarks.Add(CreateTextWatermark("First Watermark","Watermark1"));
report.Watermarks.Add(CreateTextWatermark("Second Watermark", "Watermark2"));
report.WatermarkId = "Watermark2";
report.ShowRibbonPreviewDialog();
// ...
private XRWatermark CreateTextWatermark(string text, string id) {
XRWatermark textWatermark = new XRWatermark();
textWatermark.Text = text;
textWatermark.Id = id;
textWatermark.TextDirection = DirectionMode.ForwardDiagonal;
textWatermark.Font = new DXFont("Verdana", 36);
textWatermark.TextPosition = WatermarkPosition.InFront;
textWatermark.ForeColor = Color.Red;
return textWatermark;
}
Imports DevExpress.Drawing
Imports DevExpress.XtraPrinting.Drawing
Imports DevExpress.XtraReports.UI
' ...
Partial Public Class Form1
Inherits Form
Public Sub New()
InitializeComponent()
Dim report As New XtraReportCategories()
report.Watermarks.Add(CreateTextWatermark("First Watermark","Watermark1"))
report.Watermarks.Add(CreateTextWatermark("Second Watermark", "Watermark2"))
report.WatermarkId = "Watermark2"
report.ShowRibbonPreviewDialog()
End Sub
' ...
Private Function CreateTextWatermark(ByVal text As String, ByVal id As String) As XRWatermark
Dim textWatermark As New XRWatermark()
textWatermark.Text = text
textWatermark.Id = id
textWatermark.TextDirection = DirectionMode.ForwardDiagonal
textWatermark.Font = New DXFont("Verdana", 36)
textWatermark.TextPosition = WatermarkPosition.InFront
textWatermark.ForeColor = Color.Red
Return textWatermark
End Function
End Class
You can also call the Page.AssignWatermark method to specify a unique watermark for different pages in a report. Page.AssignWatermark takes priority over WatermarkId.
View Example: Reporting for WinForms - How to Add Different Watermarks to Different Pages
Bind WatermarkId to an expression to apply watermarks stored in the collection to specific report pages.
Create the “First page watermark”, “Even page watermark”, and “Odd page watermark” watermarks with the following settings:
Specify the expression in the report’s WatermarkId property:
Iif([Arguments.PageIndex]=0,'Watermark_0',Iif([Arguments.PageIndex]%2=0,'Watermark_1','Watermark_2'))
The image below shows the result.
The following code snippet adds different watermarks to the first, odd, and even pages of XtraReport:
using DevExpress.XtraReports.UI;
// ...
public partial class XtraReport : DevExpress.XtraReports.UI.XtraReport {
private void XtraReport_BeforePrint(object sender, System.ComponentModel.CancelEventArgs e){
XtraReport report = new XtraReport();
ExpressionBinding watermarksBinding = new ExpressionBinding();
watermarksBinding.EventName = nameof(BeforePrint);
// Specify an expression that is rendered within the BeforePrint event.
watermarksBinding.Expression = "`Iif([Arguments.PageIndex]=0,'Watermark_0',Iif([Arguments.PageIndex]%2=0,'Watermark_1','Watermark_2'))`";
watermarksBinding.PropertyName = nameof(WatermarkId);
report.ExpressionBindings.Add(watermarksBinding);
}
}
Imports DevExpress.XtraReports.UI
' ...
Partial Public Class XtraReportCategories
Inherits DevExpress.XtraReports.UI.XtraReport
Private Sub XtraReport_BeforePrint(ByVal sender As Object, ByVal e As System.ComponentModel.CancelEventArgs)
Dim report As New XtraReport()
Dim watermarksBinding As New ExpressionBinding()
watermarksBinding.EventName = NameOf(BeforePrint)
' Specify an expression that is rendered within the BeforePrint event.
watermarksBinding.Expression = "`Iif([Arguments.PageIndex]=0,'Watermark_0',Iif([Arguments.PageIndex]%2=0,'Watermark_1','Watermark_2'))`"
watermarksBinding.PropertyName = NameOf(WatermarkId)
report.ExpressionBindings.Add(watermarksBinding)
End Sub
End Class
Review the following help topic for more information on how to bind expressions to report elements: Data Binding Modes.
Use the following properties to specify whether to include report watermarks in the logical structure of exported PDF documents:
For image watermarks that convey meaningful information, set the XRWatermark.ImageAccessibleRole property to XRAccessibleRole.Figure and use the XRWatermark.ImageAccessibleDescription property to specify alternative text.
For text watermarks, set the XRWatermark.TextAccessibleRole property to XRAccessibleRole.Paragraph and use the XRWatermark.TextAccessibleDescription property to specify alternative text.
For purely decorative watermarks, retain the default value to treat the watermark as an artifact.
In merged reports, only the watermark settings of the main report are applied; watermarks defined in subreports are ignored. For example, if a subreport contains its own watermark, it is not displayed in the merged document. To apply these watermarks, configure them in the main report and assign them to individual pages with the Page.AssignWatermark method.