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.


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


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


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


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


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.


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	Properrty 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.


Change Event (placeholder)


Click Event (placeholder)


DblClick Event (placeholder)


DragDrop Event (placeholder)


DragOver Event (placeholder)


KeyDown Event (placeholder)


KeyPress Event (placeholder)


KeyUp Event (placeholder)


MouseDown Event (placeholder)


MouseMove Event (placeholder)


MouseUp Event (placeholder)


OLECompleteDragEvent (placeholder)


OLEDragDrop Event (placeholder)


OLEDragOver Event (placeholder)


OLEGiveFeedback Event (placeholder)


OLESetData Event (placeholder)


OLEStartDrag Event (placeholder)


Refresh Method (placeholder)


OLEDrag Method (placeholder)


Appearance Property (placeholder)


BackColor Property (placeholder)


Caption Property (placeholder)


Enabled Property (placeholder)


Font Property (placeholder)


ForeColor Property (placeholder)


IntegralHeight Property (placeholder)


Locked Property (placeholder)


MouseIcon Property (placeholder)


MousePointer Property (placeholder)


OLEDragMode Property (placeholder)


OLEDropMode Property (placeholder)


SelLength Property (placeholder)


SelStart Property (placeholder)


SelText Property (placeholder)


Style Property (placeholder)


Text Property (placeholder)


Keyword Not Found

The keyword you've selected can't be found in Visual Basic Help. It's possible that:

•	The keyword is misspelled

•	You selected too much or too little text

•	You asked for help on a word that is not a valid Visual Basic keyword.

The easiest way to get help on a specific keyword is to position the insertion point anywhere within the keyword you want help on and press F1. You do not need to select the keyword. In fact, if you select only a portion of the keyword, or more than a single word, Help will not find what you're looking for.

To use the built-in Help search dialog box, press the Help Topics button on the toolbar.

One option to possibly find what you're looking for is to view the ReadMe file that comes with Visual Basic. This document contains information regarding last-minute changes, additions, and deletions that did not make it into the final documentation.


Left, Top Properties (Placeholder)


Height, Width Properties (Placeholder)


Tag Property (Placeholder)


ToolTipText Property (Placeholder)


Count Property (Placeholder)


Item Method (Placeholder)


Hwnd Property (Placeholder)


TabStop Property (Placeholder)


Visible Property (Placeholder)


Picture Property (placeholder)


Max, Min Properties (placeholder)


Add Method (placeholder)


Clear Method (placeholder)


Container Property (placeholder)


Controls Collection (placeholder)


Copies Property (placeholder)


DataBinding Object (placeholder)


DataBindings Collection (placeholder)


Filename Property (placeholder)


FontBold, FontItalic, FontStrikeThru Properties (placeholder)


FontName Property (placeholder)


FontSize Property (placeholder)


GetData Method (placeholder)


GetFormat Method (placeholder)


HelpFile Property (placeholder)


Item Property (placeholder)


Remove Method (placeholder)


SetData Method (placeholder)


Align Property (placeholder)


DragIcon Property (placeholder)


DragMode Property (placeholder)


HelpContextID Property (placeholder)


TabIndex Property (placeholder)


Alignment Constants (placeholder)


Border Property Constants (placeholder)


BorderStyle Constants (placeholder)


BorderStyle Property (ActiveX Controls) (placeholder)


Clear Method (ActiveX Controls) (placeholder)


Clipboard Object Constants (placeholder)


Color Constants (placeholder)


CommonDialog Control Constants (placeholder)


CommonDialog Error Constants (placeholder)


Control Constants (placeholder)


DataBindings Property (placeholder)


DDE Constants (placeholder)


Drag-and-Drop Constants (placeholder)


Drawing Constants (placeholder)


FetchVerbs Method (placeholder)


Form Constants (placeholder)


Graphics Constants (placeholder)


Grid Control Constants (placeholder)


Help Constants (placeholder)


HideSelection Property (ActiveX Controls) (placeholder)


HideSelection Property (placeholder)


Image Property (ActiveX Controls) (placeholder)


ImageList Property (ActiveX Controls) (placeholder)


Index Property (ActiveX Controls) (placeholder)


Index Property (placeholder)


Key Code Constants (placeholder)


Key Property (ActiveX Controls) (placeholder)


Menu Accelerator Constants (placeholder)


Menu Control Constants (placeholder)


Miscellaneous Constants (placeholder)


MousePointer Constants (placeholder)


OLE Container Control Constants (placeholder)


Picture Object Constants (placeholder)


Printer Object Constants (placeholder)


RasterOp Constants (placeholder)


Remove Method (ActiveX Controls) (placeholder)


ShowInTaskbar Property (placeholder)


ShowTips Property (ActiveX Controls) (placeholder)


ShowWhatsThis Method (placeholder)


Text Property (ActiveX Controls) (placeholder)


Value Property (ActiveX Controls) (placeholder)


Variant Type Constants (placeholder)


Visual Basic Constants (placeholder)


WhatsThisButton Property (placeholder)


WhatsThisHelp Property (placeholder)


WhatsThisHelpID Property (placeholder)


WhatsThisMode Method (placeholder)


Windows 95 Control Constants (placeholder)


ColIsVisible Property (placeholder)


ColPos Property (placeholder)


DataObject Object (placeholder)


DataObjectFiles Collection (placeholder)


DataSource Property (placeholder)


Drag Method (placeholder)


DrawMode Property (placeholder)


FixedAlignment Property (placeholder)


GotFocus Event (placeholder)


