IUIImageFromBitmap::CreateImage method

Creates an IUIImage object from a bitmap image.

Syntax


HRESULT CreateImage(
  [in]   HBITMAP bitmap,
  [in]   UI_OWNERSHIP options,
  [out]  IUIImage **image
);

Parameters

bitmap [in]

Type: HBITMAP

A handle to the bitmap that contains the image.

options [in]

Type: UI_OWNERSHIP

The ownership conditions under which an image is created.

ValueMeaning
UI_OWNERSHIP_TRANSFER If UI_OWNERSHIP_TRANSFER is specified as the value of options, then the Ribbon framework owns the handle to the bitmap (HBITMAP) through the IUIImage object and releases it when the framework no longer requires it.

Note   This option prevents the Ribbon host application from safely referencing the same HBITMAP elsewhere in the application UI.

UI_OWNERSHIP_COPY If UI_OWNERSHIP_COPY is specified as the value of options, then the host application owns the HBITMAP and is able to reference the same HBITMAP for use elsewhere in the UI.

Note   This option places responsibility for releasing the HBITMAP on the host application.

 

image [out]

Type: IUIImage**

When this method returns, contains the address of a pointer variable that receives the IUIImage object.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This factory method is useful when an application dynamically generates an image resource and wants to pass the new HBITMAP to the Ribbon, for example, loading a Portable Network Graphics (PNG) through the Windows Imaging Component (WIC) or using CreateDIBSection to create an image for a new style in a styles gallery.

This method is also useful for applications that require a pre-existing bitmap image that has not been rendered obsolete by the Ribbon, for example, a legacy toolbar image strip.

Specify UI_OWNERSHIP_COPY as the value for options if the Ribbon is being implemented in an existing application and minimal code changes are required. This method uses extra memory for the additional image.

Specify UI_OWNERSHIP_TRANSFER as the value for options to minimize memory usage.

Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Product

Windows UI

Header

Uiribbon.h

IDL

Uiribbon.idl

DLL

Mshtml.dll

See also

IUIImageFromBitmap
Windows Ribbon Framework Samples

 

 

Community Additions

ADD
Show:
© 2014 Microsoft