IOleControlSite Interface

IID_IOleControlSite

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

The IOleControlSite interface provides the methods that enable a site object to manage each embedded control within a container. A site object provides IOleControlSite as well as other site interfaces such as IOleClientSite and IOleInPlaceSite. When a control requires the services expressed through this interface, it will query one of the other client site interfaces for IOleControlSite.

Implement this interface on an in-place capable site object to support the embedding of controls in the site.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IOleControlSite Methods

Description

OnControlInfoChanged

Informs the container that the control's CONTROLINFO structure has changed and that the container should call the control's IOleControl::GetControlInfo for an update.

LockInPlaceActive

Indicates whether or not this control should remain in-place active, regardless of possible deactivation events.

GetExtendedControl

Requests an IDispatch pointer to the extended control that the container uses to wrap the real control.

TransformCoords

Converts between a POINTL structure expressed in HIMETRIC units (as is standard in OLE) and a POINTF structure expressed in units the container specifies.

TranslateAccelerator

Instructs the container to process a specified keystroke.

OnFocus

Indicates whether the embedded control in this control site has gained or lost the focus.

ShowPropertyFrame

Instructs the container to show a property page frame for the control object if the container so desires.

OnControlInfoChanged

FUNCTION IOleControlSite_OnControlInfoChanged ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

  FUNCTION = %S_OK ' Returned in all cases

END FUNCTION

LockInPlaceActive

FUNCTION IOleControlSite_LockInPlaceActive ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL fLock AS LONG _

  ) AS LONG
 

  ' FUNCTION = %S_OK or FUNCTION = %E_NOTIMPL

END FUNCTION

GetExtendedControl

FUNCTION IOleControlSite_GetExtendedControl ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppDisp AS DWORD _

  ) AS LONG
 

  ' FUNCTION = %S_OK or FUNCTION = %E_NOTIMPL or FUNCTION = %E_POINTER

END FUNCTION

TransformCoords

FUNCTION IOleControlSite_TransformCoords ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pPtlHimetric AS POINTL _

, BYREF pPtfContainer AS POINTF _

, BYVAL dwFlags AS DWORD _

  ) AS LONG
 

  ' FUNCTION = %S_OK or FUNCTION = %E_NOTIMPL or FUNCTION = %E_POINTER

END FUNCTION

TranslateAccelerator

FUNCTION IOleControlSite_TranslateAccelerator ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pMsg AS tagMSG _

, BYVAL grfModifiers AS DWORD _

  ) AS LONG

  ' FUNCTION = %S_OK or FUNCTION = %S_FALSE or FUNCTION = %E_NOTIMPL

END FUNCTION

OnFocus

FUNCTION IOleControlSite_OnFocus ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL fGotFocus AS LONG _

  ) AS LONG
 

  FUNCTION = %S_OK ' Returned in all cases

END FUNCTION

ShowPropertyFrame

FUNCTION IOleControlSite_ShowPropertyFrame ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

  ' FUNCTION = %S_OK or FUNCTION = %E_NOTIMPL

END FUNCTION

IOleControlSite interface implementation

$IID_IOleControlSite = GUID$("{B196B289-BAB4-101A-B69C-00AA00341D07}")

