CreatePicture Function

Purpose

Creates a new picture object initialized with a GDI bitmap or icon handle.

Syntax

Set p = CreatePicture(hBmp, Owner)

p	: Picture
hBmp	: Handle
Owner	: Bool

Description

The hBmp parameter specifies the GDI handle for a bitmap (BMP or DIB) or a icon.

The Owner parameter indicates whether the picture is to own the GDI picture handle for the picture it contains, so that the picture object will destroy its picture when the object itself is destroyed. When Owner = 1, the Picture object takes ownership.

Example

Example - Icon

Dim p As Picture

Dim h% = LoadIcon(_INSTANCE, 1)

Set p = CreatePicture(h, 0) // fOwn must be 0 for Icons as they are a shared resource

PaintPicture p, 1, 1

Example - Bitmap

OpenW 1

Local i%, h%, p As Picture

For i = 0 To 255 Step 2

Color RGB(i, i * 2, i * 3)

Circle 100, 100, i / 2

Next i

Get 0, 0, 200, 200, h// get the bitmap

Color 0

Set p = CreatePicture(h, 1)

Set Win_1.Picture = p

Win_1.PictureMode = 1

Win_1.Refresh

Remarks

The Owner parameter indicates whether the Picture object is to have ownership of the GDI image handle (bitmap, metafile or icon) for the picture it contains, so that the Picture object will destroy its picture when it itself is destroyed. A Picture object that owns a resource and goes out of scope calls DeleteObject() for a bitmap, DeleteEnhMetafile for a metafile, and DestroyIcon for an icon.

The Owner parameter should be set to 0 if a the Picture object is assigned a shared resource. The following functions return a shared resource:

LoadIcon(), LoadImage() with the LR_SHARED flag, CopyImage() (if you use the LR_COPYRETURNORG flag and the hImage parameter is a shared icon)

In general, when the application is responsible for destroying an image, the CreatePicture’s Owner parameter can be set to 1 if the Picture object must release the resource. Otherwise, the application must release the image explicitly using FreeBmp (DeleteObject), DeleteEnhMetafile, or DestroyIcon.