PictureClip Control

The PictureClip control allows you to select an area of a source bitmap and then display the image of that area in a form or picture box. PictureClip controls are invisible at run time. This is a typical bitmap that might be used in the PictureClip control:

File Name

PICCLP32.OCX

Class Name

PictureClip

Remarks

The PictureClip control provides an efficient mechanism for storing multiple picture resources. Instead of using multiple bitmaps or icons, create a source bitmap that contains all the icon images required by your application. When you need to display an individual icon, use the PictureClip control to select the region in the source bitmap that contains that icon.

For example, you could use this control to store all the images needed to display a toolbox for your application. It is more efficient to store all of the toolbox images in a single PictureClip control than it is to store each image in a separate picture box. To do this, first create a source bitmap that contains all of the toolbar icons. The picture at the top of this topic is an example of such a bitmap.

Note For international localized applications, resource files are sometimes a more useful way to store bitmaps. For more information, refer to Chapter 16, "International Issues," in the Visual Basic Programmer's Guide.

You can specify the clipping region in the source bitmap in one of two ways:

  • Select any portion of the source bitmap as the clipping region. Specify the upper-left corner of the clipping region using the ClipX and ClipY properties. Specify the area of the clipping region using the ClipHeight and ClipWidth properties. This method is useful when you want to view a random portion of a bitmap.

  • Divide the source bitmap into a specified number of rows and columns. The result is a uniform matrix of picture cells numbered 0, 1, 2, and so on. You can display individual cells using the GraphicCell property. This method is useful when the source bitmap contains a palette of icons that you want to display individually, such as in a toolbar bitmap.

Load the source bitmap into the PictureClip control using the Picture property. You can load only bitmap (.bmp) files into the PictureClip control.

Distribution Note When you create and distribute applications that use the PictureClip control, you should install PicClp32.ocx in the customer's Microsoft Windows System or System32 subdirectory. The Setup Kit included with Visual Basic provides tools to help you write setup programs that install your applications correctly.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Error Messages (PictureClip Control)

The following table lists the trappable errors for the PictureClip control.

Error Number | Constant | Description - Message Explanation
7 | picOutOfMemory | Out of memory.
383 | picSetNotPermitted picSetNotSupported | Property can't be set on this control. Property is read-only.
394 | picGetNotSupported | Property is write-only.
32000 | picInvalidPictureFormat | Picture format not supported.
 |  | You can load only bitmap (.bmp) files into the PictureClip control.
32001 | picDisplayContext | Unable to obtain display context.
32002 | picMemDevContext | Unable to obtain memory device context.
32003 | picBitmap | Unable to obtain bitmap.
32004 | picSelBitmapObj | Unable to select bitmap object.
32005 | picIntPicStruct | Unable to allocate internal picture structure.
32006 | picBadIndex | Bad GraphicCell Index.
 |  | The index argument for the GraphicCell property is out of range. This argument must be in the range 0 to (PicClip.Rows * PicClip.Cols)1.
32007 | picNoPicSize | No GraphicCell picture size specified.
32008 | picBitmapsOnly | Only bitmap GraphicCell pictures allowed.
32010 | picBadClip | Bad GraphicCell PictureClip property request.
32012 | picGetObjFailed | GetObject() Windows function failure.
 |  | A call to the Windows function GetObject () failed.
32014 | pic | GlobalAlloc() Windows function failure.
 |  | A call to the Windows function GlobalAlloc () failed.
32015 | picClipBounds | Clip region boundary error.
 |  | The ClipHeight and ClipWidth properties specify coordinates which are outside the boundary of the bitmap loaded in the PictureClip control.
32016 | picCellTooSmall | Cell size too small (must be at least 1 by 1 pixel).
32017 | picRowNotPositive | Rows property must be greater than zero.
32018 | picColNotPositive | Cols property must be greater than zero.
32019 | picStretchXNegative | StretchX property cannot be negative.
32020 | picStretchYNegative | StretchY property cannot be negative.
32021 | picNoPicture | No picture assigned.


CellHeight, CellWidth Properties (PictureClip Control)

Returns the height and width, in pixels, of a PictureClip control's GraphicCell property.

Syntax

object.CellHeight

object.CellWidth

The object placeholder represents an object expression that evaluates to a PictureClip control.

Remarks

The CellHeight and CellWidth properties are dependent upon the Cols and Rows properties of a PictureClip control. For example, dividing a picture into four columns and four rows would result in a GraphicCell that is twice the size of the same picture divided into eight columns and eight rows.


Clip Property (PictureClip Control)

Returns a bitmap of the area in the PictureClip control specified by the ClipX, ClipY, ClipWidth, and ClipHeight properties. This property is read-only at run time.

Syntax

[form.]PictureClip.Clip

Remarks

Use this property to specify a random clipping region from the selected bitmap.

When assigning a Clip image to a picture control in Visual Basic, make sure that the ScaleMode property for the picture control is set to 3 (pixels). You must use pixels because the ClipHeight and ClipWidth properties that define the clipping region are measured in pixels.

