Visual Basic Reference
MaskPicture Property (UserControl Object)
See Also Example Applies To
Returns or sets the bitmap that, combined with the MaskColor property, determines the transparent and visible regions of a UserControl object whose BackStyle property is set to 0 (Transparent).
Syntax
object.MaskPicture [= picture]
The MaskPicture property syntax has these parts:
| Part | Description |
| object | An object expression that evaluates to an object in the Applies To list. |
| picture | A graphic image of one of the types described in Settings. |
Settings
The settings for picture are:
| Setting | Description |
| Nothing | (Default) No picture. At design time, highlight the property value and press the Delete key; "(None)" will appear in the Properties window. At run time, assign the return value of the LoadPicture function with no filename, or use the Set statement to assign the value Nothing to the property. |
| (Bitmap, DIB, GIF, or JPEG) | Specifies an image-type bitmap. At design time, you can use the Properties window to enter a string expression specifying a file containing a graphic. At run time, you can set this property using a Picture object, using another object's Picture property, or using the LoadPicture function on an image-type bitmap file. |
Important This feature is supported only for image-type bitmaps, such as GIF, JPEG, and DIB. It is not supported for Windows metafiles, icons, or cursors.
Remarks
When a bitmap is assigned to the MaskPicture property of a UserControl whose BackStyle property is set to 0 (Transparent), the control becomes transparent wherever it is covered by areas of the bitmap that match the MaskColor property.
Mouse events that occur over the transparent areas are received by the container or by controls that would otherwise be covered by the UserControl.
The non-transparent parts of the MaskPicture bitmap are painted with the color specified by the UserControl's BackColor property. These areas, which need not be contiguous, define the clipping region for drawing on the UserControl. That is, any drawing that is done on the surface of the UserControl is clipped to the non-transparent parts of the MaskPicture bitmap.
Important The bitmap assigned to the MaskPicture property is only used to define the transparent region and clipping region for the UserControl. The bitmap is never displayed. To display a bitmap on top of the clipping region defined by MaskPicture and MaskColor, you can assign the bitmap to the Picture property of the UserControl, or draw it on the UserControl using PaintPicture in the UserControl's Paint event.
You can create an animated clipping region for your control by drawing on a hidden PictureBox, and transferring the resulting image to the MaskPicture property of the UserControl.
Note When you set the MaskPicture property at design time, the graphic is saved and loaded with the .ctl and .ctx files that define the UserControl. If you make the project into a control component (.ocx file), the file contains the image. When you load a graphic at run time, by contrast, the graphic isn't saved with the component.
For more information, see "Giving Your Control a Transparent Background," in "Building ActiveX Controls" in "Creating ActiveX Components" in the Component Tools Guide.