IPointerInactive Interface

IID_IPointerInactive

{55980BA0-35AA-11CF-B671-00AA004CD6D8}

The IPointerInactive interface enables an object to remain inactive most of the time, yet still participate in interaction with the mouse, including drag and drop.

Objects can be active (in-place or UI active) or they can be inactive (loaded or running). An active object creates a window and can receive Windows mouse and keyboard messages. An inactive object can render itself and provide a representation of its data in a given format. While they provide more functionality, active objects also consume more resources than inactive objects. Typically, they are larger and slower than inactive objects. Thus, keeping an object inactive can provide performance improvements.

However, an object, such as a control, needs to be able to control the mouse pointer, fire mouse events, and act as a drop target so it can participate in the user interface of its container application.

A container calls the methods in this interface for its embedded objects so that the embedded objects can participate in the user interface for the application.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IPointerInactive Methods

Description

GetActivationPolicy

Returns the present activation policy for the object.

OnInactiveMouseMove

Notifies the object that the mouse pointer has moved over it so the object can fire mouse events.

OnInactiveSetCursor

Sets the mouse pointer for an inactive object.

GetActivationPolicy

FUNCTION IPointerInactive_GetActivationPolicy ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pdwPolicy AS DWORD _

  ) AS LONG
 

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

END FUNCTION

OnInactivateMouseMove

FUNCTION IPointerInactive_OnInactiveMouseMove ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pRectBounds AS RECT _

, BYVAL x AS LONG _

, BYVAL y AS LONG _

, BYVAL grfKeyState AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IPointerInactive_OnInactiveMouseMove (pthis, pRectBounds, x, y, grfKeyState) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

OnInactivateSetCursor

FUNCTION IPointerInactive_OnInactiveSetCursor ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pRectBounds AS RECT _

, BYVAL x AS LONG _

, BYVAL y AS LONG _

, BYVAL dwMouseMsg AS DWORD _

, BYVAL fSetAlways AS LONG _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IPointerInactive_OnInactiveSetCursor (pthis, pRectBounds, x, y, dwMouseMsg, fSetAlways) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

IPointerInactive interface implementation

$IID_IPointerInactive = GUID$("{55980BA0-35AA-11CF-B671-00AA004CD6D8}")

' ****************************************************************************************
' IPointerInactive interface
' ****************************************************************************************
TYPE IPointerInactiveVtbl
   ' IUnknown methods
   pQueryInterface         AS DWORD          ' // QueryInterface method
   pAddRef                 AS DWORD          ' // AddRef method
   pRelease                AS DWORD          ' // Release method
   ' IPointerInactive members
   pGetActivationPolicy    AS DWORD          ' // GetActivationPolicy method
   pOnInactiveMouseMove    AS DWORD          ' // OnInactiveMouseMove method
   pOnInactiveSetCursor    AS DWORD          ' // OnInactiveSetCursor method
   ' Custom data
   pVtblAddr               AS DWORD          ' // Address of the virtual table
   cRef                    AS DWORD          ' // Reference count
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' Builds the IPointerInactive Virtual Table
' Returns a cookie that is a pointer to a IPointerInactiveVtbl structure.
' ****************************************************************************************
FUNCTION IPointerInactive_BuildVtbl () AS DWORD

   LOCAL pVtbl AS IPointerInactiveVtbl PTR
   LOCAL pUnk AS IPointerInactiveVtbl PTR

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

   @pVtbl.pQueryInterface         = CODEPTR(IPointerInactive_QueryInterface)
   @pVtbl.pAddRef                 = CODEPTR(IPointerInactive_AddRef)
   @pVtbl.pRelease                = CODEPTR(IPointerInactive_Release)

   @pVtbl.pGetActivationPolicy    = CODEPTR(IPointerInactive_GetActivationPolicy)
   @pVtbl.pOnInactiveMouseMove    = CODEPTR(IPointerInactive_OnInactiveMouseMove)
   @pVtbl.pOnInactiveSetCursor    = CODEPTR(IPointerInactive_OnInactiveSetCursor)

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

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

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

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

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

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

' ****************************************************************************************
' Returns the present activation policy for the object.
' ****************************************************************************************
FUNCTION IPointerInactive_GetActivationPolicy (BYVAL pCookie AS IPointerInactiveVtbl PTR, BYREF pdwPolicy AS DWORD) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Notifies the object that the mouse pointer has moved over it so the object can fire
' mouse events.
' ****************************************************************************************
FUNCTION IPointerInactive_OnInactiveMouseMove (BYVAL pCookie AS IPointerInactiveVtbl PTR, BYREF pRectBounds AS RECT, BYVAL x AS LONG, BYVAL y AS LONG, BYVAL grfKeyState AS DWORD) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Sets the mouse pointer for an inactive object.
' ****************************************************************************************
FUNCTION IPointerInactive_OnInactiveSetCursor (BYVAL pCookie AS IPointerInactiveVtbl PTR, pRectBounds AS RECT, BYVAL x AS LONG, BYVAL y AS LONG, BYVAL dwMouseMsg AS DWORD, BYVAL fSetAlways AS LONG) AS LONG
   ' Put your code here
END FUNCTION
' ****************************************************************************************