Version

Adding Images (xamRichTextEditor)

Topic Overview

Purpose

This topic provides information on how to create images using the xamRichTextEditor ™ from the developer’s perspective.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This topic provides an overview of the features supported by the xamRichTextEditor control.

This topic explains the document’s content logical structure you can use to edit the contents in the xamRichTextEditor programmatically.

This topic provides detailed instructions to help you get up and running as quickly as possible with the xamRichTextEditor .

Introduction

Images summary

The xamRichTextEditor control supports images of different formats in its document’s content. The images are represented by an ImageNode, which can only be added to the ChildNodes collection of a RunNode. The following tree shows the structure of a paragraph with an image:

  1. ParagraphNode

    1. RunNode

      1. ImageNode

The following image formats are supported: BMP, DIB, EMF, GIF, JPEG, PNG, TIFF and WMF.

Note
Note

GIF and TIFF images will be lost when saving the rich document’s content to RTF format in Silverlight. WMF and EMF formats are supported for round-tripping purposes only. They will be rendered by the xamRichTextEditor as default image icons.

ImageNode Class Key Features

Overview

This class represents an image in the document’s node hierarchy. It provides methods for specifying crop and margin.

Key features

The following table maps the desired configuration to its respective property settings.

In order to: Use: And set it to:

Load an image

The Image property

An instance of type RichTextImage

Load an image

The ImageUri property

A string specifying the location of the image file to load.

Note
Note

If the Image property is also specified then this property will be ignored.

Crop the image

The Cropping property

An instance of type RectOffsets specified as percentage offsets from each edge. For example, setting the Left and Right properties to 10 each would crop out 20% of the image rendering only the middle 80%. Negative values are allowed and will result in padding around the image.

Set margins on the image

The RenderEffectsMargin property

An instance of type RichTextMargin

Note
Note

In most scenarios it is best not to set this property, especially if stretch and/or rotate transforms are being set thru the Transform property or if cropping is specified. If RenderEffectsMargin is left to null the appropriate margins will be calculated by the layout engine automatically. However, in this case, this property will remain null.

Set advanced image transformation

The Transform property

An instance of type RichTextImageTransform that exposes properties to stretch, rotate and/or flip the image horizontally and/or vertically

Set or obtain the image size

The RenderSize property

Set or obtain its value of type RichTextSize.

Note
Note

If stretch and/or rotate transforms are being set thru the Transform property or if cropping is specified it is best to leave this property set to null. If left to null the appropriate render size will be calculated by the layout engine and this property will be updated automatically.

RichTextImage Class Key Features

Overview

This class represents the image data. Its constructor can create an instance from a byte array. This class also provides static methods for creating instances from a stream or file location.

Key features

The following table maps the desired configuration to its respective property settings.

In order to: Use: And:

Create a RichTextImage from byte array

The constructor of the class

Provide the byte array

Create a RichTextImage from data stream

The CreateFrom method

Provide a stream

Create a RichTextImage from a file location

The CreateFrom method

Provide the file location as string

RichTextImageTransform Class Key Features

Overview

This class represents the transformations which will be applied to the image at document render time.

Key features

The following table maps the desired configuration to its respective property settings.

In order to: Use this property: And set it to:

Flip the image horizontally

true

Flip the image vertically

true

Rotate the image

A value of type float representing the rotation’s angle. A negative value rotates the image to the left and a positive value rotates it to the right.

Stretch the image horizontally and/or vertically

A value of type RichTextSize, which contains the stretch width and height.

Note
Note

After you set a stretch size for an image the sizes specified in the RenderSize property are ignored.

Related Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic provides information on how to create text using the xamRichTextEditor from a developer’s perspective.

This topic provides information on how to create hyperlinks using the xamRichTextEditor from the developer’s perspective.

This topic provides information on how to create lists using the xamRichTextEditor from the developer’s perspective.

This topic provides information on how to use the xamRichTextEditor to create tables from the developer’s perspective.