Sharing Message Loops Between Win32 and WPF

This topic describes how to implement a message loop for interoperation with Windows Presentation Foundation (WPF), either by using existing message loop exposure in Dispatcher or by creating a separate message loop on the Win32 side of your interopation code.

ComponentDispatcher and the Message Loop

A normal scenario for interoperation and keyboard event support is to implement IKeyboardInputSink, or to subclass from classes that already implement IKeyboardInputSink such as HwndSource or HwndHost. However, keyboard sink support does not address all possible message loop needs you might have when sending and receiving messages across your interoperation boundaries. To help formalize an application message loop architecture, Windows Presentation Foundation (WPF) provides the ComponentDispatcher class that defines a simple protocol for a message loop to follow.

ComponentDispatcher is a static class that exposes esveral members. The scope of each method is implicitly tied to the calling thread. A message loop must call some of those APIs at critical times (as defined in the next section of this topic).

ComponentDispatcher provides events that other components (such as the keyboard sink) can listen to. The Dispatcher class calls all the appropriate ComponentDispatcher methods at an appropriate sequence. If you are implementing your own message loop, your code is responsible for calling ComponentDispatcher methods in a similar fashion.

Calling ComponentDispatcher methods on a thread will only invoke event handlers that were registered on that thread.

Writing Message Loops

The following is a checklist of ComponentDispatcher members you will use if you write your own message loop.

  • PushModal :your message loop should call this to indicate that the thread is modal.

  • PopModal :your message loop should call this to indicate that the thread has reverted to nonmodal.

  • RaiseIdle :your message loop should call this to indicate that ComponentDispatcher should raise the ThreadIdle event. ComponentDispatcher will not raise ThreadIdle if IsThreadModal is true, but message loops may choose to call RaiseIdle even if ComponentDispatcher cannot respond to it while in modal state.

  • RaiseThreadMessage :your message loop should call this to indicate that a new message is available. The return value indicates whether a listener to a ComponentDispatcher event handled the message. If RaiseThreadMessage returns true (handled), the dispatcher should do nothing further with the message. If the return value is false, the dispatcher is expected to call the Win32 function TranslateMessage, then call DispatchMessage.

Using ComponentDispatcher and Existing Message Handling

The following is a checklist of ComponentDispatcher members you will use if you rely on the inherent WPF message loop.

  • IsThreadModal : returns whether the application has gone modal (e.g., a modal message loop has been pushed). ComponentDispatcher can track this state because the class maintains a count of PushModal and PopModal calls from the message loop.

  • ThreadFilterMessage and ThreadPreprocessMessage events follow the standard rules for delegate invocations. Delegates are invoked in an unspecified order, and all delegates are invoked even if the first one marks the message as handled.

  • ThreadIdle : indicates an appropriate and efficient time to do idle processing (there are no other pending messages for the thread). ThreadIdle will not be raised if the thread is modal.

  • ThreadFilterMessage : raised for all messages that the message pump processes.

  • ThreadPreprocessMessage : raised for all messages that were not handled during ThreadFilterMessage.

A message is considered handled if after the ThreadFilterMessage event or ThreadPreprocessMessage event, the handled parameter passed by reference in event data is true. Event handlers should ignore the message if handled is true, because that means the different handler handled the message first. Event handlers to both events may modify the message. The dispatcher should dispatch the modified message and not the original unchanged message. ThreadPreprocessMessage is delivered to all listeners, but the architectural intention is that only the top-level window containing the hwnd at which the messages targeted should invoke code in response to the message.

How HwndSource Treats ComponentDispatcher Events

If the HwndSource is a top-level window (no parent HWND), it will register with ComponentDispatcher. If ThreadPreprocessMessage is raised, and if the message is intended for the HwndSource or child windows, HwndSource calls its TranslateAccelerator, TranslateChar, OnMnemonic keyboard sink sequence.

If the HwndSource is not a top-level window (has a parent HWND), there will be no handling. Only the top level window is expected to do the handling, and there is expected to be a top level window with keyboard sink support as part of any interoperation scenario.

If WndProc on an HwndSource is called without an appropriate keyboard sink method being called first, your application will receive the higher level keyboard events such as KeyDown.  However, no keyboard sink methods will be called, which circumvents desirable keyboard input model features such as access key support. This might happen because the message loop did not properly notify the relevant thread on the ComponentDispatcher, or because the parent HWND did not invoke the proper keyboard sink responses.

See Also

Reference

ComponentDispatcher
IKeyboardInputSink

Concepts

WPF and Win32 Interoperation Overview
Threading Model
Input Overview