IUIImageFromBitmap::CreateImage method (uiribbon.h)
Creates an IUIImage object from a bitmap image.
Syntax
HRESULT CreateImage(
[in] HBITMAP bitmap,
[in] UI_OWNERSHIP options,
[out] IUIImage **image
);
Parameters
[in] bitmap
Type: HBITMAP
A handle to the bitmap that contains the image.
[in] options
Type: UI_OWNERSHIP
The ownership conditions under which an image is created.
| Value | Meaning |
|---|---|
| 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.
|
[out] image
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
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Target Platform | Windows |
| Header | uiribbon.h |
| DLL | Mshtml.dll |