Chapter 15

Miscellanceous Methods

CONTENTS

• Introduction
• Your Plug-In's Window
  • Subclassing a Window
  • Getting Instance Data
  • Subclassing with MFC
• Printing and Your Plug-In
• The Macintosh and Window Events
• API Quick Reference
  • NPP_SetWindow
  • NPP_Print
  • NPP_HandleEvent
• Conclusion
• What's Next?

Introduction

Your plug-in's window is created by the Netscape browser. To receive window events in the Microsoft Windows environment, you must subclass the plug-in window using the Windows API SetWindowLong method or the Microsoft Foundation Class Library SubclassWindow method. The Macintosh does not provide for window subclassing and must use the plug-in method NPP_HandleEvent to get window events.

Printing is handled jointly by your plug-in and the browser in the case of an embedded plug-in. For full-page plug-in types, printing is solely up to the plug-in.

The following APIs are covered in this chapter:

NPP_SetWindow
NPP_Print
NPP_HandleEvent

Your Plug-In's Window

If your plug-in is of type NP_EMBED or NP_FULL, the Navigator creates a window on its behalf. The size of the window depends on the type. An embedded window's size is specified in the HTML code, as in the following example:

<embed SRC=sound.wav WIDTH=400 HEIGHT=60>

This code causes the browser to create a window of width 400 and height 60. A NP_FULL type plug-in refers to a full Navigator page. Full page plug-ins fill the whole page display area of the browser. Regardless of the size, it is the browser that creates the window, not your plug-in. This creates some special challenges to the plug-in developer.

Because the plug-in does not create the window, it needs a way to receive events from any user actions relating to the window. In the world of Microsoft Windows, this is accomplished through subclassing the window. Macintosh plug-ins receive events through a Macintosh-specific API called NPP_HandleEvent.

Subclassing a Window

In Microsoft Windows, every window has a class associated with it. This class is defined by a WNDCLASS structure and a call to RegisterClass. Within this structure is an address of the window procedure that is called for windows of this class. This window procedure is called whenever a message for the window needs to be processed.

A plug-in is contained in a Windows DLL. This DLL is loaded and called by the Netscape Navigator and becomes part of the Navigator's process. Being part of this process allows the plug-in and browser to easily share system resources such as memory and files. In addition, being in the same process space allows a plug-in to subclass a window procedure that is in the Navigator's code. Through a series of APIs, the plug-in can instruct Windows to call a window procedure within the plug-in's code before it calls the window procedure in the browser's code. The new window procedure is hooked in as shown in Figure 15.1.

Figure 15.1 : A plug-in's window procedure subclassing the Navigator created plug-in window.

Immediately after Netscape Navigator creates a window for your plug-in, it calls the NPP_SetWindow API. This API passes a window handle for the newly created window. If you are not using Microsoft's Foundation Class Library (MFC), you must subclass Netscape's window with the SetWindowLong API. This function replaces the window procedure with one inside your plug-in DLL. You can call it like this:

instance->lpfnOldWndProc = (FARPROC)SetWindowLong (hWnd,
    GWL_WNDPROC,
    (DWORD)SubclassFunc);

In this example, SetWindowLong replaces the window procedure for the window specified by hWnd with the new procedure SubclassFunc. Note the saving of the old window procedure within lpfnOldWndProc, which is returned by SetWindowLong. The new procedure located within your DLL's code would be structured something like this:

LONG NP_LOADDS WINAPI SubClassFunc (HWND hWnd,
    WORD Message,
    WORD wParam,
    LONG lParam)
{
    PluginInstance* instance = GetInstance(hWnd);

    switch (Message)
    {
    case:
        //
        // Any message specific code would go in this switch statement.
        //
        break;
    default:
        break;
    }
    return CallWindowProc (instance->lpfnOldWndProc,
        hWnd,
        Message,
        wParam,
        lParam);
}

At the end of SubClassFunc is a call to the Windows API CallWindowProc. As you might have guessed, this API calls the old window procedure, located in the Navigator, with the saved procedure pointer instance->lpfnOldWndProc.

