C++ Event Sinks Sample

Description of C++ event sinks sample for the Tablet PC.

This program demonstrates how you can build an application that captures InkCollector events using only C++. This program co-creates an InkCollector object to ink-enable the window. It displays a message box whenever a Stroke event is received.

Defining a Wrapper for Ink Collector Events

The InkCollectorEvents class handles passing ink collector events from the ink collector to the user of this class. The AdviseInkCollector method sets up the connection between the InkCollector object and this class. The Invoke method converts the IDispatch event notification into a call to a virtual function that the user of this class can override to process a particular event.

Note: You must do more than override the virtual function for an event handler to get that event. For all but default events, you have to call the ink collector's SetEventInterest method to guarantee getting an event. Secondly, this object marshals itself free threaded so all implemented event handlers need to be free threaded as well. Of particular importance is using Windows APIs, which may cause a switch to another thread as the event handler is not guaranteed to be running on the same thread as the window connected with the ink collector.

// Invoke translates from IDispatch to an event callout
//  that can be overriden by a subclass of this class.
STDMETHOD(Invoke)(
   DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    WORD /*wFlags*/,
    DISPPARAMS* pdispparams,
    VARIANT* pvarResult,
    EXCEPINFO* /*pexcepinfo*/,
    UINT* /*puArgErr*/)
{
    switch(dispidMember)
    {
        case DISPID_ICEStroke:
            Stroke(
                (IInkCursor*) pdispparams->rgvarg[2].pdispVal,
                (IInkStrokeDisp*) pdispparams->rgvarg[1].pdispVal,
                (VARIANT_BOOL *)pdispparams->rgvarg[0].pboolVal);
            break;
        ...
    }
    return S_OK;
}

virtual void Stroke(
    IInkCursor* Cursor,
    IInkStrokeDisp* Stroke,
    VARIANT_BOOL *Cancel)
{
    // This is a place holder designed to be overridden by
    //  user of this class.
    return;
}
...

The Init method calls CoCreateFreeThreadedMarshaler to set up a free threaded marshaler.

// Init: set up free threaded marshaller.
HRESULT Init()
{
    return CoCreateFreeThreadedMarshaler(this, &m_punkFTM);
}

The AdviseInkCollector method sets up the connection between the InkCollector object and this class. It first retrieves a connection point to the ink collector. Then it retrieves a pointer to the IInkCollectorEvents so that it may establish an advisory connection to the control.

// Set up connection between sink and InkCollector
HRESULT AdviseInkCollector(
    IInkCollector *pIInkCollector)
{
    // Get the connection point container
    IConnectionPointContainer *pIConnectionPointContainer;
    HRESULT hr = pIInkCollector->QueryInterface(        IID_IConnectionPointContainer,         (void **) &pIConnectionPointContainer);

    if (FAILED(hr))
        ...

    // Find the connection point for Ink Collector events
    hr = pIConnectionPointContainer->FindConnectionPoint(        __uuidof(_IInkCollectorEvents), &m_pIConnectionPoint);

    if (SUCCEEDED(hr))
    {
        // Hook up sink to connection point
        hr = m_pIConnectionPoint->Advise(this, &m_dwCookie);
    }

    if (FAILED(hr))
        ...

    // Don't need the connection point container any more.
    pIConnectionPointContainer->Release();
    return hr;
}

The UnadviseInkCollector method releases the connections the object has to the control.

// Remove the connection of the sink to the Ink Collector
HRESULT UnadviseInkCollector()
{
    HRESULT hr = m_pIConnectionPoint->Unadvise(m_dwCookie);    m_pIConnectionPoint->Release();    m_pIConnectionPoint = NULL;
    return hr;
}

Defining an Ink Collector Events Handler

The CMyInkEvents class overrides the default behavior of the Stroke event handler of the InkCollectorEvents class. The Stroke method displays a message box when the InkCollector receives a Stroke event.

class CMyInkEvents : public InkCollectorEvents
{
public:

    // Event: Stroke
    virtual void Stroke(
        IInkCursor* Cursor,
        IInkStrokeDisp* Stroke,
        VARIANT_BOOL *Cancel)
    {
        // Demonstrate that the event notification was received.
        MessageBox(m_hWnd, "Stroke Event", "Event Received", MB_OK);
    }

    CMyInkEvents()
    {
        m_hWnd = NULL;
    }

    HRESULT Init(
        HWND hWnd)
    {
        m_hWnd = hWnd;
        return InkCollectorEvents::Init();
    }

    HWND m_hWnd;
};

Defining an Ink Collector Wrapper

The CMyInkCollector class's Init method declares and initializes a CMyInkEvents object. It then creates an InkCollector object and associates the ink collector and the event handler. Finally, the InkCollector is attached to the window and enabled.

// Handle all initializaton
HRESULT Init(
HWND hWnd)
{
    // Initialize event sink. This consists of setting
    //  up the free threaded marshaler.
    HRESULT hr = m_InkEvents.Init(hWnd);

    if (FAILED(hr))
        ...

    // Create the ink collector
    hr = CoCreateInstance(CLSID_InkCollector, NULL, CLSCTX_ALL,        IID_IInkCollector, (void **) &m_pInkCollector);

    if (FAILED(hr))
        ...

    // Set up connection between Ink Collector and our event sink
    hr = m_InkEvents.AdviseInkCollector(m_pInkCollector);

    if (FAILED(hr))
        ...

    // Attach Ink Collector to window
    hr = m_pInkCollector->put_hWnd((long) hWnd);

    if (FAILED(hr))
        ...

    // Allow Ink Collector to receive input.
    return m_pInkCollector->put_Enabled(VARIANT_TRUE);
}

Accessing the Tablet PC Interfaces and the Wrapper Classes

First, include the headers for Tablet PC Automation interfaces. These are installed with the Microsoft® Windows® XP Tablet PC Edition Development Kit 1.7.

#include <msinkaut.h>
#include <msinkaut_i.c>

Then, include the headers for the wrapper classes and InkCollector event handler was defined.

#include "TpcConpt.h"
#include "EventSink.h"

Calling the Wrapper Classes

When the window is created, the Window procedure creates an ink collector wrapper and initializes the wrapper. When the window is destroyed, the Window procedure deletes the ink collector wrapper. The ink collector wrapper handles the creation and deletion of its associated event handler.

case WM_CREATE:

    // Allocate and initialize memory for object
    pmic = new CMyInkCollector();

    if (pmic != NULL)
    {
        // Real initialization. This consists of creating
        //  an ink collector object and attaching it to
        //  the current window.
        if (SUCCEEDED(pmic->Init(hWnd)))
        {
            return 0;
        }

        // Failure free resources.
        delete pmic;
        pmic = NULL;
    }

    return -1;
...
case WM_DESTROY:
    // The destructor for the object handles releasing the
    //  InkCollector and disconnecting the InkCollector
    //  from the object's event sink.
    delete pmic;
    pmic = NULL;
    PostQuitMessage(0);
    break;