IOleControl Interface

IID_IOleControl

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

The IOleControl interface provides the features for supporting keyboard mnemonics (GetControlInfo, OnMnemonic), ambient properties (OnAmbientPropertyChange), and events (FreezeEvents) in control objects.

A control container uses this interface to work with keyboard mnemonics, ambient properties, and events of a contained control object.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IOleControl Methods

Description

GetControlInfo

Fills in a CONTROLINFO structure with information about a control's keyboard mnemonics and keyboard behavior.

OnMnemonic

Informs a control that the user has pressed a keystroke that matches one of the ACCEL entries in the mnemonic table returned through IOleControl::GetControlInfo. The control takes whatever action is appropriate for the keystroke.

OnAmbientPropertyChange

Informs a control that one or more of the container's ambient properties (available through the control site's IDispatch) has changed.

FreezeEvents

Indicates whether the container is ignoring or accepting events from the control.

CTRLINFO Enumeration

%CTRLINFO_EATS_RETURN = 1
%CTRLINFO_EATS_ESCAPE = 2

GetControlInfo

FUNCTION IOleControl_GetControlInfo ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pCI AS CONTROLINFO _

  ) AS LONG

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

END FUNCTION

OnMnemonic

FUNCTION IOleControl_OnMnemonic ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pMsg AS tagMSG _

  ) AS LONG

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

END FUNCTION

OnAmbientPropertyChange

FUNCTION IOleControl_OnAmbientPropertyChange ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dispID AS LONG _

  ) AS LONG

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

END FUNCTION

FreezeEvents

FUNCTION IOleControl_FreezeEvents ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL bFreeze AS LONG _

  ) AS LONG

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

END FUNCTION

IOleControl interface implementation

$IID_IOleControl = GUID$("{B196B288-BAB4-101A-B69C-00AA00341D07}")

' ****************************************************************************************
' IOleControl interface
' ****************************************************************************************
TYPE IOleControlVtbl
   ' IUnknown methods
   pQueryInterface          AS DWORD          ' // QueryInterface method
   pAddRef                  AS DWORD          ' // AddRef method
   pRelease                 AS DWORD          ' // Release method
   ' IOleControl members
   pGetControlInfo          AS DWORD          ' // GetControlInfo method
   pOnMnemonic              AS DWORD          ' // OnMnemonic method
   pOnAmbientPropertyChange AS DWORD          ' // OnAmbientPropertyChange method
   pFreezeEvents            AS DWORD          ' // FreezeEvents method
   ' Custom data
   pVtblAddr                AS DWORD          ' // Address of the virtual table
   cRef                     AS DWORD          ' // Reference count
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' Builds the IOleControl Virtual Table
' Returns a cookie that is a pointer to a IOleControlVtbl structure.
' ****************************************************************************************
FUNCTION IOleControl_BuildVtbl () AS DWORD

   LOCAL pVtbl AS IOleControlVtbl PTR
   LOCAL pUnk AS IOleControlVtbl PTR

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

   @pVtbl.pQueryInterface          = CODEPTR(IOleControl_QueryInterface)
   @pVtbl.pAddRef                  = CODEPTR(IOleControl_AddRef)
   @pVtbl.pRelease                 = CODEPTR(IOleControl_Release)

   @pVtbl.pGetControlInfo          = CODEPTR(IOleControl_GetControlInfo)
   @pVtbl.pOnMnemonic              = CODEPTR(IOleControl_OnMnemonic)
   @pVtbl.pOnAmbientPropertyChange = CODEPTR(IOleControl_OnAmbientPropertyChange)
   @pVtbl.pFreezeEvents            = CODEPTR(IOleControl_FreezeEvents)

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

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

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

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

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

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

' ****************************************************************************************
' Fills in a CONTROLINFO structure with information about a control's keyboard mnemonics
' and keyboard behavior.
' ****************************************************************************************
FUNCTION IOleControl_GetControlInfo (BYVAL pCookie AS IOleControlVtbl PTR, BYREF pCI AS CONTROLINFO) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Informs a control that the user has pressed a keystroke that matches one of the ACCEL
' entries in the mnemonic table returned through IOleControl::GetControlInfo. The control
' takes whatever action is appropriate for the keystroke.
' ****************************************************************************************
FUNCTION IOleControl_OnMnemonic (BYVAL pCookie AS IOleControlVtbl PTR, BYREF pCI AS CONTROLINFO) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Informs a control that one or more of the container's ambient properties (available
' through the control site's IDispatch) has changed.
' ****************************************************************************************
FUNCTION IOleControl_OnAmbientPropertyChange (BYVAL pCookie AS IOleControlVtbl PTR, BYVAL dispID AS LONG) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Informs a control that one or more of the container's ambient properties (available
' through the control site's IDispatch) has changed.
' ****************************************************************************************
FUNCTION IOleControl_FreezeEvents (BYVAL pCookie AS IOleControlVtbl PTR, BYVAL bFreeze AS LONG) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************