' ****************************************************************************************
' IOleControlSite interface
' ****************************************************************************************
TYPE IOleControlSiteVtbl
   ' IUnknown methods
   pQueryInterface          AS DWORD          ' // QueryInterface method
   pAddRef                  AS DWORD          ' // AddRef method
   pRelease                 AS DWORD          ' // Release method
   ' IOleControlSite members
   pOnControlInfoChanged    AS DWORD          ' // OnControlInfoChanged method
   pLockInPlaceActive       AS DWORD          ' // LockInPlaceActive method
   pGetExtendedControl      AS DWORD          ' // GetExtendedControl method
   pTransformCoords         AS DWORD          ' // TransformCoords method
   pTranslateAccelerator    AS DWORD          ' // TranslateAccelerator method
   pOnFocus                 AS DWORD          ' // OnFocus method
   pShowPropertyFrame       AS DWORD          ' // ShowPropertyFrame method
   ' Custom data
   pVtblAddr                AS DWORD          ' // Address of the virtual table
   cRef                     AS DWORD          ' // Reference count
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' Builds the IOleControlSite Virtual Table
' Returns a cookie that is a pointer to a IOleControlSiteVtbl structure.
' ****************************************************************************************
FUNCTION IOleControlSite_BuildVtbl () AS DWORD

   LOCAL pVtbl AS IOleControlSiteVtbl PTR
   LOCAL pUnk AS IOleControlSiteVtbl PTR

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

   @pVtbl.pQueryInterface          = CODEPTR(IOleControlSite_QueryInterface)
   @pVtbl.pAddRef                  = CODEPTR(IOleControlSite_AddRef)
   @pVtbl.pRelease                 = CODEPTR(IOleControlSite_Release)

   @pVtbl.pOnControlInfoChanged    = CODEPTR(IOleControlSite_OnControlInfoChanged)
   @pVtbl.pLockInPlaceActive       = CODEPTR(IOleControlSite_LockInPlaceActive)
   @pVtbl.pGetExtendedControl      = CODEPTR(IOleControlSite_GetExtendedControl)
   @pVtbl.pTransformCoords         = CODEPTR(IOleControlSite_TransformCoords)
   @pVtbl.pTranslateAccelerator    = CODEPTR(IOleControlSite_TranslateAccelerator)
   @pVtbl.pOnFocus                 = CODEPTR(IOleControlSite_OnFocus)
   @pVtbl.pShowPropertyFrame       = CODEPTR(IOleControlSite_ShowPropertyFrame)

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

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

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

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

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

' ****************************************************************************************
' IOleControlSite_Release method
' Releases our class if there is only a reference to him and decrements the reference counter.
' ****************************************************************************************
FUNCTION IOleControlSite_Release (BYVAL pCookie AS IOleControlSiteVtbl 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
' ****************************************************************************************

' ****************************************************************************************
' Informs the container that the control's CONTROLINFO structure has changed and that the
' container should call the control's IOleControl::GetControlInfo for an update.
' ****************************************************************************************
FUNCTION IOleControlSite_OnControlInfoChanged (BYVAL pCookie AS IOleControlSiteVtbl PTR) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Indicates whether or not this control should remain in-place active, regardless of
' possible deactivation events.
' ****************************************************************************************
FUNCTION IOleControlSite_LockInPlaceActive (BYVAL pCookie AS IOleControlSiteVtbl PTR, BYVAL fLock AS LONG) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Requests an IDispatch pointer to the extended control that the container uses to wrap
' the real control.
' ****************************************************************************************
FUNCTION IOleControlSite_GetExtendedControl (BYVAL pCookie AS IOleControlSiteVtbl PTR, BYREF ppDisp AS DWORD) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Converts between a POINTL structure expressed in HIMETRIC units (as is standard in OLE)
' and a POINTF structure expressed in units the container specifies.
' ****************************************************************************************
FUNCTION IOleControlSite_TransformCoords (BYVAL pCookie AS IOleControlSiteVtbl PTR, BYREF pPtlHimetric AS POINTL, BYREF pPtfContainer AS POINTF, BYVAL dwFlags AS DWORD) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Indicates whether the embedded control in this control site has gained or lost the focus.
' ****************************************************************************************
FUNCTION IOleControlSite_OnFocus (BYVAL pCookie AS IOleControlSiteVtbl PTR, BYVAL fGotFocus AS LONG) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Instructs the container to show a property page frame for the control object if the
' container so desires.
' ****************************************************************************************
FUNCTION IOleControlSite_ShowPropertyFrame (BYVAL pCookie AS IOleControlSiteVtbl PTR) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************