Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Objective Grid User's Guide
Rogue Wave web site:  Home Page  |  Main Documentation Page

15.4 Plug-in Components

15.4.1 Motivation

MFC has its limitations when it comes to encapsulating different window functionality into separate objects. When you program with MFC, you often have to implement different window actions based on user events. For example, when the user presses a mouse button, the MFC window is set into a special context. In subsequent mouse messages, you check the context of the window and give graphical feedback to the user based on the mouse movements. Once the user releases the mouse button, you reset the window context and perform the specified user action. Suppose you want to add support for more user actions. The easiest way is to add if-statements for each context in your message handlers. This approach has severe disadvantages: each event handler is responsible for handling a variety of actions that are not related to each other. In short, it ignores encapsulation.

As an experienced C++ developer, you want to get rid of these if-statements and provide individual objects for each user action. The goal of this article is to show you a new approach for encapsulating user actions into separate objects that support MFC message maps. These special objects, called Plug-in components, can be reused among different window and view objects without code duplication. To give you a real world example for using this plug-in approach, this article includes a convenient reusable MFC class called CMSJIntelliMousePlugin that can be attached to any CWnd or CView class. The component provides support for IntelliMouse scrolling, zooming, and panning. No code change is necessary in the component source code to use its functionality with different window and view classes.

15.4.2 Existing Approaches

There are existing approaches that encapsulate user actions into separate objects and do not use if-statements, but these solutions lack support for the MFC message map. Consequently, most MFC developers avoid these approaches.

15.4.2.1 Approach One

The first approach is to add message handlers to the window class and forward each of these messages to the attached component object that is responsible for handling the user actions. The following code snippet demonstrates how to delegate the WM_MOUSEMOVE message to an attached object:

The disadvantage of this approach is obvious. There is a tight coupling between the window class and the user action component. Whenever you need to process a new message in the component, you need to add a message handler in the parent window class and forward it to the component. You might try to solve the problem by providing pre-defined message handlers for each window message, but this approach has the disadvantage that it results in a large amount of messages and relatively few of them will be used.

15.4.2.2 Approach Two

The second approach is to override the WindowProc() method that is the entry point for all window messages sent to a window. In the overridden method, you can forward each window message to the attached user action component object. In the attached component, you implement a switch statement that provides handlers for the window messages you want to handle. The following code shows what a typical event handler looks like:

This approach allows you to add messages in the user action component without changing the parent window class, however, it is a step backwards, akin to early C-like Windows SDK development. This approach requires you to perform the tedious task of decoding the WPARAM and LPARAM parameters into useful information. After decoding a few of these parameters, you will wish you could still use the ClassWizard to add new messages.

15.4.2.3 Summary of Existing Approaches

Both approaches are insufficient because they lack support for MFC message maps in the user action components. Given these alternatives, the if-statement approach is the most attractive alternative even if it entails copying and pasting code from one window class to another to provide the same functionality for different views or windows.

Using plug-in components lets you override WindowProc() and forward all windows messages to a user action component that fully supports MFC message maps. ClassWizard lets you add message handlers, as with any other MFC window class.

15.4.3 The Plug-in Approach

Before demonstrating how to implement the plug-in approach, let us describe the requirements for this approach and show how to encapsulate the solution in one common base class for plug-in components.

Here are the requirements for the plug-in approach:

  1. Determine one point of entry for searching the MFC message map and dispatching any window messages to the correct message handler in a derived class.

  2. Ensure that source code for user actions in existing window classes can be reused without making major changes.

  3. Avoid redundant calls to the default window procedure. Only the parent window object should call this method.

Here is a more detailed discussion for each of these requirements and its solutions:

15.4.3.1 Message Dispatching

MFC message dispatching is implemented by CWnd's OnWndMsg() member function. OnWndMsg() searches the window's message map and calls the correct message handler in a derived class. One interesting feature of OnWndMsg() is that it correctly dispatches messages whether or not a valid windows handle is attached to the CWnd object. OnWndMsg() is completely independent of the CWnd's m_hWnd attribute. It works correctly even if you never called CWnd::Create().

Armed with this knowledge, we could derive the plug-in component base class from CWnd that does not need to be attached to a windows handle and provides an entry point for each window message. The entry point for window messages is the plug-in component's HandleMessage() method.

The following code shows how HandleMessage() is implemented. The method calls the protected CWnd::OnWndMsg() member, which then searches the message map and calls the correct message handler. The meaning of the attributes m_bExitMesssage and m_bSkipOtherPlugins is discussed later in this article.

The next code snippet shows how messages are forwarded from the parent window class to the plug-in component. m_pPlugin is a pointer to a plug-in component object.

15.4.3.2 Reuse of Existing Code

CWnd is a thin wrapper class for a window handle and provides many member functions that rely on the m_hWnd attribute. For example, CWnd::Invalidate() is a wrapper to the equivalent Windows SDK method and passes m_hWnd as the window handle. The member function is declared as an inline method in afxwin.inl using the following code:

Many other CWnd member functions are implemented in exactly the same way. If you port existing code to a plug-in component and call a CWnd member function, your application asserts because m_hWnd is not a valid window handle. To solve this problem, we need to provide a valid windows handle for the plug-in component's m_hWnd attribute.

Consider the following two issues:

  1. CWnd::OnWndMsg disregards the value of the m_hWnd attribute, so we can assign any value to it.

  2. A plug-in component is not a real window object. The plug-in component should operate directly on the parent window object. It receives the same messages that the parent window object receives and any window operations that are executed in the plug-in component need to affect the parent window.

