ISideShowNotification::Image Property

Article
11/02/2006

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);
    }
}

Applies To

ISideShowNotification

Share via