IPimSrcContactListIcon::Paint

Article
08/28/2006

The Paint method enables a Source Provider to draw an alternate icon for its associated Contact items when they appear in the Contact list view.

Note To use this mechanism, you must provide your own implementation for Paint, within a new class that derives from IPimSrcContactListIcon.

Syntax

HRESULT Paint(
  const SRCCUSTOMDRAW * pscd,
  CEOID oid
)

Parameters

pscd
[in] Reference to a SRCCUSTOMDRAW structure, which contains painting information that the Source Provider uses to draw the icon.
oid
[in] The current PIM item's object identifier (OID).

Note This will be zero if the property does not already exist for the current Contact.

Return Values

This method returns the standard values E_INVALIDARG and E_FALSE, as well as the following:

S_OK
The method completed successfully.

Remarks

Source Providers and their associated Source ID's are part of a mechanism that supports per-provider customization of the PIM experience on Windows Mobile–based devices.

A Source Provider is a custom function that customizes the PIM user experience. Typically, a Source Provider has a corresponding associate function that is responsible for synchronizing PIM data with the Windows Mobile–based device. Data synchronized with the Windows Mobile–based device by this associate function is marked with a Source identification tag (Source ID). When Outlook Mobile displays a PIM item, it checks to see if the item has a Source ID. If it finds one, it invokes the Source Provider, which customizes the user interface for the PIM item.

When users enter new contacts and appointments, they can select a Source Provider to associate with them.

A valid Source ID is a DWORD with only 1 bit set (i.e., there are 32 possible Source IDs).

Although Contact and Appointment items, regardless of Source ID, are synchronized with Microsoft Exchange — Source IDs are not.

Source IDs are not supported for Task items.

Since Contacts and Appointments can be associated with only one Source Provider, your Source Provider installation implementation must select a Source ID that is unique in the domain of all Source Providers installed on the Windows Mobile–based device (it is considered an error to determine Source IDs prior to install). Your implementation must choose a unique Source ID by first iterating over the installed Source Providers registered in the key \HKLM\PIMSources\, and then choosing the next available Source ID.

The default Source ID value is zero (0). Contact and Appointment items with a Source ID value of zero are not associated with a Source Provider, and just use the default user interface.

Your Source Provider uninstall implementation must reset the Source ID field of all associated Contact and Appointment items back to zero.

The Contact item OID is passed as a parameter to IPimSrcContactListIcon::Paint so that the Source Provider can look up any additional properties it might require in order to determine how to draw the Contact item.

Sources must draw using a transparent background.

Code Example

The following code example demonstrates how to use Paint.

Note To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

// The following are assumed to be already defined in the resource and header files:

// #define IDI_APP_PROVIDERICON 101
// static LPTSTR g_szIconResource = MAKEINTRESOURCE(IDI_APP_PROVIDERICON);
// IDI_APP_PROVIDERICON ICON DISCARDABLE "SampleIcon.ico"

// The following code example assumes that CTestProvider is a class that implements the COM 
// server for the source provider which extends the IPimSrcContactListIcon::Paint
// interface.

STDMETHODIMP CTestProvider::Paint(const SRCCUSTOMDRAW *pscd, CEOID oid)
{

    HRESULT hr = S_OK;

    // Load an icon from the resource.
    // Setup the necessary resources (see comments above).
    HICON hIcons = LoadIcon((HINSTANCE) g_hInstance, g_szIconResource);    

    // Draw the custom icon using the RECT information.
    DrawIconEx(pscd->hdc, 
               pscd->rc.left, 
               pscd->rc.top, 
               hIcons, 
               (pscd->rc.right - pscd->rc.left), 
               (pscd->rc.bottom - pscd->rc.top), 
               0, 
               NULL, 
               DI_NORMAL);

    DestroyIcon(hIcons);

    return hr;

}

Requirements

Pocket PC: Windows Mobile Version 5.0 and later
Smartphone: Windows Mobile Version 5.0 and later
OS Versions: Windows CE 5.01 and later
Header: pimstore.h
Library: pimstore.lib