Picture Box

Aug 03, 2020
3 minutes to read

This document explains the basics of using the XRPictureBox control and describes its main features.

The document consists of the following sections:

Picture Box Overview
Bind a Picture Box to Data
Image Size Modes

Picture Box Overview

XRPictureBox is used to embed static (stored along with the report definition) or dynamic (obtained from a data source) images into a report.

It can display images of various file formats: BMP, JPG, JPEG, GIF, TIF, TIFF, PNG, ICO, DIB, RLE, JPE, JFIF, EMF, WMF.

To add this control to a report, drag the XRPictureBox item from the DX:17.2: Report Controls Toolbox tab and drop it onto the report.

Versions_DropControl_XRPictureBox

Then, specify the image or image source for the control via the XRPictureBox.Image or the XRPictureBox.ImageUrl property.

xrpicturebox-02

The main difference between these two properties is that static images are serialized along with the report definitions, while for dynamic images, only the information about their source is stored in the report.

When the value of the ImageUrl property is set, the value of the Image property is set to null (Nothing in Visual Basic) and vice versa.

Bind a Picture Box to Data

To use the XRPictureBox control to display an image dynamically obtained from a data source, click the control’s smart tag and in the invoked actions list, expand the Expression drop-down list for the Image property and select the required data field.

report-control-picturebox-0

In the same way, you can bind the ImageUrl property to data. In this case, a URL specifying the location of the image to display within an XRPictureBox is obtained from a data source.

Clicking the Expression option’s ellipsis button invokes the Expression Editor, in which you can construct a complex binding expression involving two or more data fields.

You can automatically create an XRPictureBox for a data field containing image data. To do this, drag the required data field and drop it onto a report band.

To quickly create an XRPictureBox that is bound to a data field of an arbitrary type, right-click the corresponding node of the Field List and drop it onto a report band. In the invoked context menu, select the PictureBox item.

DesignTimeFeatures - FieldList4.png

See the Binding Report Controls to Data topic to learn more about available data binding modes and creating data-aware controls.

Image Size Modes

To specify how an image is positioned within the control, set the XRPictureBox.Sizing property to one of the available image size modes.

Illustration	Description
	ImageSizeMode.Normal The image is displayed with its original dimensions.
	ImageSizeMode.StretchImage The image is stretched to fill both the control’s width and height.
	ImageSizeMode.AutoSize The control’s dimensions are auto-adjusted to the image size.
	ImageSizeMode.ZoomImage The image is proportionally resized, so that it fits the control.
	ImageSizeMode.Squeeze If the control’s dimensions exceed the image size, the image is centered and shown full-size. Otherwise, the image is resized to fit into the control’s dimensions.
	ImageSizeMode.Tile The original image is replicated within the picture control starting from the upper-left corner. The replicated image is clipped if it does not fit in the picture control which contains it.