Progress® Telerik® Reporting R2 2020


The PictureBox report item is used to display images on a report and it supports only image formats supported by GDI+ (BMP, GIF, JPEG, EXIF, PNG and TIFF).

Its value can be an expression that contains binary image data or it can be a URI (local path or Url). When a Value property is assigned a string that is not an expression (doesn't start with "=") the value is assumed to be an URI. Click the ellipsis for this property to browse for an image file on your hard drive.

This screenshot shows a PictureBox report item on a report at design-time (note the image thumbnail in the upper left corner).

Data Binding

Binding image data to a PictureBox report item is straight-forward. When you use a Report Designer designer and have connected to a data source, you can simply drag the image field from the Data Explorer window onto your report. The designer is smart enough to know what kind of report item to associate with each field based on its data type.

Alternatively, one can drag a PictureBox item onto the design surface and use an expression to set its Value property to an existing field from the data source.

While the methods above are quickest to get an image onto your report, one doesn’t have to bind directly to a database field with an image column. The type of the PictureBox.Value property is Object which allows for versatile data binding. The Value property accepts objects of type Image and strings. The string can be expression or string literal. The expression should evaluate to Image, Image byte[], relative or absolute Uri. The string literal can be relative or absolute Uri

  • Binding to a Binary Image

    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;

    While in design-time, if you click the ellipsis of the Value property of a selected PictureBox, you will be presented with a dialog to choose the desired image. After you have selected 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 property of the PictureBox:

    this.pictureBox1.Value = ((object)(resources.GetObject("pictureBox1.Value")));

    When the database field contains relative path (be it file path or uri) you can use User Functions to specify the correct path to the image:

    public static Image LoadImage(string imageLocation)
         string absoluteLocation = "C:\\" + imageLocation;
         return Image.FromFile(absoluteLocation);

    and set the Value of the PictureBox item to the correct expression: =LoadImage(Fields.YourImagePathColumn).

  • Binding to Expression/URI

    Alternatively you can assign a string value to the Value property of a PictureBox. This string value can be either an item binding expression or an URI. Both absolute and relative URIs are supported. When binding to a data field with an expression, the Value property will accept both binary and string data fields. In other words, your data source column may store the image directly or store an 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
    this.pictureBox4.Value = @".\images\MyPicture.png";//relative path
    this.pictureBox5.Value = "";//absolute URL

Clipping and positioning

The clipping and positioning of an image in the display area of a PictureBox item is controlled by its Sizing property.

Sizing Property modes:

AutoSize The PictureBox item size is adjusted to that of the image it contains.
Center The image is displayed in the center of the PictureBox item. If the image is larger than the PictureBox item, the outside edges are clipped.
Normal The image is placed in the upper-left corner of the PictureBox item. The image is clipped if it's larger than the PictureBox item which contains it.
Stretch The image within the PictureBox item is stretched or shrunk as appropriate to fit the size of the PictureBox item.
ScaleProportional The image is sized proportionally (without clipping), so that it's best fitted to the PictureBox item. If the height and width ratio of the PictureBox item is the same as the image's ratio it will be resized to exactly fit into the PictureBox item. 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 picturebox image is rendered depending on the underlying image DPI settings, so the physical dimensions of the rendered item may vary. For example, if you are using an 120dpi image in your PictureBox with Sizing set to AutoSize or Normal and the machine settings are set to 96dpi, the image would look smaller due to the higher amount of pixels per inch. If you want your image to be resized appropriately, its Sizing should be set to Stretch or ScaleProportional.

See Also

In this article
Not finding the help you need?