IPicture interface (ocidl.h)

Article
07/22/2021

Manages a picture object and its properties. 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, the latter being derived from IDispatch to provide access to the picture's properties through Automation. A picture object is created with OleCreatePictureIndirect.

The picture object also supports the outgoing interface IPropertyNotifySink, so a client can determine when picture properties change. Because the picture object supports at least one outgoing interface, it also implements IConnectionPointContainer and its associated interfaces for this purpose.

The picture object also supports IPersistStream so that it can save and load itself from an instance of IStream. An object that uses a picture object internally would normally save and load the picture as part of the object's own persistence handling. The function OleLoadPicture simplifies the creation of a picture object based on stream contents.

Inheritance

The IPicture interface inherits from the IUnknown interface. IPicture also has these types of members:

Methods

The IPicture interface has these methods.


IPicture::get_Attributes Retrieves the current set of the picture's bit attributes.
IPicture::get_CurDC Retrieves the handle of the current device context. This property is valid only for bitmap pictures.
IPicture::get_Handle Retrieves the handle to the picture managed within this picture object to a specified location.
IPicture::get_Height Retrieves the current height of the picture in the picture object.
IPicture::get_hPal Retrieves a copy of the palette currently used by the picture object.
IPicture::get_KeepOriginalFormat Retrieves the current value of the picture's KeepOriginalFormat property.
IPicture::get_Type Retrieves the current type of the picture contained in the picture object.
IPicture::get_Width Retrieves the current width of the picture in the picture object.
IPicture::PictureChanged Notifies the picture object that its picture resource has changed. This method only calls IPropertyNotifySink::OnChanged with DISPID_PICT_HANDLE for any connected sinks.
IPicture::put_KeepOriginalFormat Sets the value of the picture's KeepOriginalFormat property.
IPicture::Render Renders (draws) a specified portion of the picture defined by the offset (xSrc,ySrc) of the source picture and the dimensions to copy (cxSrc,xySrc).
IPicture::SaveAsFile Saves the picture's data into a stream in the same format that it would save itself into a file. Bitmaps use the BMP file format, metafiles the WMF format, and icons the ICO format.
IPicture::SelectPicture Selects a bitmap picture into a given device context, and returns the device context in which the picture was previously selected as well as the picture's GDI handle. This method works in conjunction with IPicture::get_CurDC.
IPicture::set_hPal Assigns a GDI palette to the picture contained in the picture object.

Remarks

Each property in the IPicture interface includes a get_PropertyName method if the property supports read access and a put_PropertyName method if the property supports write access.

Property	Type	Access	Description
Handle	OLE_HANDLE (int)	R	The Windows GDI handle of the picture
hPal	OLE_HANDLE (int)	RW	The Windows handle of the palette used by the picture.
Type	short	R	The type of picture (see PICTYPE).
Width	OLE_XSIZE_HIMETRIC (long)	R	The width of the picture.
Height	OLE_YSIZE_HIMETRIC (long)	R	The height of the picture.
CurDC	HDC	R	The current device context.
KeepOriginalFormat	BOOL	RW	If TRUE, the picture object maintains the entire original state of the picture in memory. If FALSE, any state not applicable to the user's computer is discarded.
Attributes	DWORD	R	Miscellaneous bit attributes of the picture.

OLE Implementation

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.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	ocidl.h