Data Type

Integer


ClipHeight Property (PictureClip Control)

Specifies the height of the bitmap section to be copied by the Clip property. This property is not available at design time.

Syntax

[form.]PictureClip.ClipHeight[ = Height%]

Remarks

This property is measured in pixels.

Data Type

Integer


Clip Example (PictureClip Control)

Visual Basic Example

The following example displays a Clip image in a picture box when the user specifies X and Y coordinates and then clicks a form. First create a form with a PictureBox, a PictureClip control, and two TextBox controls. At design time, use the Properties sheet to load a valid bitmap into the PictureClip control.

Private Sub Form_Click ()
   Dim SaveMode As Integer
   ' Save the current ScaleMode for the picture box.
   SaveMode = Picture1.ScaleMode
   ' Get X and Y coordinates of the clipping region.
   PicClip1.ClipX = Val(Text1.Text)
   PicClip1.ClipY = Val(Text2.Text)
   ' Set the area of the clipping region (in pixels).
   PicClip1.ClipHeight = 100
   PicClip1.ClipWidth = 100
   ' Set the picture box ScaleMode to pixels.
   Picture1.ScaleMode = 3
   ' Set the destination area to fill the picture box.
   PicClip1.StretchX = Picture1.ScaleWidth
   PicClip1.StretchY = Picture1.ScaleHeight
   ' Assign the clipped bitmap to the picture box.
   Picture1.Picture = PicClip1.Clip
   ' Reset the ScaleMode of the picture box.
   Picture1.ScaleMode = SaveMode
End Sub


ClipWidth Property (PictureClip Control)

Specifies the width of the bitmap section to be copied by the Clip property. This property is not available at design time.

Syntax

[form.]PictureClip.ClipWidth[ = Width%]

Remarks

This property is measured in pixels.

Data Type

Integer


ClipX Property (PictureClip Control)

Specifies the x-coordinate of the upper-left corner of the bitmap section to be copied by the Clip property. This property is not available at design time.

Syntax

[form.]PictureClip.ClipX[ = X%]

Remarks

This property is measured in pixels.

Data Type

Integer


ClipY Property (PictureClip Control)

Specifies the y-coordinate of the upper-left corner of the bitmap section to be copied by the Clip property. This property is not available at design time.

Syntax

[form.]PictureClip.ClipY[ = Y%]

Remarks

This property is measured in pixels.

Data Type

Integer


Cols, Rows Properties (PictureClip Control)

Set or return the total number of columns or rows in the picture.

Syntax

[form.]PictureClip.Cols[ = cols%]

[form.]PictureClip.Rows[ = rows%]

Remarks

Use these properties to divide the source bitmap into a uniform matrix of picture cells. Use the GraphicCell property to specify individual cells.

A PictureClip control must have at least one column and one row.

The height of each graphic cell is determined by dividing the height of the source bitmap by the number of specified rows. Leftover pixels at the bottom of the source bitmap (caused by integer rounding) are clipped.

The width of each graphic cell is determined by dividing the width of the source bitmap by the number of specified columns. Leftover pixels at the right of the source bitmap (caused by integer rounding) are clipped.

Data Type

Integer


GraphicCell Property (PictureClip Control)

A one-dimensional array of pictures representing all of the picture cells. This property is not available at design time and is read-only at run time.

Syntax

[form.]PictureClip.GraphicCell (Index%)

Remarks

  • Use the Rows and Cols properties to divide a picture into a uniform matrix of graphic cells.

  • The cells specified by GraphicCell are indexed, beginning with 0, and increase from left to right and top to bottom.

  • When reading this property, an error is generated when there is no picture or when the Rows or Cols property is set to 0.

Data Type

Integer


Height, Width Properties (PictureClip Control)

Return the height and width (in pixels) of a bitmap contained in the control. These properties are not available at design time and are read-only at run time.

Syntax

[form.]PictureClip.Height

[form.]PictureClip.Width

Remarks

These properties are only valid when the control contains a bitmap.

You can load a bitmap into a PictureClip control at design time using the Properties sheet. In Visual Basic, you can also load a bitmap into a PictureClip control at run time by using the LoadPicture function.

Data Type

Integer


Picture Property (PictureClip Control)

This property is the same as the standard Visual Basic Picture property except that it supports only bitmap (.bmp) files.


StretchX, StretchY Properties (PictureClip Control)

Specify the target size for the bitmap created with the Clip property. These properties are not available at design time.

Syntax

[form.]PictureClip.StretchX[ = X%]

[form.]PictureClip.StretchY[ = Y%]

Remarks

Use these properties to define the area to which the Clip bitmap is copied. When the bitmap is copied, it is either stretched or condensed to fit the area defined by StretchX and StretchY.

StretchX and StretchY are measured in pixels.

Note In Visual Basic, the default ScaleMode for forms and picture boxes is twips. Set ScaleMode = 3 (pixels) for all controls that display pictures from a PictureClip control.

Data Type

Integer