Assigning the parent's window handle to the plug-in component's m_hWnd attribute is the ideal solution. Using the parent's window handle lets you port existing code to a plug-in component without changing any existing calls to CWnd member functions. All CWnd member functions now operate directly on the parent window.

If you are an experienced MFC developer, you may question the legality of assigning the same windows handle to different CWnd objects. In the case of CWnd::Attach(), you cannot assign the same windows handle to different CWnd objects. If you attempt to do this, MFC will assert. Internally, MFC only allows one window object for each window handle. The window handles and CWnd objects are maintained in the window handle map. However, the Plug-In Approach does not require us to call CWnd::Attach(). Instead, we only assign the windows handle to m_hWnd, which is safe. However, you should be aware that whenever you call CWnd::FromHandle(m_hWnd), MFC returns a pointer to the parent CWnd object, because this is the window that is registered in the MFC window handle map.

15.4.3.3 Default Window Procedure

As mentioned earlier, another requirement is to avoid redundant calls to the default window procedure of the parent window. The solution to this problem is to override the virtual DefWindowProc() method for the plug-in component class and return immediately, as shown in the following code snippet below. Then, only the parent window is calling the default window procedure.

15.4.4 The CGXPluginComponent Class

The CGXPluginComponent class is the base class for plug-in components.

Here is a short overview on member functions and attributes.

15.4.5 Implementing a Sample Plug-in Component

To show you how easy it is to use the plug-in approach, this section documents the development steps for implementing a sample auto-scroll component. The auto-scroll component checks if the user presses the left mouse button. In response to this event, a timer is started and WM_VSCROLL messages are sent to the parent window. When the user moves the mouse up or down, the parent window scrolls into the given direction. Once the user releases the mouse button, the timer is killed and the auto-scroll operation ends. Other events such as the WM_CANCELMODE message or when the user presses the ESC key stop the operation. The component can easily be reused and attached to any view or window class without changing its source code.

The major steps for implementing the sample component are:

  1. Create a small MFC application with AppWizard using CView as the main window's base class. For instance, create a class called CMyView.

  2. Derive a class called CAutoScrollPlugin from the CGXPluginComponent class, where you add the functionality that should be encapsulated in the plug-in component.

  3. In the CMyView class, override WindowProc() and then call the OnWndMsg() method of the plug-in component. To do this, call CGXPluginComponent::PlugIn(this) in your CMyView::OnInitialUpdate()override.

Here is a more detailed explanation:

  1. When you create the project using the MFC AppWizard, please derive the view class from CScrollView. We recommend you name the view class CMyView. After you generate the project, enlarge the scroll range specified in OnInitialUpdate(). For example:

  2. Next, create the CAutoScrollPlugin class. Use ClassWizard to derive a class from a generic CWnd and name it CAutoScrollPlugin. After you generate the class, you can derive it from CGXPluginComponent. To do this, edit the header and implementation file and replace all occurrences of CWnd with CGXPluginComponent. If you remove the existing ClassWizard (.clw) file from the project directory and press <CTRL>+W, the ClassWizard file is regenerated. You can then add message handlers to the CAutoScrollPlugin class with ClassWizard.

    The following listing shows the final implementation of the CAutoScrollPlugin component.

  3. The next step is to add a pointer to the plug-in object in your view class. To do this, add this code to the class declaration:

    In myview.cpp, instantiate the auto-scroll component and call its Plugin() method in the OnInitialUpdate() routine:

    Don't forget to include the header file for the CAutoScrollPlugin class in myview.cpp!

  4. Finally, override WindowProc() and call the HandleMessage() method of the plug-in component.

    The following listing shows the implementation of the CMyView class:

15.4.6 Using the IntelliMouse Plug-in Component

A real world example for using this plug-in approach is the convenient and reusable CGXIntelliMousePlugin component that can be attached to any CWnd or CView class. The component provides support for IntelliMouse scrolling, zooming and panning. No code change is necessary in the component source code to use its functionality with different window and view classes.

Here is a short overview of the functionality implemented with the component. The implementation is very similar to MS Excel and Internet Explorer 4.0. The following features are provided:

The CGXIntelliMousePlugin class integrates into any advanced view that may itself process many window messages.

15.4.6.1 Using the IntelliMouse Component with any View or Window

Check out the ogmouse sample (samples\grid\plugin\ogmouse) to see how easy it is to add IntelliMouse support to any existing view. All you have to do is follow these steps from the previous section:

  1. Add a pointer to the plug-in object in your view class. Allocate a CGXIntelliMousePlugin object and call CGXPluginComponent::Plugin() at initialization time.

  2. Override WindowProc() and call the HandleMessage() method of the plug-in component.

15.4.6.2 Using the IntelliMouse Component with CGXGridCore

With CGXGridCore, using IntelliMouse support is even easier. CGXGridCore already provides internally the necessary dispatching of messages in the WindowProc() method. All you need to do is register the IntelliMouse component. To do this, simply call EnableIntelliMouse(); at initialization time of your grid (for example in OnInitialUpdate().)

EnableIntelliMouse() calls CGXGridCore::AddPlugin(). CGXGridCore::AddPlugin() registers the plug-in component within the grid. This registration is necessary to let the grid know that it should dispatch WindowProc() events to this component. When the grid goes out of scope, the plug-in object will be automatically destroyed.

Check out the GridApp sample for using IntelliMouse within a grid.



Previous fileTop of DocumentContentsNo linkNext file

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and Stingray, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.