XRRichText Class
A control that displays formatted text in a report.
Namespace: DevExpress.XtraReports.UI
Assembly: DevExpress.XtraReports.v26.1.dll
Declaration
public class XRRichText :
XRRichTextBase,
ISupportInitialize,
IDisplayNamePropertyContainerRemarks
To add the XRRichText control to a report, drag the XRRichText item from the DX:26.1: Report Controls Toolbox tab and drop it onto the report’s bands.
Specify Formatted Text
You can add RTF or HTML content to the XRRichText control in one of the following ways:
- Copy content from an external resource.
- Load content from a file.
- Bind the control to a field from a data source.
Refer to the following topic for information on supported HTML tags: HTML Tag Support.
Copy from an External Resource
To add formatted text from an external resource, copy the text, double-click the control, and paste the text into the control’s in-place editor. The following example shows an XRRichText control that contains formatted DevExpress Website Terms of Use text:
Load from a File
You can load content into the XRRichText control from RTF (.rtf, .docx, .txt) or HTML (.html or .htm ) files. Click the control’s smart tag and select Load File from the actions list. For the limitations that apply to loaded content, see Limitations.
Select a file in the invoked Open dialog. After the file’s content is loaded, use the Formatting Toolbar and the control’s in-place editor to edit the content.
Load from a Data Source
You can bind the XRRichText control’s Rtf (or Html) property to a data source field that contains RTF (or HTML) content.
Click the control’s smart tag, expand the Rtf (Html) Expression drop-down list, and select the field to which you want to bind the control.
You can also use the Field List to bind the Rtf property. Right-click a field in the Field List, drop the field onto the report, and choose the RichText item in the invoked menu. This creates the XRRichText control whose Rtf property is bound to the selected field.
Use expressions to specify a string that uses data from several data fields or to apply additional formatting to data. Click the Rtf (Html) Expression option’s ellipsis button and use the invoked Expression Editor to specify expressions.
Note
When you use expression bindings to supply content for the XRRichText control, the control applies the style settings defined in that content. Changes made through the control’s properties do not affect the content style. To modify the supplied content, use the RichEditDocumentServer component. Refer to the example that shows how to change the font of content loaded from a data source.
Accessible PDF Export
The XRRichText control supports export to accessible (tagged) PDF documents. During export, rich text content is converted into a logical structure that preserves semantic meaning and reading order.
This feature improves compatibility with screen readers and enables PDF/UA-compliant output.
Enable Accessible Export
Set the following property to PdfUA1 or PdfUA2 to export a document as an accessible PDF:
Accessible information is included only when this option is enabled.
Logical Structure
When exporting to an accessible PDF, the XRRichText control generates a logical structure tree based on the content of the rich text.
The export engine analyzes the document and maps elements to their corresponding semantic roles:
- Headings are exported as
H1,H2,H3, and so on. - Paragraphs are exported as
P. - Lists are exported as
L,LI, andLBody. - Images are exported as
Figure. - Tables are exported as
Table,TR,TH,TD.
This structure allows assistive technologies to interpret and navigate document content. Content is added to the logical structure in the same order as it appears in the document. This ensures that screen readers process text in the correct sequence.
The exported PDF document contains a structured representation of the rich text content and can be used with accessibility tools and screen readers:
Export Limitations
When exporting to an accessible PDF, table of contents items defined inside XRRichText are not recognized as TOCI elements. These items are tagged as paragraphs (P) in the document structure. Use XRTableOfContents to generate accessible table of contents entries (TOCI).
XLS(X)
Only the following content of the XRRichText control is exported to XLS and XLSX formats:
Text format | <b>, <i>, <u>, <s>, <strong>, <em> |
Line break | <br> |
Non-breaking space | |
Font | <font face=[font name]> |
Font size | <font size=[font size]> |
Foreground color | <font color=[color]> |
Runtime Examples
Create the XRRichText Control in Code
The following example creates an XRRichText control and specifies HTML content for this control:
using DevExpress.XtraReports.UI;
using System.Drawing;
// ...
public XRRichText createXRRichTextControlHtml() {
var richTextControl = new XRRichText() {
Html = "<b><u>Some content goes here...</b></u>",
SizeF = new SizeF(200.0F, 30.0F)
};
return richTextControl;
}
Change the Font of the XRRichText Control’s Content
This example uses the RichEditDocumentServer (Word Processing Document API) component to change the style settings of the RichText control’s content loaded from a data source.
Warning
The Office File API (Basic Edition), which included the Word Processing Document API and Excel Export API libraries, was discontinued on October 17, 2024. If you purchased a DevExpress Universal, DXperience, WinForms, WPF, Office File API, Reporting and ASP.NET subscription prior to October 17, 2024, our Office File API (Basic Edition) will remain available to you. If you are new to DevExpress and are interested in our Office File API, please refer to the following webpage for pricing/licensing information: DevExpress Office File API
using System.Drawing;
using System.Drawing.Printing;
using DevExpress.XtraReports.UI;
using DevExpress.XtraRichEdit;
// ...
private void xrRichText1_BeforePrint(object sender, System.ComponentModel.CancelEventArgs e) {
XRRichText richText = (XRRichText)sender;
using (RichEditDocumentServer docServer = new RichEditDocumentServer()) {
docServer.RtfText = richText.Rtf;
docServer.Document.DefaultCharacterProperties.FontName = richText.Font.ToString();
docServer.Document.DefaultCharacterProperties.FontSize = 15;
docServer.Document.DefaultCharacterProperties.ForeColor = Color.Green;
richText.Rtf = docServer.RtfText;
}
}
Limitations
- The
XRRichTextcontrol does not load headers, footers, footnotes, page breaks, and margins from RTF files. If you need to load margins of the RTF document, use the RichEditDocumentServer component to get the loaded document’s margin settings, and then adjust theXRRichTextcontrol’s position and width to these settings. - The
XRRichTextcontrol does not support vertical text. The control loads vertical text from RTF files as a horizontal textbox. - The
XRRichTextcontrol may render the specified content incorrectly (for instance, characters may overlap) if the specified content has the Character Spacing’s Scale property set to a non-default value. - In web applications, the inline client Rich Text Editor in the
XRRichTextcontrol does not support Right-To-Left mode. - The
XRRichTextcontrol does not display content if the Track Changes feature is enabled in an RTF document. All revisions must be accepted before the XRRichText control can display the content. - The
XRRichTextcontrol cannot paginate RTF content during export. - The
XRRichTextcontrol cannot ensure that its content is correctly split between report pages if the LineSpacing property value is less than the font size. - The
XRRichTextcontrol does not render HTML links (hyperlinks) on preview. You can use the XRRichText.NavigateUrl property to make the entireXRRichTextcontrol function as a hyperlink. HTML links are preserved when you export the report to PDF. - The
XRRichTextcontrol’sHtmlandRtfproperties are not localizable. If you only need to display formatted text in your report, you can use the XRLabel control and optionally enable its AllowMarkupText property.XRLabelsupports localization.