CPictureHolder Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CPictureHolder Class.

Implements a Picture property, which allows the user to display a picture in your control.

class CPictureHolder  

Public Constructors

NameDescription
CPictureHolder::CPictureHolderConstructs a CPictureHolder object.

Public Methods

NameDescription
CPictureHolder::CreateEmptyCreates an empty CPictureHolder object.
CPictureHolder::CreateFromBitmapCreates a CPictureHolder object from a bitmap.
CPictureHolder::CreateFromIconCreates a CPictureHolder object from an icon.
CPictureHolder::CreateFromMetafileCreates a CPictureHolder object from a metafile.
CPictureHolder::GetDisplayStringRetrieves the string displayed in a control container's property browser.
CPictureHolder::GetPictureDispatchReturns the CPictureHolder object's IDispatch interface.
CPictureHolder::GetTypeTells whether the CPictureHolder object is a bitmap, a metafile, or an icon.
CPictureHolder::RenderRenders the picture.
CPictureHolder::SetPictureDispatchSets the CPictureHolder object's IDispatch interface.

Public Data Members

NameDescription
CPictureHolder::m_pPictA pointer to a picture object.

CPictureHolder does not have a base class.

With the stock Picture property, the developer can specify a bitmap, icon, or metafile for display.

For information on creating custom picture properties, see the article MFC ActiveX Controls: Using Pictures in an ActiveX Control.

CPictureHolder

Header: afxctl.h

Constructs a CPictureHolder object.

CPictureHolder();

Creates an empty CPictureHolder object and connects it to an IPicture interface.

BOOL CreateEmpty();

Return Value

Nonzero if the object is successfully created; otherwise 0.

Uses a bitmap to initialize the picture object in a CPictureHolder.

BOOL CreateFromBitmap(
    UINT idResource);

 
BOOL CreateFromBitmap(
    CBitmap* pBitmap,  
    CPalette* pPal = NULL,  
    BOOL bTransferOwnership = TRUE);

 
BOOL CreateFromBitmap(
    HBITMAP hbm,  
    HPALETTE hpal = NULL,  
    BOOL bTransferOwnership = FALSE);

Parameters

idResource
Resource ID of a bitmap resource.

pBitmap
Pointer to a CBitmap object.

pPal
Pointer to a CPalette object.

bTransferOwnership
Indicates whether the picture object will take ownership of the bitmap and palette objects.

hbm
Handle to the bitmap from which the CPictureHolder object is created.

hpal
Handle to the palette used for rendering the bitmap.

Return Value

Nonzero if the object is successfully created; otherwise 0.

Remarks

If bTransferOwnership is TRUE, the caller should not use the bitmap or palette object in any way after this call returns. If bTransferOwnership is FALSE, the caller is responsible for ensuring that the bitmap and palette objects remain valid for the lifetime of the picture object.

Uses an icon to initialize the picture object in a CPictureHolder.

BOOL CreateFromIcon(
    UINT idResource);

 
BOOL CreateFromIcon(
    HICON hIcon,  
    BOOL bTransferOwnership = FALSE);

Parameters

idResource
Resource ID of a bitmap resource.

hIcon
Handle to the icon from which the CPictureHolder object is created.

bTransferOwnership
Indicates whether the picture object will take ownership of the icon object.

Return Value

Nonzero if the object is successfully created; otherwise 0.

Remarks

If bTransferOwnership is TRUE, the caller should not use the icon object in any way after this call returns. If bTransferOwnership is FALSE, the caller is responsible for ensuring that the icon object remains valid for the lifetime of the picture object.

Uses a metafile to initialize the picture object in a CPictureHolder.

BOOL CreateFromMetafile(
    HMETAFILE hmf,  
    int xExt,  
    int yExt,  
    BOOL bTransferOwnership = FALSE);

Parameters

hmf
Handle to the metafile used to create the CPictureHolder object.

xExt
X extent of the picture.

yExt
Y extent of the picture.

bTransferOwnership
Indicates whether the picture object will take ownership of the metafile object.

Return Value

Nonzero if the object is successfully created; otherwise 0.

Remarks

If bTransferOwnership is TRUE, the caller should not use the metafile object in any way after this call returns. If bTransferOwnership is FALSE, the caller is responsible for ensuring that the metafile object remains valid for the lifetime of the picture object.

Retrieves the string that is displayed in a container's property browser.

BOOL GetDisplayString(CString& strValue);

Parameters

strValue
Reference to the CString that is to hold the display string.

Return Value

Nonzero if the string is successfully retrieved; otherwise 0.

This function returns a pointer to the CPictureHolder object's IPictureDisp interface.

LPPICTUREDISP GetPictureDispatch();

Return Value

A pointer to the CPictureHolder object's IPictureDisp interface.

Remarks

The caller must call Release on this pointer when finished with it.

Indicates whether the picture is a bitmap, metafile, or icon.

short GetType();

Return Value

A value indicating the type of the picture. Possible values and their meanings are as follows:

ValueMeaning
PICTYPE_UNINITIALIZEDCPictureHolder object is unititialized.
PICTYPE_NONECPictureHolder object is empty.
PICTYPE_BITMAPPicture is a bitmap.
PICTYPE_METAFILEPicture is a metafile.
PICTYPE_ICONPicture is an icon.

A pointer to the CPictureHolder object's IPicture interface.

LPPICTURE m_pPict;  

Renders the picture in the rectangle referenced by rcRender.

void Render(
    CDC* pDC,  
    const CRect& rcRender,  
    const CRect& rcWBounds);

Parameters

pDC
Pointer to the display context in which the picture is to be rendered.

rcRender
Rectangle in which the picture is to be rendered.

rcWBounds
A rectangle representing the bounding rectangle of the object rendering the picture. For a control, this rectangle is the rcBounds parameter passed to an override of COleControl::OnDraw.

Connects the CPictureHolder object to a IPictureDisp interface.

void SetPictureDispatch(LPPICTUREDISP pDisp);

Parameters

pDisp
Pointer to the new IPictureDisp interface.

Hierarchy Chart
CFontHolder Class

Show: