ISideShowNotification::Image Property
Contains an icon associated with a notification.
Declaration
[C++]
HRESULT get_Image(
HICON *out_phIcon
);
HRESULT put_Image(
HICON in_hIcon
);
Property Value
out_phIcon
[out] A pointer to a handle to an icon created for the notification by the Windows SideShow gadget and retrieved by the Windows SideShow platform. If the pointer gets set to NULL, no icon is associated with this notification.
in_hIcon
[in] A handle to an icon, provided by the Windows SideShow gadget. If the handle is NULL, no icon is associated with this notification.
This property is read/write.
Return Values
HRESULT value |
Description |
S_OK |
Success |
E_INVALIDARG |
The parameter out_phIcon is NULL. |
Remarks
Instances of a Component Object Model (COM) object that implement the ISideShowNotification interface, of which this property is a member, are created by the Windows SideShow gadget. After creation, the gadget sets the value of this property so that the Windows SideShow platform can retrieve it.
When putting this property, the Windows SideShow platform makes a copy of the icon. The Windows SideShow gadget retains ownership of the icon handle specified by in_hIcon and is responsible for deallocating it.
When getting this property, a copy of the icon is created for the Windows SideShow gadget and is returned by using the out_phIcon parameter. The gadget owns the returned icon handle and is responsible for deallocating it by using DestroyIcon.
The icon's default size is used.
The default value of this property is NULL, indicating that no icon is associated with this notification.
Example
This example demonstrates how to set the value of the ISideShowNotification::Image Property property in an instance of the SideShowNotification class. Before setting the value of this property, Windows SideShow gadgets must create an instance of the SideShowNotification class, as demonstrated in the example for the ISideShowNotification interface. After setting the value of this property, and after setting other property values in the instance of the SideShowNotification class, Windows SideShow gadgets normally show the notification, as demonstrated by the example for the Show method of the ISideShowNotificationManager interface.
In this example, the standard system warning icon is loaded and set as the value of the ISideShowNotification::Image Property property.
[C++]
HRESULT hr;
HICON hIcon;
//
// Call LoadIcon to load a system icon to use as the
// value of the Image property.
// Also check for failure.
//
hIcon = LoadIcon(NULL, IDI_WARNING);
if (NULL == hIcon)
{
//
// Handling of failures will be application-specific.
//
HandleFailure("LoadIcon", 0);
}
else
{
//
// Call put_Image to write the Image property, passing
// the handle to the icon that was previously loaded.
//
// Use a previously established pointer to an
// ISideShowNotification interface pointer.
//
// Also check for failure.
//
hr = pISideShowNotification->put_Image(hIcon);
if (FAILED(hr))
{
//
// Handling of failures will be application-specific.
//
HandleFailure("put_Image", hr);
}
}