IPropertyPageSite Interface

IID_IPropertyPageSite

{B196B28C-BAB4-101A-B69C-00AA00341D07}

The IPropertyPageSite interface provides the main features for a property page site object. For each property page created within a property frame, the frame creates a property page site to provide information to the property page and to receive notifications from the page when changes occur. This latter notification is used to initiate a call to IPropertyPage::IsPageDirty, the return value of which is then used to enable or disable the frame's Apply button.

Use a site object with this interface to set up communications between the property frame and the property page object.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IPropertyPageSite Methods

Description

OnStatusChange

Indicates that the user has modified property values on the property page.

GetLocaleID

Returns the locale identifier so the property page can adjust itself to country-specific or region-specific settings.

GetPageContainer

Returns an IUnknown pointer for the object representing the entire property frame dialog box that contains all the pages.

TranslateAccelerator

Passes a keystroke to the property frame for processing.

PROPPAGESTATUS Enumeration

%PROPPAGESTATUS_DIRTY = &H1
%PROPPAGESTATUS_VALIDATE = &H2
%PROPPAGESTATUS_CLEAN = &H4

OnStatusChange

FUNCTION IPropertyPageSite_OnStatusChange ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwFlags AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IPropertyPageSite_OnStatusChange (pthis, dwFlags) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetLocaleID

FUNCTION IPropertyPageSite_GetLocaleID ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pLocaleID AS LONG _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IPropertyPageSite_GetLocaleID (pthis, pLocaleID) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetPageContainer

FUNCTION IPropertyPageSite_GetPageContainer ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppUnk AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IPropertyPageSite_GetPageContainer (pthis, ppUnk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

TranslateAccelerator

FUNCTION IPropertyPageSite_TranslateAccelerator ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pMsg AS tagMsg _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IPropertyPageSite_TranslateAccelerator (pthis, pMsg) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

IPropertyPageSite interface implementation

$IID_IPropertyPageSite = GUID$("{B196B28C-BAB4-101A-B69C-00AA00341D07}")

' ****************************************************************************************
' IPropertyPageSite interface
' ****************************************************************************************
TYPE IPropertyPageSiteVtbl
   ' IUnknown methods
   pQueryInterface         AS DWORD          ' // QueryInterface method
   pAddRef                 AS DWORD          ' // AddRef method
   pRelease                AS DWORD          ' // Release method
   ' IPropertyPageSite members
   pOnStatusChange         AS DWORD          ' // OnStatusChange method
   pGetLocaleID            AS DWORD          ' // GetLocaleID method
   pGetPageContainer       AS DWORD          ' // GetPageContainer method
   pTranslateAccelerator   AS DWORD          ' // TranslateAccelerator method
   ' Custom data
   pVtblAddr               AS DWORD          ' // Address of the virtual table
   cRef                    AS DWORD          ' // Reference count
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' Builds the IPropertyPageSite Virtual Table
' Returns a cookie that is a pointer to a IPropertyPageSiteVtbl structure.
' ****************************************************************************************
FUNCTION IPropertyPageSite_BuildVtbl () AS DWORD

   LOCAL pVtbl AS IPropertyPageSiteVtbl PTR
   LOCAL pUnk AS IPropertyPageSiteVtbl PTR

   pVtbl = HeapAlloc(GetProcessHeap(), %HEAP_ZERO_MEMORY, SIZEOF(@pVtbl))
   IF pVtbl = 0 THEN EXIT FUNCTION

   @pVtbl.pQueryInterface         = CODEPTR(IPropertyPageSite_QueryInterface)
   @pVtbl.pAddRef                 = CODEPTR(IPropertyPageSite_AddRef)
   @pVtbl.pRelease                = CODEPTR(IPropertyPageSite_Release)

   @pVtbl.pOnStatusChange         = CODEPTR(IPropertyPageSite_OnStatusChange)
   @pVtbl.pGetLocaleID            = CODEPTR(IPropertyPageSite_GetLocaleID)
   @pVtbl.pGetPageContainer       = CODEPTR(IPropertyPageSite_GetPageContainer)
   @pVtbl.pTranslateAccelerator   = CODEPTR(IPropertyPageSite_TranslateAccelerator)

   @pVtbl.pVtblAddr               = pVtbl
   @pVtbl.cRef                    = 1

   pUnk = VARPTR(@pVtbl.pVtblAddr)
   FUNCTION = pUnk

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' IPropertyPageSite_QueryInterface method
' Returns the IUnknown of our class and increments the reference counter.
' ****************************************************************************************
FUNCTION IPropertyPageSite_QueryInterface (BYVAL pCookie AS IPropertyPageSiteVtbl PTR, BYREF riid AS GUID, BYREF ppvObj AS DWORD) AS LONG
   IF riid = $IID_IPropertyPageSite THEN
      ppvObj = pCookie
      INCR @@pCookie.cRef
      FUNCTION = %S_OK
   ELSE
      FUNCTION = %E_NOINTERFACE
   END IF
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' IPropertyPageSite_AddRef method
' Increments the reference counter.
' ****************************************************************************************
FUNCTION IPropertyPageSite_AddRef (BYVAL pCookie AS IPropertyPageSiteVtbl PTR) AS DWORD
   INCR @@pCookie.cRef
   FUNCTION = @@pCookie.cRef
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' IPropertyPageSite_Release method
' Releases our class if there is only a reference to him and decrements the reference counter.
' ****************************************************************************************
FUNCTION IPropertyPageSite_Release (BYVAL pCookie AS IPropertyPageSiteVtbl PTR) AS DWORD
   DECR @@pCookie.cRef
   FUNCTION = @@pCookie.cRef
   IF @@pCookie.cRef = 0 THEN
      IF ISTRUE @@pCookie.pVtblAddr THEN
         HeapFree(GetProcessHeap(), 0, BYVAL @@pCookie.pVtblAddr)
      END IF
   END IF
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Indicates that the user has modified property values on the property page.
' ****************************************************************************************
FUNCTION IPropertyPageSite_OnStatusChange (BYVAL pCookie AS IPropertyPageSiteVtbl PTR, BYVAL dwFlags AS DWORD) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Returns the locale identifier so the property page can adjust itself to country-specific
' or region-specific settings.
' ****************************************************************************************
FUNCTION IPropertyPageSite_GetLocaleID (BYVAL pCookie AS IPropertyPageSiteVtbl PTR, BYREF pLocaleID AS LONG) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Returns an IUnknown pointer for the object representing the entire property frame dialog
' box that contains all the pages.
' ****************************************************************************************
FUNCTION IPropertyPageSite_GetPageContainer (BYVAL pCookie AS IPropertyPageSiteVtbl PTR, BYREF ppUnk AS DWORD) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Passes a keystroke to the property frame for processing.
' ****************************************************************************************
FUNCTION IPropertyPageSite_TranslateAccelerator (BYVAL pCookie AS IPropertyPageSiteVtbl PTR, BYREF pMsg AS tagMsg) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************