Creating a Property Frame

When a client or an object is ready to display a property sheet, it calls the function OleCreatePropertyFrame, which takes a large number of arguments:

STDAPI OleCreatePropertyFrame(HWND hWndOwner, UINT x, UINT y
    , LPCOLESTR lpszCaption, ULONG cObjects, IUnknown **lplpUnk
    , ULONG cPages, CLSID *lpPages, LCID lcid
    , DWORD dwReserved, LPVOID pvReserved);

Alternatively, the caller can put these arguments and an extra dispID into an OCPFIPARAMS structure and call OleCreatePropertyFrameIndirect:

typedef struct tagOCPFIPARAMS
    {
    ULONG      cbStructSize;
    HWND       hWndOwner;
    int        x;
    int        y;
    LPCOLESTR  lpszCaption;
    ULONG      cObjects;
    IUnknown **lplpUnk;
    ULONG      cPages;
    CLSID     *lpPages;
    LCID       lcid;
    DISPID     dispidInitialProperty;
    } OCPFIPARAMS;

STDAPI OleCreatePropertyFrameIndirect(LPOCPFIPARAMS pParams);

The common arguments and fields work as follows:

Argument/Field	Description
hWndOwner	The parent window of the modal dialog.
x, y	The position of the dialog in relation to hWndOwner.
lpszCaption	The caption to show in the dialog.
cObjects, lplpUnk	The array of objects affected by this property sheet; lplpUnk points to the array, and cObjects specifies the size of the array.
cPages, lpPages	The array of CLSIDs specifying which pages to display; lpPages points to the array of CLSIDs, and cPages specifies the size of the array.
lcid	The locale specifying the national language that should be shown.
dispIDInitialProperty	The property that gets the initial focus in per-property browsing. (See "Per-Property Browsing" later in this chapter.) Clients can pass such a dispID only through OleCreatePropertyFrameIndirect, as dwReserved must be 0 in OleCreatePropertyFrame. Specifying DISPID_UNKNOWN in this field results in behavior identical to that of OleCreatePropertyFrame, so the first control on the first page receives the initial focus.

Both the OleCreatePropertyFrame and OleCreatePropertyFrameIndirect functions create a modal dialog and attempt to instantiate and initialize each property page using the CLSIDs in lpPages. From that point, the dialog communicates with the pages, telling them when to show or hide themselves and when to apply changes to the affected objects. Because a modal dialog is involved, neither API function returns until the user closes the dialog box. The HRESULT return value may contain any error code, including those prefixed with CTL_E_ to specify problems with the arguments or structure fields.