PictureBox Report Item Overview
The PictureBox report item displays images in a report and supports Base64-encoded images, SVG (Scalable Vector Graphics), and GDI+-supported (BMP, GIF, JPEG, EXIF, PNG, and TIFF) image formats.
This document explains how to add an image to a report with the help of the PictureBox item and how to configure its layout.
Setting the Value
As its value, the PictureBox accepts an expression that can contain any of the following:
- Binary image data.
- A URI (local path or URL) that points to a bitmap or an SVG file.
- A string that represents either a Base64-encoded image or an SVG markup.
The following screenshot shows a PictureBox report item at design time. Note the image thumbnail in the upper left corner.
When you add values to the PictureBox, note the following:
-
When the
Value
property is a string that is not an expression (a string that doesn't start with=
), the PictureBox assumes the value is a URI, a Base64-encoded image, or an SVG markup.The Relative Path will be resolved as follows:
- For declarative report definitions (TRDP and TRDX files) - with respect to the report location.
- For type report definitions (CS and VB reports) - with respect to the application starting point.
Clicking the ellipsis for
Value
will open a Browse dialog to navigate to a file on your hard drive. The engine will try to determine the type of the selected file and populate theValue
property with descriptive text.- When a raster image file (BMP, GIF, JPEG, PNG, EXIF, or TIFF) is selected, its bytes will be serialized in the report definition. When a Base64-encoded image file is selected, the report definition will persist the string representation of the Base64-encoded image. When an SVG image file is selected, the report definition persists its markup and it will be accessible in the Edit Expression dialog.
- You can also paste a path to an image file, a Base64-encoded string, or an SVG markup in the
Value
property editor or in the Edit Expression dialog. Note that the maximum length supported by theValue
editor is 32767 characters, so if the new string value is longer than that, you need to use the Edit Expression dialog instead.
To set an expression as a PictureBox value in the Report Designer:
- Right-click the item. Choose Expression....
- Enter the expression in the Edit Expression dialog.
Binding to Data
To bind an image data to a PictureBox when using a Report Designer is a straightforward process. You need to connect to a data source and drag the image field from the Data Explorer window to your report. As a result, the report designer tool will associate each field based on its data type.
Alternatively, you can drag a PictureBox item to the design surface and use an expression to set its Value
property to an existing field from the data source. The type of the PictureBox.Value
property is Object
which allows for versatile data binding and you do not have to directly bind to a database field with an image column.
The Value
property accepts objects of type Image
, byte array, and strings. The string can be either of the following:
- An expression—The expression must evaluate to an
Image
, byte array, relative or absolute Uri, or a string representing a Base64-encoded image or an SVG markup. - A string literal— The string literal can be a relative or absolute Uri, or a string representing a Base64-encoded image or an SVG markup.
Binding to Binary Images
You can directly assign a reference to an Image
to the Value
property of a PictureBox.
using System.Drawing;
Image image1 = Image.FromFile(@"C:\MyPictures\MyPicture.jpg");
this.pictureBox1.Value = image1;
Image image2 = Image.FromStream(imageStream);
this.pictureBox2.Value = image2;
Imports System.Drawing
Dim image1 As Image = Image.FromFile("C:\MyPictures\MyPicture.jpg")
Me.PictureBox1.Value = image1
Dim image2 As Image = Image.FromStream(imageStream)
Me.PictureBox2.Value = image2
While in design-time within the Visual Studio Report Designer, if you click the ellipsis of the Value
property, a dialog appears for you to choose the desired image. After you select the image, the Designer will automatically store it in the resources file for the report (.resx
) and add a line of code to the InitializeComponent
method that obtains a reference to the image stored in the resources and assigns it to the Value
of the PictureBox:
this.pictureBox1.Value = ((object)(resources.GetObject("pictureBox1.Value")));
When the database field contains a relative path, either a file path or a URI, you can utilize the user functions to specify the correct path to the image and then set the Value
to the correct =LoadImage(Fields.YourImagePathColumn)
expression.
public static Image LoadImage(string imageLocation)
{
string absoluteLocation = "C:\\" + imageLocation;
return Image.FromFile(absoluteLocation);
}
Public Shared Function LoadImage(imageLocation As String) As Image
Dim absoluteLocation As String = "C:\" + imageLocation
Return Image.FromFile(absoluteLocation)
End Function
Binding to Expressions, URIs, Base64, and SVG
Alternatively, you can assign a string value to the Value
property. This string value can be any of the following:
- An item binding expression— When binding to a data field with an expression, the Value property will accept both
binary
andstring
data fields. - A URI— The
Value
property supports both absolute and relative URIs. -
A string representing a Base64-encoded image or a valid SVG markup— For optimization, the engine initially checks the length of the string value.
If it is less than 80 characters, the value is considered to be a URI. Otherwise, the string is tested whether it is SVG markup (if its first 256 characters contain
<svg
) or a Base64-encoded string.If the string is neither a valid SVG nor a Base64-encoded string, the engine will still accept the string as a URI and will try to instantiate an image from it.
To sum it up, the data source column of the PictureBox can store the image object, its Base64 string representation, an SVG markup, or a relative or absolute URI pointing to the image:
this.pictureBox1.Value = "=Fields.MyImageBinary";//a binary data column
this.pictureBox2.Value = "=Fields.MyImageURI";//a data column containing an URI
this.pictureBox3.Value = @"C:\MyPictures\MyPicture.png";//absolute file path to a PNG file
this.pictureBox4.Value = @"C:\MyPictures\MySVGImage.svg";//absolute file path to an SVG file
this.pictureBox5.Value = @".\images\MyPicture.png";//relative path
this.pictureBox6.Value = "https://www.mysite.com/images/img1.gif";//absolute URL
Me.PictureBox1.Value = "=Fields.MyImageBinary" 'a binary data column
Me.PictureBox2.Value = "=Fields.MyImageURI" 'a data column containing an URI
Me.PictureBox3.Value = "C:\MyPictures\MyPicture.png" 'absolute file path to a PNG image
Me.PictureBox4.Value = "C:\MyPictures\MySVGImage.svg" 'absolute file path to an SVG file
Me.PictureBox5.Value = ".\images\MyPicture.png" 'relative path
Me.PictureBox6.Value = "https://www.mysite.com/images/img1.gif" 'absolute URL
Clipping, Rendering, and Positioning
The clipping and positioning of an image in the display area of the PictureBox item is controlled by its Sizing
and ImageAlignment
properties.
The following table lists the Sizing
property modes.
Name | Description |
---|---|
AutoSize |
The PictureBox size is adjusted to that of the image it contains. |
Center |
The image is displayed in the center of the PictureBox. If the image is larger than the PictureBox, the outside edges are clipped. |
Normal |
The image is placed in the upper-left corner of the PictureBox. The image is clipped if it's larger than the PictureBox which contains it. |
Stretch |
The image within the PictureBox is stretched or shrunk as appropriate to fit the size of the PictureBox. |
ScaleProportional |
The image is sized proportionally (without clipping), so that it's best fitted to the PictureBox. If the height and width ratio of the PictureBox is the same as the ratio of the image, it will be resized to exactly fit into the PictureBox. Otherwise, the closest fitting side (height or width) of the image will be sized to the item and the other side (height or width) of the image sized proportionally (leaving empty space). |
The ImageAlignment
property dictates the alignment of the image if it does not conform to the specified PictureBox size.
The
ImageAlignment
property is not respected when the Sizing property is set to AutoSize, Center, or Stretch.
The following table lists the available ImageAlignment
property modes.
Name | Horizontal Alignment | Vertical Alignment |
---|---|---|
Auto * |
Default | Default |
Center |
Center | Center |
Left |
Left | Center |
Top |
Center | Top |
Right |
Right | Center |
Bottom |
Center | Bottom |
TopLeft |
Left | Top |
TopRight |
Right | Top |
BottomLeft |
Left | Bottom |
BottomRight |
Right | Bottom |
* The
Auto
mode retains the original alignment of the Normal and ScaleProportional sizing modes.
This is the default mode.
The PictureBox renders the image depending on the underlying image DPI settings, so the physical dimensions of the rendered item may vary. For example, if you are using a 120dpi image in your PictureBox with Sizing set to AutoSize
or Normal
and the machine settings are set to 96dpi
, the image will look smaller due to the higher amount of pixels per inch. To properly resize the image, set its Sizing to Stretch
or ScaleProportional
.
The SVG images are rendered in vector format where the rendering extension supports it.
- On the designer surface and in image formats, the SVG content is rendered as an EMF (Enhanced Metafile) which is also a vector format and preserves the lossless scaling.
- In HTML formats, the SVG markup is rendered as-is, since all modern browsers support SVG contents.
- In OpenXML-based rendering extensions (DOCX, XLSX, PPTX, RTF), the SVG is rendered in a vector format by default, but can be rendered in a raster format if the
deviceInfo
settingUseMetafile
is set tofalse
. - In the rest of the rendering extensions, the SVG is rendered as a raster image, but the size of the item is always taken into account for quality.
Next Steps
- (Demo) Product Catalog Report with a PictureBox
- Using Styles to Customize Reports
- Using Expressions
- (API) PictureBox
- (API) Sizing
- Demo Page for Telerik Reporting
- Knowledge Base Section