When your plug-in's instance is being destroyed, you should remove the subclass from the window. This is done with the same API, SetWindowLong, and is called as follows:

SetWindowLong (instance->hWnd, GWL_WNDPROC, instance->lpfnOldWndProc);

Here the saved old window procedure is replacing the new one installed previously.

Getting Instance Data

One obstacle with using a subclassed window procedure without MFC is getting your plug-in's instance data. Most Netscape methods provide your plug-in with instance data with a passed parameter of instance. This is a pointer to a structure containing references to both the plug-in's and Netscape's instance data. However, the subclassed window procedure is not called directly from the Navigator. It is called by Windows itself. Windows does not pass a pointer to your instance data.

The most obvious solution is to provide a global reference to your instance data in the DLL's global data. Unfortunately, this won't do the trick, because plug-ins support multiple window instances. A single pointer to an instance is overwritten when the next window is created.

Another potential way is to use extra window bytes allocated with the RegisterClass API. You could have stored a pointer to your instance data within these extra bytes if Netscape had allocated any extra window bytes for a plug-in's use-which it didn't.

The Netscape Way

Netscape provides a technique for retrieving your instance data using a linked list to store pointers to your instance for each plug-in window. The non-MFC example of NPSHELL.CPP (provided on this book's CD-ROM) gives an example of this technique with two routines: AssociateInstance and GetInstance. AssociateInstance is called during the NPP_SetWindow method for any new windows. It associates an instance pointer to a window handle. GetInstance, called during the new window procedure, scans through the linked list until the same window handle is found, and then it returns an instance pointer. You can see a call to GetInstance in the previous example of SubClassFunc.

Another Way

If Netscape's linked list approach causes your head to spin, another way to store window-specific data is by storing it in the window's property list. The SetProp API attaches properties to a window by calling it with a window handle, property string, and pointer to your data. When you need to get your instance data again, simply call GetProp with the window handle and property string. Your instance pointer is returned. Don't forget to call RemoveProp to remove your data when the window is destroyed.

Subclassing with MFC

Microsoft's Foundation Class Library makes subclassing a window much easier. Problems with instance data are gone, because MFC enables you to create a window object with an associated message map. This window object is defined in your code as a child of CWnd. You can store any data you need, including a pointer to the plug-in's instance data within this object. MFC shields you from the complexities of associating data with a particular window.

To use this technique, first create a new window class derived from CWnd in your header file. Here is a very simple example:

class CPluginWindow : public CWnd
{
protected:
    MyInstance*  instance;

public:
    CPluginWindow ();
    ~CPluginWindow ();

    void StoreData (MyData *);

    //{{AFX_MSG( CMainWindow )
    afx_msg void OnPlay();
    afx_msg void OnStop();
    //}}AFX_MSG

    DECLARE_MESSAGE_MAP()
};

Notice the pointer to your instance data: MyInstance* instance. This pointer is set with a call to the method StoreData. A message map is declared with methods OnPlay and OnStop.

When the plug-in method NPP_SetWindow is called for the first time, construct your object CPluginWindow and attach a pointer to your instance data. Remember, constructing a CWnd derived class does not actually create a window. This is important because CPluginWindow will be subclassed to an already existing window:

instance->pWindow = new CPluginWindow ();

Then call the inherited CWnd method SubclassWindow, and give it a handle to the plug-in window create by the Navigator:

instance->pWindow->SubclassWindow ((HWND)window->window);

Finally, save a pointer to your instance data in your new CPluginWindow with a call to StoreData or your equivalent method:

instance->pWindow->StoreData (instance);

MFC handles the rest by calling your appropriate method defined in the message map and, upon completion, returning control to the original Navigator window procedure.

Remember to unsubclass the window during destruction of the window's instance in NPP_Destroy with a call to CWnd's UnsubclassWindow:

instance->pWindow->UnsubclassWindow ();

Printing and Your Plug-In

When a user requests a print action and your plug-in is a visible type and is loaded, a call is made to your plug-in's NPP_Print method. To receive this call, your plug-in must be of type NP_FULL or NP_EMBED.

For plug-ins of type NP_FULL, printing is handled totally by the plug-in code. A NULL pointer is passed to the NPP_Print method for the printInfo parameter. The plug-in is in charge of all printing-related tasks such as displaying the printer dialog, getting the printer, creating the printer device context, scaling data, and so on.

Plug-ins of type NP_EMBED print jointly with the Navigator. An embedded plug-in is, by definition, embedded in another document. The Navigator must print its portion of this document and, in turn, the plug-in prints the embedded portion. A plug-in might opt to print nothing, which simply leaves a space in the printout.

When NPP_Print is called for an embedded plug-in, the API parameter printInfo points to the structure NPPrint. This structure contains the plug-in mode and a union of structures NPFullPrint and NPEmbedPrint:

typedef struct _NPPrint
{
    uint16              mode;       /* NP_FULL or NP_EMBED */
    union
    {
        NPFullPrint     fullPrint;  /* if mode is NP_FULL */
        NPEmbedPrint    embedPrint; /* if mode is NP_EMBED */
    } print;

} NPPrint;

The structure NPEmbedPrint is currently defined as follows:

typedef struct _NPEmbedPrint
{
    NPWindow    window;
    void*       platformPrint;      /* Platform-specific printing info */
} NPEmbedPrint;

In this case, the window structure member is a structure of type NPWindow and the platformPrint structure member is the printer's device context (DC). NPWindow is currently defined as follows:

typedef struct _NPWindow
{
    void*   window;                 /* platform specific window handle */
    uint32  x;                      /* position of top left corner relative
                                       to a netscape page */
    uint32  y;
    uint32  width;                  /* maximum window size */
    uint32  height;
    NPRect  clipRect;               /* clipping rectangle in port coordinates */

} NPWindow;

NPWindow provides a window handle, x/y coordinates for the top left corner of the plug-in window relative to a browser page, window width and height, and a clipping rectangle.

In Microsoft Windows, all window coordinates are in TWIPs. A TWIP is one twentieth of a printer's point. A point is 1/72 of an inch, so a TWIP is 1/1440 of an inch. You must use the appropriate conversions to get back to logical coordinates.

The Macintosh and Window Events

Because of the Macintosh windowing architecture, it is not possible to receive events using subclassing. To provide window events to a Macintosh plug-in, Netscape has included the Mac-specific plug-in method NPP_HandleEvent.

NPP_HandleEvent is passed a pointer to a Macintosh EventRecord structure. The EventRecord.what field can be any of the normal Macintosh event types or a Netscape-specific event. Currently, the following types are used:

getFocusEvent
loseFocusEvent
adjustCursorEvent

getFocusEvent informs your plug-in that it will get key events. If you don't want to get key events, just return a FALSE when passed a getFocusEvent.

The event loseFocusEvent lets a plug-in know that it is no longer in focus.

The adjustCursorEvent event is passed to your plug-in as the mouse moves over your window. You can hide the cursor by returning FALSE.

API Quick Reference

The following sections give in-depth information on the APIs used in this chapter.

NPP_SetWindow

NPP_Print

NPP_HandleEvent

Conclusion

The Macintosh receives window events through calls to the Macintosh-specific plug-in API NPP_HandleEvent. Windows plug-ins get their events by subclassing the plug-in window given a window handle in the plug-in method NPP_SetWindow.

During window event processing, plug-in instance data is easy to retrieve using Microsoft's Foundation Class Library. Without MFC, instance data is more difficult to access and must be done through a linked list or a window's property list.

Printing can be performed solely by the plug-in (which is the case with types of NP_FULL) or in conjunction with the browser (which is the case with an embedded plug-in).

What's Next?

That about wraps up the plug-in API documentation. The next few chapters introduce you to sample plug-in code that uses the plug-in API. All of the samples are included on the book's CD-ROM.

The next chapter explains how the sample code is structured and what samples are provided.