Share via

IPimSrcContactListIcon::Paint

  • Article

4/8/2010

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] Reference to the current PIM item's Object Identifier (OID). OIDs are DWORD values that uniquely identify POOM items within an Item Store. In POOM, an OID is also a Windows CE Object Identifier (CEOID), which uniquely identify all WINCE objects (databases, database volumes, database records, files, registry keys, etc.). You can find the definition for this type in the Windbase.h header file.

    Note

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

Return Value

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 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 device. Data synchronized with the Windows Mobile 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 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. CTestProvider is the class that implements the COM server for the source provider, and it derives from IPimSrcContactListIcon.

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";

STDMETHODIMP CTestProvider::Paint(const SRCCUSTOMDRAW *pscd, CEOID oid)
{
    HRESULT hr = S_OK;

    // Load an icon from the resource, and setup the required resources.
    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

Header pimstore.h
Library Pimstore.lib
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

See Also

Reference

IPimSrcContactListIcon
Customizing the PIM User Experience by Using Source Providers
Source Provider Customization Type Flags
Source Provider PIM Type Ownership Flags
PIMSRC_COLOR
IPimSrcContactSummaryCard::Display
IPimSrcContactNew::Create

Other Resources

Register a Source Provider