[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Collapse]WPF Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Common Concepts
 [Expand]MVVM Framework
 [Collapse]Controls and Libraries
   Reporting
  [Expand]Data Grid
  [Expand]Ribbon, Bars and Menu
  [Expand]Charts Suite
  [Expand]Pivot Grid
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Collapse]Rich Text Editor
   [Expand]Product Information
    Product Class Structure
    Supported Formats
   [Expand]Getting Started
   [Expand]RichEditControl Document
   [Expand]Fields
    Text Formatting
    Import and Export
   [Collapse]Page Layout
     Line Numbering
     Table of Contents
     Layout API
     Measure Units
    Printing
    AutoCorrect
    Mail Merge
    Restrictions and Protection
    Syntax Highlighting
   [Expand]Visual Elements
    Services
    Events
    Commands
    HTML Tag Support
   [Expand]Examples
  [Expand]Tree List
  [Expand]Gauge Controls
  [Expand]Map Control
  [Expand]Layout Management
  [Expand]Windows Modern UI
  [Expand]Printing-Exporting
  [Expand]Data Editors
  [Expand]Navigation Controls
  [Expand]Spell Checker
  [Expand]Property Grid
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Gantt Control
  [Expand]Diagram Control
  [Expand]Windows and Utility Controls
   Dialogs, Notifications and Panels
  [Expand]Scheduler (legacy)
 [Expand]Scaffolding Wizard
 [Expand]Localization
  Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Layout API

This document introduces the Rich Text Editor Layout API - objects, properties and methods that allow you traverse the document layout tree and access layout elements.

Expanded Layout API Overview

The Layout API is located in the DevExpress.RichEdit.v18.2.Core.dll assembly, and is available for both WinForms and WPF Rich Text Editor, as well as for Word Processing Document API. It can be used to arbitrarily display layout elements and draw graphics within the element boundaries (expected in future versions).

Expanded Layout API Object Model

The document layout model in the Layout API is a hierarchical tree-like structure. Each node in a tree is an instance of a certain class which implements a base interface named LayoutElement. A class representing a particular element is named after that element with addition of the prefix Layout or a suffix Box. There are LayoutPage, LayoutHeader, LayoutPageArea, LayoutFooter, ... BookmarkBox, PlainTextBox etc. A layout element may or may not have a related RangedLayoutElement.Range in the document.

The structure of a sample document is shown in the picture below. The document consists of three pages, has a header and a footer, the first page has a floating text box and a floating picture. The text is organized in one column, the first page has only three lines of text. The first line of text includes a floating object's anchor and five plain text boxes (a plain text box can be a space, a text with uniform formatting or a paragraph mark).

Tip

Call the HitTestManager.HitTest method to obtain the RichEditHitTestResult instance containing information about the element located under the test point. Refer to the How to: Determine the Document Element under the Mouse Pointer topic for details.

Expanded Starting Point

The main entry point of the Layout API in WPF Rich Editor is the RichEditControl.DocumentLayout property. This property provides access to the DocumentLayout object containing basic properties and methods for working with the hierarchy of the document layout objects. After any changes in text or formatting, the document layout is recalculated and the DocumentLayout.DocumentFormatted event fires.

Note

The DocumentFormatted event handler is running in a background thread. To avoid concurrency issues, execute the code which affects the document or interacts with the user asynchronously in a UI thread using the RichEditControl.BeginInvoke method.

Expanded Traversing Layout Tree

<<<<<<< articles/controls-and-libraries/rich-text-editor/page-layout/layout-api.md

The Iterator and the Visitor are independent at the document layout level. The LayoutIterator and LayoutVisitor allow you to collect information about document element's location (bounds, nearest element, etc.) and range.

The LayoutIterator and LayoutVisitor allow you to collect information about document element's location (bounds, nearest element, etc.) and range.

articles/controls-and-libraries/rich-text-editor/page-layout/layout-api.md

The table below compares LayoutIterator and LayoutVisitor features. This comparison allows you to decide what to use depending on your current task.

<<<<<<< articles/controls-and-libraries/rich-text-editor/page-layout/layout-api.md

LayoutVisitor LayoutIterator
Travel Direction Down Up and Down (using MoveNext (see LayoutIterator.MoveNext) and MovePrevious (see LayoutIterator.MovePrevious) methods).
Can Iterate Only a Specific Layout Level No Yes. Pass the one of the LayoutLevel (see LayoutLevel) values to the Move.. method to complete the task.
Visits Complex Layout Elements True. False. Create a new LayoutIterator when visiting complex elements (header/footer, floating objects, comments)

=======

  LayoutVisitor LayoutIterator
Travel Direction Down Up and Down (using MoveNext (see LayoutIterator.MoveNext) and MovePrevious (see LayoutIterator.MovePrevious) methods).
Can Iterate Only a Specific Layout Level No Yes. Pass the one of the LayoutLevel (see LayoutLevel) values to the Move.. method to complete the task.
Visits Complex Layout Elements True. False. Create a new LayoutIterator when visiting complex elements (header/footer, floating objects, comments)

articles/controls-and-libraries/rich-text-editor/page-layout/layout-api.md

Code samples below show how to use LayoutIterator and LayoutVisitor to count lines in the document's main body. The message box displays the result amount, as shown on the image.

Use LayoutIterator

Use LayoutVisitor

<<<<<<< articles/controls-and-libraries/rich-text-editor/page-layout/layout-api.md

=======

articles/controls-and-libraries/rich-text-editor/page-layout/layout-api.md

Expanded Custom Draw

The RichEditControl.BeforePagePaint event allows you to specify a descendant of the PagePainter class to implement custom draw for layout elements.

The following code snippet illustrates how to custom draw the PlainTextBox and LayoutFloatingPicture elements.

This code snippet illustrates the implementation of a PagePainter descendant. It draws color rectangles in place of the words and labels a floating picture with a text string drawn over it.

Is this topic helpful?​​​​​​​