PictureBox

The PictureBox control displays images. It also provides a Graphics object that you can use to draw lines, rectangles, ellipses, and other shapes at runtime.

The control’s Image property determines the picture that the control displays. Its SizeMode property determines how the image is sized to fit into the control. The following table describes the allowed SizeMode values.

Open table as spreadsheet

Value	Meaning
Normal	The image is not resized. If it sticks off the edge of the PictureBox, the image is clipped.
StretchImage	The image is stretched to fill the control. This may change the image’s shape, making it shorter and wider or taller and thinner than it should be.
AutoSize	The PictureBox adjusts its size to fit the image. If the control is displaying borders, it allows extra room for them.
CenterImage	The image is centered in the PictureBox at its normal size. If it sticks off the edge of the PictureBox, the image is clipped.

If you set the control’s BackgroundImage property to a picture, the control tiles itself completely with copies of the picture. If you also set the Image property, then the background shows behind the image. If you have SizeMode set to StretchImage or AutoSize, then the image fills the entire control, so you will not see the background image.

The PictureBox control has several properties that deal with its size internally and externally. Its Size, Width, and Height properties give information about the size of the control, including its border if it has one. The ClientRectangle, ClientSize, and DisplayRectangle properties give information about the area inside the control, not including its border. You should use these properties when you draw on the control.

The PictureBox control’s CreateGraphics method returns a Graphics object that represents the control’s client area. Your code can use that object’s methods to draw on the control.

The following code draws an ellipse on the picCanvas control when the user presses the btnDrawCircle button. It uses the PictureBox control’s CreateGraphics method to make the Graphics object and uses that object’s DrawEllipse method to draw the ellipse. The code uses the PictureBox’s DisplayRectangle property to get the dimensions of the PictureBox control’s interior. The code subtracts 1 from the rectangle’s width and height so the ellipse will lie completely inside the control’s display area.

  Private Sub btnDrawCircle_Click(ByVal sender As System.Object, _  ByVal e As System.EventArgs) Handles btnDrawCircle.Click     Dim gr As Graphics = picCanvas.CreateGraphics()     gr.DrawEllipse(Pens.Blue, _         picCanvas.DisplayRectangle.X, _         picCanvas.DisplayRectangle.Y, _         picCanvas.DisplayRectangle.Width - 1, _         picCanvas.DisplayRectangle.Height - 1) End Sub 

This routine draws an ellipse on a PictureBox, but it does not ensure that the drawing remains. If you hide the PictureBox with another form and then bring it back to the top, the ellipse is gone. There are two main approaches to keeping a drawing visible on a PictureBox.

First, you can place the drawing commands in the PictureBox control’s Paint event handler. The Paint event occurs any time part of the control needs to be refreshed. That happens if the control is covered and then uncovered, when its form is minimized and then restored, and when the control is enlarged so that a new part of its display area is exposed.

The following code draws an ellipse on the picCanvas PictureBox whenever it generates a Paint event. Notice that the event handler’s e.Graphics parameter gives the Graphics object on which the routine should draw.

  Private Sub picCanvas_Paint(ByVal sender As Object, _  ByVal e As System.Windows.Forms.PaintEventArgs) Handles picCanvas.Paint     e.Graphics.DrawEllipse(Pens.Red, _         picCanvas.DisplayRectangle.X, _         picCanvas.DisplayRectangle.Y, _         picCanvas.DisplayRectangle.Width - 1, _         picCanvas.DisplayRectangle.Height - 1) End Sub 

The second approach to keeping a drawing visible is to make a Bitmap that fits the PictureBox, draw on the Bitmap, and then set the control’s Image property equal to the Bitmap. After that, the control automatically displays its image.

The following code shows how a program can make the picCanvas PictureBox permanently display an ellipse. It starts by creating a new Bitmap object with the same size as the PictureBox control’s display area. Next, it makes a Graphics object associated with the Bitmap. It uses that object’s Draw?Ellipse method to draw the ellipse on the Bitmap. Finally, it sets the PictureBox control’s Image property to the Bitmap.

  Private Sub Form1_Load(ByVal sender As System.Object, _  ByVal e As System.EventArgs) Handles MyBase.Load     ' Make a Bitmap to fit the PictureBox.     Dim bm As New Bitmap( _         picCanvas.DisplayRectangle.Width, _         picCanvas.DisplayRectangle.Height)     ' Get a Graphics object to draw on the Bitmap.     Dim gr As Graphics = Graphics.FromImage(bm)     ' Draw the ellipse.     gr.DrawEllipse(Pens.Yellow, _         picCanvas.DisplayRectangle.X, _         picCanvas.DisplayRectangle.Y, _         picCanvas.DisplayRectangle.Width - 1, _         picCanvas.DisplayRectangle.Height - 1)     ' Assign the Bitmap to the control's Image      picCanvas.Image = bm End Sub 

This method takes more memory than the previous method of drawing in the control’s Paint event handler. If the drawing is very complicated and takes a long time, however, it may be faster to generate the Bitmap once rather than redrawing the picture every time the control raises its Paint event.

The final PictureBox feature that is relevant to drawing is its Invalidate method. This method invalidates some or all of the control’s display area and generates a Paint event. You can use this method to redraw the control if you have changed some data that will affect the drawing’s appearance.