Floating Objects (Shapes)

• Nov 17, 2018
• 4 minutes to read

This topic describes how the RichEditControl manages the floating objects and shapes - pictures and text boxes. Floating means that the object is strictly positioned, absolutely or relatively within the document, regardless of the text flow. An object anchor (seen in the picture below) specifies the paragraph with which an object is associated and indicates where a floating object is located in relation to the text.

Insert a Floating Object

To insert a floating object to the document, use the ShapeCollection.InsertPicture or ShapeCollection.InsertTextBox method. By default, the inserted shape is positioned at the beginning of the first paragraph on the page that contains the floating object’s anchor.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/winforms-richedit-document-api-e5219

Shapes.cs

document.AppendText("Line One\nLine Two\nLine Three");
Shape myPicture = document.Shapes.InsertPicture(document.CreatePosition(15), 
    System.Drawing.Image.FromFile("beverages.png"));
myPicture.HorizontalAlignment = ShapeHorizontalAlignment.Center;

Shapes.vb

document.AppendText("Line One" & vbLf & "Line Two" & vbLf & "Line Three")
Dim myPicture As Shape = document.Shapes.InsertPicture(document.CreatePosition(15), System.Drawing.Image.FromFile("beverages.png"))
myPicture.HorizontalAlignment = ShapeHorizontalAlignment.Center

All document shapes are contained in the ShapeCollection collection. It can be retrieved using the ReadOnlyShapeCollection.Get method. Access the necessary collection item by its index or name using the array notation. To specify the name of the target shape, use the Shape.Name property.

To find whether the retrieved item is the floating picture or the text box, check its Shape.TextBox and Shape.Picture properties. If the current object is the text box, its Shape.Picture property value is null, and vice versa, if the object’s Shape.TextBox property is null, the object is the floating picture.

Tip

To select a shape, assign the Shape.Range to the Document.Selection property.

Modify the Floating Object

1. Position

   To specify the flow of the text around the shape, use the Shape.TextWrapping property. To define the floating object’s position within the document, use one of the following properties.

   • Shape.ZOrder - to change the shape position in the Z-order. Use this property to place the floating object behind or in front of other shapes contained in the document.
   • Shape.Offset - to position the object relative to a certain point.
   • Shape.HorizontalAlignment and Shape.VerticalAlignment - to position the object relative to the page. To change the item to which the object position is relative, specify the Shape.RelativeHorizontalPosition and Shape.RelativeVerticalPosition properties.

   The following code snippet uses the Shape.ZOrder property to position an image behind the specified floating object and sets the Shape.TextWrapping property to set the image behind the text of the document.

   Note

   A complete sample project is available at https://github.com/DevExpress-Examples/winforms-richedit-document-api-e5219

   Shapes.cs

   document.LoadDocument("Grimm.docx", DevExpress.XtraRichEdit.DocumentFormat.OpenXml);
   Shape myPicture = document.Shapes[1];
   myPicture.VerticalAlignment = ShapeVerticalAlignment.Top;
   myPicture.ZOrder = document.Shapes[0].ZOrder - 1;
   myPicture.TextWrapping = TextWrappingType.BehindText;
   

   Shapes.vb

   document.LoadDocument("Grimm.docx", DevExpress.XtraRichEdit.DocumentFormat.OpenXml)
   Dim myPicture As Shape = document.Shapes(1)
   myPicture.VerticalAlignment = ShapeVerticalAlignment.Top
   myPicture.ZOrder = document.Shapes(0).ZOrder - 1
   myPicture.TextWrapping = TextWrappingType.BehindText
   

2. Rotate and Resize

   To rotate the shape, use the Shape.RotationAngle property. To resize the floating object, specify its Shape.Size property. To scale the target shape horizontally or vertically, set the Shape.ScaleX or Shape.ScaleY property.

   The following code rotates text boxes and resizes floating pictures.

   Note

   A complete sample project is available at https://github.com/DevExpress-Examples/winforms-richedit-document-api-e5219

   Shapes.cs

   document.LoadDocument("Grimm.docx", DevExpress.XtraRichEdit.DocumentFormat.OpenXml);
   foreach (Shape s in document.Shapes)
   {
    // Rotate a text box and resize a floating picture.
       if (s.TextBox == null)
       {
           s.ScaleX = 0.1f;
           s.ScaleY = 0.1f;
       }
       else
       {
           s.RotationAngle = 45;
       }
   }
   

   Shapes.vb

   document.LoadDocument("Grimm.docx", DevExpress.XtraRichEdit.DocumentFormat.OpenXml)
   For Each s As Shape In document.Shapes
    ' Rotate a text box and resize a floating picture.
       If s.TextBox Is Nothing Then
           s.ScaleX = 0.1F
           s.ScaleY = 0.1F
       Else
           s.RotationAngle = 45
       End If
   Next s
   

3. Change the Shape Outline

   You can specify the shape outline color and thickness. Retrieve the border line using the Shape.Line property and set its ShapeLine.Color and ShapeLine.Thickness properties. If the floating object’s background is transparent, you can change the fill color. To do that, use the ShapeFill.Color property.

   C#

   
   richEditControl1.Document.Shapes[1].Line.Color = System.Drawing.Color.Teal;
   richEditControl1.Document.Shapes[1].Line.Thickness = 2;
   richEditControl1.Document.Shapes[1].Fill.Color = System.Drawing.Color.Green; 
   

   VB.NET

   
   richEditControl1.Document.Shapes(1).Line.Color = System.Drawing.Color.Teal
   richEditControl1.Document.Shapes(1).Line.Thickness = 2
   richEditControl1.Document.Shapes(1).Fill.Color = System.Drawing.Color.Green
   

Delete the Floating Object

The ShapeCollection where all the document shapes are contained is read-only, i.e., the collection items cannot be deleted. To remove the floating object from the document, delete the range to which the target shape is anchored. Retrieve the range using the Shape.Range property and pass it to the SubDocument.Delete method.

C#

DocumentRange range = richEditControl1.Document.Shapes[1].Range;
richEditControl1.Document.Delete(range);

VB.NET

Dim range As DocumentRange = richEditControl1.Document.Shapes(1).Range
richEditControl1.Document.Delete(range)