Creates an object reference for a bitmap, icon, or Windows meta file.
Supported Image TypesImage Type Groups | Filename Extensions |
---|
bitmaps | .bmp, .jpg, .jpeg, .jpe, .jfif, .gif, .giff, .gfa |
icons | .ico |
windows metafiles | .wmf |
windows enhanced metafiles | .emf |
cursor | .cur |
The following restrictions (tested with VFP 9 SP2 and OlePro32.dll Version 6.0.6002.18005) exist:
Known LimitationsImage Type Groups | Restrictions & Issues |
---|
bitmaps |
Loading these .tif and .png formats will cause an OLE error.
|
icons |
Icons are allowed with sizes up to 128x128 and must not have more than 256 colors. Even if there is more than one icon stored in the icon file,
always only the smallest icon gets displayed. The icon file may contain much more icons - even with more colors and larger sizes - as long as there is at least
one that complies with the rules above, then no exception is thrown.
|
cursor |
Cursor files must not have more than 1K of file size, otherwise an OLE error is generated. Cursor files containing 16 color cursors can be loaded
flawlessly, but only monochrome output is supported. Loading an animated cursor (.ani) causes an OLE error to be raised.
|
Null Picture Support
If cFileName is omitted, the "null picture" is returned.
You can include GetPict( ) as cFileName to display the Open dialog from which you can choose a bitmap file.
Picture objects provide a language-neutral abstraction for bitmaps, icons, and metafiles.
As with the standard font object, the system provides a standard implementation of the picture object.
Its primary interfaces are
iPicture and
iPictureDisp.
A picture object is created with
OleCreatePictureIndirect and supports both the
iPicture and the
iPictureDisp interfaces.
The OLE-provided picture object implements the complete semantics of the
iPicture and
iPictureDisp interfaces.
In other words, there’s no need to use another interface than
iPicture!
LoadPicture( ) Function internally wraps the
OleCreatePictureIndirect() function implemented in
OleAut32.dll.
Thus, all you can read about that function (above and online) is also true for VFP’s
LoadPicture() function.
LoadPicture( ) Function was added to VFP’s vocabulary to make it easier to load images with COM interfaces
that many presentation properties of ActiveX controls require for their settings.
For example, the ActiveX Outline control has a
PictureOpen property that requires a COM object image reference for its setting.
The COM object returned by
LoadPicture( ) Function hides its primary interface
iPicture.
In contrast to the reference returnd by
LoadPicture( ) Function, the OLE-image’s primary
iPicture interface is the only fully functional one.
In other words, only
iPitcure can be used in VFP programms without generating any OLE errors.
Because
iPicture is a superset of Picture it may be, better, it should be used everywhere instead of the one returnd by
LoadPicture( ) Function!
Example #1 in the examples section below proves that it makes no difference which OLE image interface gets assigned to a
oIMAGE.PICTUREVAL property.
The IID of the
iPicture interface is defined as “{7BF80980-BF32-101A-8BBB-00AA00300CAB}”.
The following two lines of code both create a null picture OLE image object:
1oIPicture1 = GETINTERFACE(LoadPicture(), "iPicture")
2oIPicture2 = CreateObjectEx("StdPicture","","{7BF80980-BF32-101A-8BBB-00AA00300CAB}")
Interfacemembers
The following table summarizes the PEMs
iPicture interface.
iPicture Interface MembersPEM | Name | Used for | ValueType | Read/Writable |
---|
property | Attributes | The current set of the picture's bit attributes. | DWORD (int) | readonly |
property | CurDC | The current device context into which this picture is selected. | HDC (long) | readonly |
property | Handle | Handle to the picture managed within this picture object. | OLE_Handle (int) | readonly |
property | Height | The current height of the picture in the picture object. | OLE_XSIZE_HIMETRIC (long) | readonly |
property | hPal | The current palette of the picture (if any). | OLE_Handle (int) | read/writable |
property | KeepOriginalFormat | The current value of the picture object's KeepOriginalFormat property. | Bool | read/writable |
property | Type | The current type of the picture. | Short (int) | readonly |
property | Width | The current width of the picture in the picture object. | OLE_XSIZE_HIMETRIC (long) | readonly |
method | PictureChanged() | Notifies the picture object that its picture resource changed. |
method | Render() | Draws the specified portion of the picture onto the specified device context, positioned at the specified location. |
method | SaveAsFile() | Saves the picture's data into a stream in the same format that it would save itself into a file. |
method | SelectPicture() |
Selects a bitmap picture into a given device context, returning the device context in which the picture was previously selected
as well as the picture's handle.
|
The
Attributes property is said to hold the picture’s bit attributes. Actually, there are only two, which can be set alone, or additive.
The following table lists both possible values:
iPicture.Attributes EnumerationConstant | Description | Value |
---|
PICTURE_SCALABLE |
The picture object is scalable, such that it can be redrawn with a different size than was used to create the picture originally.
Metafile-based pictures are considered scalable; icon and bitmap pictures, while they can be scaled, do not express this attribute because both involve bitmap
stretching instead of true scaling.
| 1 |
PICTURE_TRANSPARENT |
The picture object contains an image that has transparent areas, such that drawing the picture will not necessarily fill in all the spaces in the rectangle
it occupies. Metafile and icon pictures have this attribute; bitmap pictures do not.
| 2 |
The following table lists all possible values of the
iPicture.Type property:
Constant | Description | Value |
---|
PICTYPE_UNINITIALIZED | The picture object is currently uninitialized. This value is never be returned within VFP. | -1 |
PICTYPE_NONE | A new picture object is to be created without an initialized state. This value is returned from VFP if LoadPicture() is used without a parameter. | 0 |
PICTYPE_BITMAP | The picture type is a bitmap. | 1 |
PICTYPE_METAFILE | The picture type is a metafile. | 2 |
PICTYPE_ICON | The picture type is an icon. | 3 |
PICTYPE_ENHMETAFILE | The picture type is an enhanced metafile. | 4 |
The most interesting method of the COM image object’s
iPicture interface is
render() which also works flawlessly only when called on the
iPicture interface.
The following table summarises the parameters of the
render() method:
Parameter | Used for | Scale unit |
---|
hdc | A handle of the device context on which to render the image. |
x | The horizontal coordinate in hdc at which to place the rendered image (X-position of upper left corner of output rectangle). | pixel |
y | The vertical coordinate in hdc at which to place the rendered image (X-position of upper left corner of output rectangle). | pixel |
cx | The horizontal dimension (width) of the destination rectangle (with of output rectangle). | pixel |
cy | The vertical dimension (height) of the destination rectangle (height of output rectangle). | pixel |
xSrc | The horizontal offset in the source picture from which to start copying. | HiMetric |
ySrc | The vertical offset in the source picture from which to start copying. | HiMetric |
cxSrc | The horizontal extent to copy from the source picture (width of image source’s clipping region AND direction of readout). | HiMetric |
cySrc | The vertical extent to copy from the source picture (height of image source’s clipping region AND direction of readout). | HiMetric |
lprcWBounds |
If hdc is a metafile device context, the lprcWBounds parameter points to a RECTL structure specifying the bounding rectangle in the underlying metafile.
The rectangle structure contains the window extent and window origin. These values are useful for drawing metafiles.
The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same coordinate space.
If hdcDraw is not a metafile device context, lprcWBounds will be NULL. If hdcDraw is a metafile device context, lprcWBounds cannot be NULL!
|
The method returns standard values like E_FAIL, E_INVALIDARG and E_OUToFMEMORY, as well as S_OK, E_POINTER and CTL_E_INVALIDPROPERTYVALUE.
These values are described on MSDN.
applications
The render function has plenty of parameters. Some of them passing in pixel values, others HiMetric values.
Example #3 has some useful conversions as well as other supporting functions and definitions.
To figure out how
render() works try the VFP code below; type it in line by line into VFP’s command window:
Direct input into VFP’s command window
1* locate an image with round about 100 x 100 pixels
2goPic = LoadPicture(GetPict())
3gIP = GETINTERFACE(m.goPic, "iPicture")
4goForm = CreateObject("Form")
5goForm.Show()
6* declare access to the _client_area_ of a window
7DECLARE Integer GetDC IN User32 integer HWnd
8* hDC should be 0 (otherwise that's an error)!
9hDC = GetDC(goForm.HWnd)
10* render your image directly onto form's client area
11gIP.Render(m.hDC,0,0,100,100,0,gIP.Height,gIP.Width,- gIP.Height,NULL)
12* declare release function
13DECLARE Integer ReleaseDC IN User32 integer HWnd, integer hDC
14* next line should print 1 on the form's background >> "Okay"
15? ReleaseDC(m.goForm.HWnd, m.hDC)
16* declare access to the _whole_ window
17DECLARE Integer GetWindowDC IN User32 integer HWnd
18* hDC now references form's caption an border areas as well!
19hDC = GetWindowDC(goForm.HWnd)
20* render out partially overwriting form's border and caption
21gIP.Render(m.hDC,0,0,100,100,0,gIP.Height,gIP.Width,- gIP.Height,NULL)
22* never forget to free an allocated device context
23? ReleaseDC(m.goForm.HWnd, m.hDC)
iPicture.Render() qualifies for painting on otherwise unreachable form regions, like the TitleBar or WindowBorders.
Another interesting application for direct rendering stems from the fact that no VFP object reference is necessary for painting.
The
render() method solely uses a common windows handle. Thus, one can render on any known device context.br
If one encounters the so-called hourglass problem, working with a COM-based image can be the preferred workaround.
The hourglass mouse cursor gets displayed by the operation system during lengthy disk accesses.
Sometimes VFP does not reset the hourglass mouse cursor correctly.
Thus, the user still sees the “busy working” icon although VFP already is idle, as long she doesn’t touch the mouse.
Most often these disk accesses stem from refreshing pictures loaded into native Image-Objects using the
Image.Picture property.
Storing a COM memory-based object to the Image-Object’s
.PictureVal property instead, never causes any disk access.
Thus, no more hourglass mouse cursor will appear after a refresh!
DrawbackiPicture.Render() does its work outside of - and unnoticed by – the VFP engine itself.
That’s why VFP has no idea of what was painted “between the lines”.
Each time VFP refreshes the form’s area (we’ve just rendered our picture onto), will clear out our image.
To make rendered output persistent measures have to be taken against VFP wiping it out!
There is another BUG one has to be aware of, when employing the hourglass workaround described above!br
To see what happens, try the following code:
1LOCAL lnLoop, oComPic1, oComPic2
2oComPic1 = LoadPicture(GetFile())
3oComPic2 = LoadPicture(GetFile())
4TRY
5_Screen.Addobject("oImage","IMAGE")
6CATCH
7FINALLY
8_Screen.oImage.Visible = .T.
9ENDTRY
10For lnLoop = 1 to 100
11_Screen.oImage.PictureVal = m.oComPic1
12_Screen.oImage.PictureVal = m.oComPic2
13Next
14*
15*\\ whereas the next loop will break somewhere down the road:
16For lnLoop = 1 to 100
17_Screen.oImage.PictureVal = m.oComPic1
18_Screen.oImage.PictureVal = m.oComPic1
19_Screen.oImage.PictureVal = m.oComPic1
20_Screen.oImage.PictureVal = m.oComPic2
21Next
One can see, that the first loop executes flawlessly, the second one breaks after only a few loops with a “Property value is invalid” error message!
This bug is hard to track and occurs only in cases when someone tries to assign the same COM-reference more than once in a row!
The workaround for this is to keep track which COM-reference is actually assigned to the Image’s PictureVal property.
Never ever then reassign the same reference a second time (overwriting the first one with a copy of itself)!
BTW: It doesn’t matter what interface you are using.
The error seems to stem from VFP’s Image class instance.