Telerik Reporting: Using the PictureBox Item

Telerik Reporting comes with all essential report items in the Visual Studio toolbox to help you more easily design rich reports. One such report item, the PictureBox, is used to display images on a report. The PictureBox is simple and easy-to-use like the other report items, but in this post I’d like to highlight a couple of its features so that you can take full advantage of its capabilities. Specifically, I will discuss the data binding and layout features that are unique to the PictureBox item.

Data Binding

Binding image data to a PictureBox report item is very straight-forward. If you’re using the designer in Visual Studio and have connected to a data source, you can simply drag the image field from the Data Explorer window onto your report. Below is an example of a Northwind report which displays employee images. As you can see, I only needed to drag the image from Photo field onto the design surface to bind the image to my report. The designer is smart enough to know what kind of report item to associate with each field based on its data type. In this case, dragging the Photo field onto the design surface adds a PictureBox to my report.

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

While the methods demonstrated above are certainly the easiest and quickest ways to get an image onto your report, you don’t have to bind directly to a database field with an image column. Since the PictureBox’s Value property is of type Object, it can be bound to both pictures and strings. Using a string, you can bind the PictureBox to an image located in a folder using a relative or absolute file path.

You can also bind to an online image using a relative or absolute URL. For example, if I want to use new employee images for employees in the Northwind database but don’t want to have to import them into the database, I can upload them somewhere online and use expressions to point the PictureBox Value property to the proper URL.

Finally, if you have a need to create reports programmatically, you can easily bind the PictureBox item to a file path or a URL path using a single line of code.

employeeImage.Value = "http://myviewstate.net/images/employee.jpg";

Layout

In addition to offering multiple ways with which to bind an image to a report, the PictureBox report item also allows you to modify the way the image is displayed on the report. Using the PictureBox’s Location property you can adjust the distance the image is displayed from the top-left corner of its container. A report item’s container is any item within which the item is displayed, whether it be a report section, a Panel report item, etc. You can also use the Size property to manually adjust the size of the PictureBox item.

It is important to remember that the Size property refers to the size of the report item, not the actual image that will be displayed. In order to change the size of the image, you must use the Sizing property. Since images come in all different sizes, and it is not always possible to know an image’s dimensions beforehand, there are several Sizing options from which to choose.

The first, AutoSize, adjusts the PictureBox so that its size is the same as the image it contains. Next, the Center option displays the image in the center of the PictureBox item, clipping any part of the image that falls outside the item’s border. The Normal option is selected by default and it places the image in the upper-left corner of the PictureBox, clipping any part of the image that falls outside its border. Next is the Stretch option, which stretches or shrinks the image so that it fits the size of the PictureBox. And finally, the ScaleProportional option sizes the image within the PictureBox item, maintaining its original proportions, so that it fits as best as possible within the item.

Conclusion

Telerik Reporting offers several report items with which you can design your report, all of which are important weapons in the arsenal of any .NET reporting ninja. The PictureBox item is no exception, and offers many flexible ways by which you can bind the image data to the item, or modify its layout within the report.