C# PictureBox: Windows Forms

PictureBox provides a rectangular region for an image.

It supports many image formats. It has an adjustable size. It can access image files from your disk or from the Internet. It can resize images in several different ways.

Steps. First, the PictureBox provides a way to display an image. It can handle many different image formats. We use the PNG format. To add a PictureBox to your Windows Forms program, go to the Designer view and open the Toolbox.

Then: Drag the PictureBox icon to your window in the desired location. This creates a rectangular PictureBox instance.

In the next step of this tutorial, we assign an image to the PictureBox from the disk. There are several ways of doing this, but the way we use here allows you to quickly resize the PictureBox control so the entire image is shown.

Here: We use a PNG image in this code. But JPEG images and GIF images are also supported.

Event: We use the Form_Load event. To create this event handler, double-click on the enclosing window in the Designer view.

Windows Forms code that initialized PictureBox control: C#

using System;
using System.Drawing;
using System.Windows.Forms;

namespace WindowsFormsApplication24
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void Form1_Load(object sender, EventArgs e)
	{
	    // Construct an image object from a file in the local directory.
	    // ... This file must exist in the solution.
	    Image image = Image.FromFile("BeigeMonitor1.png");
	    // Set the PictureBox image property to this image.
	    // ... Then, adjust its height and width properties.
	    pictureBox1.Image = image;
	    pictureBox1.Height = image.Height;
	    pictureBox1.Width = image.Width;
	}
    }
}

The Image type is a class that encapsulates information about an image, including its data in bytes. It provides an abstract data type for handling an image in a clear way. It is found in the System.Drawing namespace.

ImageDrawing

Why assign the Height and Width? This code uses two statements to assign the Height and Width instance properties of the Image. This forces the PictureBox to resize correctly. If you omit these statements, the image may be cropped.

Also: It is easy to crop a PictureBox by setting its Width and Height to the desired values.

Discussion. At its core, the PictureBox is a mechanism for displaying an image graphically in the Windows Forms program. It cannot do elaborate transformations on this image. You must invoke any of these transformations through your own logic.

Tip: You can add hover (mouse-over) and click events to the PictureBox in the same way as other Windows Forms controls.

But: For complex programs that display images in a specific way, the PictureBox is not ideal.

PictureBoxSizeMode. Here we cover the transformations that are enabled through the SizeMode property on the PictureBox control. All of these settings affect how an image is displayed based on the dimensions of the control (width and height).

Instead of setting Width and Height, we can use the PictureBoxSizeMode.AutoSize enum. We can center the image both horizontally and vertically. We can stretch the image so that it fills the entire enclosing box.

And: We can zoom the image so that it maintains its original aspect ratio. The image does not appear distorted.

Enum values:

AutoSize
CenterImage
Normal
StretchImage
Zoom

ImageLocation. The PictureBox contains an instance property called ImageLocation, and this sets the image data from a file. If you use the AutoSize enum with the ImageLocation property, your PictureBox will be sized correctly.

Implementation of Form_Load: C#

private void Form1_Load(object sender, EventArgs e)
{
    // Set the ImageLocation property to a file on the disk.
    // ... Set the size mode so that the image is correctly sized.
    pictureBox1.ImageLocation = "BeigeMonitor1.png";
    pictureBox1.SizeMode = PictureBoxSizeMode.AutoSize;
}

Download. For the PictureBox control, you can use the ImageLocation instance property to specify the URL of an image to download and place in the PictureBox. For this example, we will use the website icon file for this site.

Also: This example shows that the PictureBox supports the ICO format for images.

Another implementation of Form_Load: C#

private void Form1_Load(object sender, EventArgs e)
{
    // Set the ImageLocation property to a URL.
    // ... This example image is tiny and is the icon for Dot Net Perls.
    pictureBox1.ImageLocation = "favicon.ico";
}

Summary. The PictureBox displays images of various types. It handles the drawing of the pixels, and provides properties for adjusting the dimensions of the control. You can zoom images, stretch images, or crop image displays.

Related Links