GridLineWidth Property (placeholder)


Index Property (Control Array) (placeholder)


LostFocus Event (placeholder)


Move Method (placeholder)


Name Property (placeholder)


Object Property (placeholder)


Parent Property (placeholder)


RowColChange Event (placeholder)


RowIsVisible Property (placeholder)


RowPos Property (placeholder)


SetFocus Method (placeholder)


ZOrder Method (placeholder)


Files Method (placeholder)


Connect Event (placeholder)


HScrollSmallChange, VScrollSmallChange Properties (placeholder)


MinHeight, MinWidth Properties (placeholder)


Property Pages Dialog Box (placeholder)


RemoteHost Property (placeholder)


RemotePort Property (placeholder)


ViewportHeight, ViewportLeft, ViewportTop, ViewportWidth Properties (placeholder)


Resync Method (Remote Data) (placeholder)


ContainedVBControls Collection (placeholder)


Member Object (placeholder)


Members Collection (placeholder)


VBComponentsEvents Object (placeholder)


VBProjectsEvents Object (placeholder)


Files Property (placeholder)


Alignment Property (placeholder)


AboutBox Method (placeholder)


Col, Row Properties (placeholder)


RowHeight Property (placeholder)


Scroll Event (placeholder)


ScrollBars Property (placeholder)


SelEndCol, SelStartCol, SelEndRow, SelStartRow Properties (placeholder)


ScrollBars Property (placeholder)


Appearance Property (ActiveX Controls) (placeholder)


BackColor, ForeColor Properties (ActiveX Controls) (placeholder)


BorderStyle Constants (ActiveX Controls) (placeholder)


Caption Property (ActiveX Controls) (placeholder)


Change Event (ActiveX Controls) (placeholder)


Clear Method (ActiveX Controls) (placeholder)


Click Event (ActiveX Controls) (placeholder)


Clipboard Object Constants (ActiveX Controls) (placeholder)


Count Property (ActiveX Controls) (placeholder)


DataObject Object (ActiveX Controls) (placeholder)


DataObjectFiles Collection (ActiveX Controls) (placeholder)


DataSource Property (ActiveX Controls) (placeholder)


DblClick Event (ActiveX Controls) (placeholder)


Drag-and-Drop Constants (ActiveX Controls) (placeholder)


Enabled Property (ActiveX Controls) (placeholder)


FetchVerbs Method (ActiveX Controls) (placeholder)


Files Method (ActiveX Controls) (placeholders)


Font Property (ActiveX Controls) (placeholder)


FontName Property (ActiveX Controls) (placeholder)


FontSize Property (ActiveX placeholder)


GetData Method (ActiveX Controls) (placeholder)


GetFormat Method (ActiveX Controls) (placeholder)


HideSelection Property (ActiveX Controls) (complaceholder)


hWnd Property (ActiveX Controls) (placeholder)


Item Method (ActiveX Controls) (placeholder)


Key Code Constants (ActiveX Controls) (placeholder)


Key Property (ActiveX Controls) (complaceholder)


KeyDown, KeyUp Events (ActiveX Controls) (placeholder)


KeyPress Event (ActiveX Controls) (placeholder)


Max, Min Properties (ActiveX Controls) (placeholder)


MouseDown, MouseUp Events (ActiveX Controls) (placeholder)


MouseIcon Property (ActiveX Controls) (placeholder)


MouseMove Event (ActiveX Controls) (placeholder)


MousePointer Constants (ActiveX Controls) (placeholder)


MousePointer Property (ActiveX Controls) (placeholder


OLECompleteDrag Event (ActiveX Controls) (placeholder)


OLEDrag Method (ActiveX Controls) (placeholder)


OLEDragDrop Event (ActiveX Controls) (placeholder)


OLEDragMode Property (ActiveX Controls) (placeholder)


OLEDragOver Event (ActiveX Controls) (placeholder)


OLEDropMode Property (ActiveX Controls) (placeholder)


OLEGiveFeedback Event (ActiveX Controls) (placeholder)


OLESetData Event (ActiveX Controls) (placeholder)


OLEStartDrag Event (ActiveX Controls) (placeholder)


Picture Property (ActiveX Controls) (placeholder)


Property Pages Dialog Box (ActiveX Controls) (placeholder)


RemoteHost Property (ActiveX Controls) (placeholder)


RemotePort Property (ActiveX Controls) (placeholder)


SelLength, SelStart, SelText Properties (ActiveX Controls) (placeholder)


SetData Method (ActiveX Controls) (placeholder)


ShowTips Property (ActiveX Controls) (complaceholder)


Text Property (ActiveX Controls) (complaceholder)


Value Property (ActiveX Controls) (complaceholder)


hDC Property (ActiveX Controls) (complaceholder)


Height, Width Properties (ActiveX Controls) (complaceholder)


Index Property (ActiveX Controls) (complaceholder)


Left, Top Properties (ActiveX Controls) (complaceholder)


Tag Property (ActiveX Controls) (complaceholder)


Visible Property (ActiveX Controls) (complaceholder)


Remove Method (ActiveX Controls) (complaceholder)


Object Property (ActiveX Controls) (placeholder)


Property Pages (ActiveX controls) (placeholder)


No fonts exist (Error 24574) (Common Dialog Control) (complaceholder)


Help Contents placeholder


BorderStyle Property (ActiveX Controls) (placeholder)


RightToLeft Property (ActiveX Controls) (placeholder)


Refresh Method (ActiveX Controls) (placeholder)