PictureBox

The PictureBox control displays an Image object. The Image object to be displayed can be a member of, or descended from, one of the following classes:

Bitmap

Contains pixel data for an image and its attributes. Typical file types are jpg, gif, or bmp.

Icon

A small, transparent bitmap used to represent an object. The typical file extension is ico.

Metafile

Contains records that describe a sequence of graphics operations. The typical file extension is wmf.

The PictureBox is a relatively simple control, with only three commonly used properties other than those inherited from Control or other base classes. The properties are listed in Table 13-8. The important property is SizeMode, which controls how the image is fit to the PictureBox.

Table 13-8. PictureBox properties

Property	Value type	Description
BorderStyle	BorderStyle	Read/write. Valid values are members of the BorderStyle enumeration, listed in Table 13-9. The default value is BorderStyle.None.
Image	Image	Read/write. The image to display in the control.
SizeMode	PictureBoxSizeMode	Read/write. How the image is displayed. Valid values are members of the PictureBoxSizeMode enumeration, listed in Table 13-10. The default value is PictureBoxSizeMode.Normal.

Table 13-9. BorderStyle enumeration values

Value	Description
Fixed3D	3-D border.
FixedSingle	Single line border.
None	No border.

Table 13-10. PictureBoxSizeMode enumeration values

Value	Description
AutoSize	The PictureBox is automatically sized to fit the image it contains.
CenterImage	The image is centered in the control. If the image is larger than the control, the image is clipped on all four sides.
Normal	The image is placed in the upper-left corner of the control. If the image is larger than the control, the image is clipped.
StretchImage	The image is resized to fit the control.

The programs listed in Example 13-5 (in C#) and in Example 13-6 (in VB.NET) demonstrate the PictureBox control with all four possible values of the SizeMode property. For each possible SizeMode value, two picture boxes are presented: one intentionally larger than the image and one smaller. The image used here is a gif file that is 151 pixels wide by 140 pixels high.

Example 13-5. PictureBoxes in C# (PictureBoxes.cs)

using System;
using System.Drawing;
using System.Windows.Forms;
 
namespace ProgrammingWinApps
{
 public class PictureBoxes : Form
 {
 public PictureBoxes( )
 {
 Text = "PictureBoxes";
 Size = new Size(550,500);
 AutoScroll = true;
 
 // Get an image to use
 Image img = Image.FromFile(
 "Dan at Vernal Pool.gif");
 
 Label lblNormal = new Label( );
 lblNormal.Parent = this;
 lblNormal.Location = new Point(0,20);
 lblNormal.Size = new Size(75,25);
 lblNormal.TextAlign = ContentAlignment.MiddleRight;
 lblNormal.Text = "Normal:";
 
 PictureBox pbNormalBig = new PictureBox( );
 pbNormalBig.Parent = this;
 pbNormalBig.Size = new Size(200, 200);
 pbNormalBig.Location = new Point(75,20);
 pbNormalBig.BorderStyle = BorderStyle.FixedSingle;
 pbNormalBig.SizeMode = PictureBoxSizeMode.Normal;
 pbNormalBig.Image = img;
 
 PictureBox pbNormalSmall = new PictureBox( );
 pbNormalSmall.Parent = this;
 pbNormalSmall.Size = new Size(100, 100);
 pbNormalSmall.Location = new Point(325,20);
 pbNormalSmall.BorderStyle = BorderStyle.FixedSingle;
 pbNormalSmall.SizeMode = PictureBoxSizeMode.Normal;
 pbNormalSmall.Image = img;
 
 Label lblAuto = new Label( );
 lblAuto.Parent = this;
 lblAuto.Location = new Point(0, 250);
 lblAuto.Size = new Size(75,25);
 lblAuto.TextAlign = ContentAlignment.MiddleRight;
 lblAuto.Text = "AutoSize:";
 
 PictureBox pbAutoBig = new PictureBox( );
 pbAutoBig.Parent = this;
 pbAutoBig.Size = new Size(200, 200);
 pbAutoBig.Location = new Point(75, 250);
 pbAutoBig.BorderStyle = BorderStyle.FixedSingle;
 pbAutoBig.SizeMode = PictureBoxSizeMode.AutoSize;
 pbAutoBig.Image = img;
 
 PictureBox pbAutoSmall = new PictureBox( );
 pbAutoSmall.Parent = this;
 pbAutoSmall.Size = new Size(100, 100);
 pbAutoSmall.Location = new Point(325,250);
 pbAutoSmall.BorderStyle = BorderStyle.FixedSingle;
 pbAutoSmall.SizeMode = PictureBoxSizeMode.AutoSize;
 pbAutoSmall.Image = img;
 
 Label lblCenter = new Label( );
 lblCenter.Parent = this;
 lblCenter.Location = new Point(0,480);
 lblCenter.Size = new Size(75,25);
 lblCenter.TextAlign = ContentAlignment.MiddleRight;
 lblCenter.Text = "CenterImage:";
 
 PictureBox pbCenterBig = new PictureBox( );
 pbCenterBig.Parent = this;
 pbCenterBig.Size = new Size(200, 200);
 pbCenterBig.Location = new Point(75,480);
 pbCenterBig.BorderStyle = BorderStyle.FixedSingle;
 pbCenterBig.SizeMode = PictureBoxSizeMode.CenterImage;
 pbCenterBig.Image = img;
 
 PictureBox pbCenterSmall = new PictureBox( );
 pbCenterSmall.Parent = this;
 pbCenterSmall.Size = new Size(100, 100);
 pbCenterSmall.Location = new Point(325,480);
 pbCenterSmall.BorderStyle = BorderStyle.FixedSingle;
 pbCenterSmall.SizeMode = PictureBoxSizeMode.CenterImage;
 pbCenterSmall.Image = img;
 
 Label lblStretch = new Label( );
 lblStretch.Parent = this;
 lblStretch.Location = new Point(0,710);
 lblStretch.Size = new Size(75,25);
 lblStretch.TextAlign = ContentAlignment.MiddleRight;
 lblStretch.Text = "StretchImage:";
 
 PictureBox pbStretchBig = new PictureBox( );
 pbStretchBig.Parent = this;
 pbStretchBig.Size = new Size(200, 200);
 pbStretchBig.Location = new Point(75,710);
 pbStretchBig.BorderStyle = BorderStyle.FixedSingle;
 pbStretchBig.SizeMode = PictureBoxSizeMode.StretchImage;
 pbStretchBig.Image = img;
 
 PictureBox pbStretchSmall = new PictureBox( );
 pbStretchSmall.Parent = this;
 pbStretchSmall.Size = new Size(100, 100);
 pbStretchSmall.Location = new Point(325,710);
 pbStretchSmall.BorderStyle = BorderStyle.FixedSingle;
 pbStretchSmall.SizeMode = PictureBoxSizeMode.StretchImage;
 pbStretchSmall.Image = img;
 } // close for constructor
 
 static void Main( ) 
 {
 Application.Run(new PictureBoxes( ));
 }
 
 } // close for form class
} // close form namespace

Example 13-6. PictureBoxes in VB.NET (PictureBoxes.vb)

Option Strict On
imports System
imports System.Drawing
imports System.Windows.Forms
 
namespace ProgrammingWinApps
 public class PictureBoxes : inherits Form
 public sub New( )
 Text = "PictureBoxes"
 Size = new Size(550,500)
 AutoScroll = true
 
 ' Get an image to use
 dim img as Image = Image.FromFile( _
 "Dan at Vernal Pool.gif")
 
 dim lblNormal as new Label( )
 lblNormal.Parent = me
 lblNormal.Location = new Point(0,20)
 lblNormal.Size = new Size(75,25)
 lblNormal.TextAlign = ContentAlignment.MiddleRight
 lblNormal.Text = "Normal:"
 
 dim pbNormalBig as new PictureBox( )
 pbNormalBig.Parent = me
 pbNormalBig.Size = new Size(200, 200)
 pbNormalBig.Location = new Point(75,20)
 pbNormalBig.BorderStyle = BorderStyle.FixedSingle
 pbNormalBig.SizeMode = PictureBoxSizeMode.Normal
 pbNormalBig.Image = img
 
 dim pbNormalSmall as new PictureBox( )
 pbNormalSmall.Parent = me
 pbNormalSmall.Size = new Size(100, 100)
 pbNormalSmall.Location = new Point(325,20)
 pbNormalSmall.BorderStyle = BorderStyle.FixedSingle
 pbNormalSmall.SizeMode = PictureBoxSizeMode.Normal
 pbNormalSmall.Image = img
 
 dim lblAuto as new Label( )
 lblAuto.Parent = me
 lblAuto.Location = new Point(0, 250)
 lblAuto.Size = new Size(75,25)
 lblAuto.TextAlign = ContentAlignment.MiddleRight
 lblAuto.Text = "AutoSize:"
 
 dim pbAutoBig as new PictureBox( )
 pbAutoBig.Parent = me
 pbAutoBig.Size = new Size(200, 200)
 pbAutoBig.Location = new Point(75, 250)
 pbAutoBig.BorderStyle = BorderStyle.FixedSingle
 pbAutoBig.SizeMode = PictureBoxSizeMode.AutoSize
 pbAutoBig.Image = img
 
 dim pbAutoSmall as new PictureBox( )
 pbAutoSmall.Parent = me
 pbAutoSmall.Size = new Size(100, 100)
 pbAutoSmall.Location = new Point(325,250)
 pbAutoSmall.BorderStyle = BorderStyle.FixedSingle
 pbAutoSmall.SizeMode = PictureBoxSizeMode.AutoSize
 pbAutoSmall.Image = img
 
 dim lblCenter as new Label( )
 lblCenter.Parent = me
 lblCenter.Location = new Point(0,480)
 lblCenter.Size = new Size(75,25)
 lblCenter.TextAlign = ContentAlignment.MiddleRight
 lblCenter.Text = "CenterImage:"
 
 dim pbCenterBig as new PictureBox( )
 pbCenterBig.Parent = me
 pbCenterBig.Size = new Size(200, 200)
 pbCenterBig.Location = new Point(75,480)
 pbCenterBig.BorderStyle = BorderStyle.FixedSingle
 pbCenterBig.SizeMode = PictureBoxSizeMode.CenterImage
 pbCenterBig.Image = img
 
 dim pbCenterSmall as new PictureBox( )
 pbCenterSmall.Parent = me
 pbCenterSmall.Size = new Size(100, 100)
 pbCenterSmall.Location = new Point(325,480)
 pbCenterSmall.BorderStyle = BorderStyle.FixedSingle
 pbCenterSmall.SizeMode = PictureBoxSizeMode.CenterImage
 pbCenterSmall.Image = img
 
 dim lblStretch as new Label( )
 lblStretch.Parent = me
 lblStretch.Location = new Point(0,710)
 lblStretch.Size = new Size(75,25)
 lblStretch.TextAlign = ContentAlignment.MiddleRight
 lblStretch.Text = "StretchImage:"
 
 dim pbStretchBig as new PictureBox( )
 pbStretchBig.Parent = me
 pbStretchBig.Size = new Size(200, 200)
 pbStretchBig.Location = new Point(75,710)
 pbStretchBig.BorderStyle = BorderStyle.FixedSingle
 pbStretchBig.SizeMode = PictureBoxSizeMode.StretchImage
 pbStretchBig.Image = img
 
 dim pbStretchSmall as new PictureBox( )
 pbStretchSmall.Parent = me
 pbStretchSmall.Size = new Size(100, 100)
 pbStretchSmall.Location = new Point(325,710)
 pbStretchSmall.BorderStyle = BorderStyle.FixedSingle
 pbStretchSmall.SizeMode = PictureBoxSizeMode.StretchImage
 pbStretchSmall.Image = img
 end sub ' close for constructor
 
 public shared sub Main( ) 
 Application.Run(new PictureBoxes( ))
 end sub
 
 end class
end namespace

The programs listed in Example 13-5 and Example 13-6 start off by setting the AutoScroll property of the form to true so that a vertical scrollbar will automatically appear, since the eight picture boxes don't fit on the form as originally sized.

An image object is instantiated with the static Image.FromFile method:

Image img = Image.FromFile("Dan at Vernal Pool.gif");

dim img as Image = Image.FromFile("Dan at Vernal Pool.gif")

This example assumes that the file is located in the current directory. If it were not, then you would have to specify the full path.

The four sets of controls on the form each consist of a label and two picture boxes. Both picture boxes in each set use the same value of SizeMode; the label identifies which value of SizeMode is used. The first picture box is intentionally larger than the image (200,200 versus 151,140), and the second is intentionally too small (100,100). All picture boxes have their BorderStyle set to BorderStyle.FixedSingle, to make it easy to see how big the picture box is.

The first set has a SizeMode of PictureBoxSizeMode.Normal, the default value. In the large picture box, the image is in the upper-left corner, and in the small picture box, the image is clipped on the right and bottom edges, as shown in Figure 13-7.

Figure 13-8. PictureBoxSizeMode Normal

The next set has a SizeMode of PictureBoxSizeMode.AutoSize. This forces the picture box to be the same size as the image, as shown in Figure 13-8.

Figure 13-9. PictureBoxSizeMode AutoSize

The next set has a SizeMode of PictureBoxSizeMode.CenterImage. This setting centers the image in the picture box, as shown in Figure 13-9. If the picture box is too small for the image, the image is clipped on all four sides.

Figure 13-10. PictureBoxSizeMode CenterImage

The final set has a SizeMode of PictureBoxSizeMode.StretchImage. This either stretches or shrinks the image as necessary to fit the picture box, as shown in Figure 13-10.

Figure 13-11. PictureBoxSizeMode StretchImage

This control is best for images that are relatively static. If the image changes frequently, resetting the Image property is inefficient. For these cases, a custom control is better.