Chapter 11

Step-by-Step Through the NPP Methods

CONTENTS

• Starting the Plug-In
• Handling the Interaction
• In the SDK…

This chapter provides a detailed description of the elements of the Navigator plug-in Software Development Kit (SDK), emphasizing the hooks to these elements (NPP methods) that need to be written by you, the programmer.

This chapter begins at the point where Navigator installs and inventories its plug-ins. It then proceeds through the point where Navigator loads the plug-in and makes a series of calls to it. This chapter then demonstrates how the plug-in displays its data and interacts with the user. The chapter concludes by showing the sequence the plug-in should use to destroy its instance and shut itself down.

Starting the Plug-In

When Navigator launches, it looks in the plug-ins directory-the exact name and location depends upon the platform, but in general the directory is named "plug-ins" and is in the same directory as Navigator itself. In the case of the Windows version of Navigator, plug-ins must also begin with the letters np in their file name. When Navigator starts up, it examines each file in the plug-ins directory. If the file is a plug-in, it checks the file to see what MIME types the plug-in handles. (The exact mechanism for associating MIME types with plug-ins depends upon the platform.) During this process, Navigator puts a message on the screen that says it is Loading plug-ins. As programmers, we understand that it is only registering, or installing, the plug-ins. Later, when the plug-in is needed, Navigator will actually load the plug-in into memory.

Launching the Plug-In

When Navigator encounters a request to handle a particular MIME media type, it looks at the list of plug-ins and selects the plug-in that handles this type. If the plug-in is already loaded (by a prior instance of this type), Navigator makes another instance of the plug-in. If Navigator is seeing this media type for the first time, it loads the plug-in code, and then makes the first instance.

This section describes this start-up process in detail.

Advertising a MIME Media Type  Every Navigator plug-in must handle at least one MIME media type and subtype. Netscape's documentation usually abbreviates "MIME media type and subtype" to "MIME type." This section shows how to put the MIME type identifiers into the plug-in. The method is different for each supported platform.

The MIME media type is specified in a Windows plug-in in the Version Information Resource. The specific resource to change is named VS_VERSION_INFO. You should add three lines to the "StringFileInfo" section of the resource. These new lines resemble this example:

VALUE "MIMEType", "application/x-chapter11\0"
VALUE "FileExtents", "c11\0"
VALUE "FileOpenName", "Chapter 11 Plug-In (*.c11)\0"

To see a specific example of how to set the Version Information Resource, see the section "Modifying the Version Information Resource" in Chapter 13, "Analysis of a Simple Plug-In."

To specify the MIME media type and file extensions in your OS/2 Warp plug-in, modify the RCDATA lines in the makefile. To add the unregistered MIME media type used as this chapter's example, the makefile might include:

#include "npapi.h"
       RCDATA NP_INFO_ProductVersion { 1,0,0,1}
       RCDATA NP_INFO_MIMEType       {"application/x-chapter11\0"}
       RCDATA NP_INFO_FileExtents    {"c11\0"}
       RCDATA NP_INFO_FileOpenName   {"Chapter 11 Sample Plugin\0"}

On a Macintosh, everyfile has a "resource fork" and a "data fork." These "forks" are simply two sections of the file. On some files, the resource fork is empty. In an application, however, the code, the windows templates, the strings, and all the other resources are present in the resource fork.

Before the application is compiled, the resources are stored in a file with the extension .rsrc. Use ResEdit (a resource editor developed by Apple and supplied with most compilers) to open one of the .rsrc files that comes with the Macintosh version of the SDK-choose File, Open from the menu, and use the dialog box to select the file. Figure 11.1 shows the two resources present in ViewText.rsrc.

Figure 11.1: The resource files in the SDK contain a string resource and a version resource.

The resource used by Navigator to identify the MIME media type of a plug-in is the STR# resource, specifically STR# 128. Figure 11.2 shows STR# 128 open in ResEdit.

Figure 11.2: Navigator reads STR# 128 to determine which MIME media types a plug-in handles.

As far as ResEdit is concerned, STR# resources just contain lists of strings. Navigator, however, interprets the strings in STR# 128 as holding the MIME media type and file extensions associated with this plug-in. To specify a MIME media type and set of file extensions for a plug-in, set string 1 of STR# 128 to the MIME media type and string 2 to the file extension.

The X Window System does not have the concept of a "resource" in the same way as Windows, OS/2, and the Macintosh do, so if you are preparing a plug-in for use under UNIX, you need to build the reference to the MIME media type into the program itself. Navigator will call your UNIX program with two new calls: NPP_GetMIMEDescription() and NPP_GetValue(). Use the following code as a model for implementing these two functions:

#ifdef XP_UNIX
char* NPP_GetMIMEDescription()
{
  return ("application/x-chapter11:c11:Chapter 11 Sample Plug-in");
}
#define PLUGIN_NAME "Chapter 11 Sample Plug-in"
#define PLUGIN_DESCRIPTION "Demonstrates how to pass information

to Navigator from a UNIX plug-in"
NPError NPP_GetValue(void* future, NPPVariable theVariable, void* value)
{
  NPError err = NPERR_NO_ERROR;
  if (variable == NPPVpluginNameString)
    *((char**)value) = PLUGIN_NAME;
  else if (variable == NPPVpluginDescriptionString)
    *((char**)value) = PLUGIN_DESCRIPTION;
  else
    err = NPERR_GENERIC_ERROR;
  return err;
}
#endif

Be sure to use the file examples/UnixTemplate/source/UnixShell.c (part of the UNIX SDK) as the model for your UNIX plug-in. Also examine the files in examples/Simple/Source from the same SDK; in particular, look for conditionals based on #ifdef XP_UNIX to see how UNIX plug-ins differ from those built for other operating systems.

Loading the Plug-In  When Navigator is loaded, it goes through the available plug-ins, reading MIME media types. If a user has two or more plug-ins loaded that both handle the same MIME type, Navigator registers the last type it finds.

Navigator finds media types in one of three ways:

• Navigator connects to a server that sends a Content-type header.
• Navigator reads a TYPE attribute in an <EMBED> tag.
• Navigator reads a local file with a file extension that matches the file extension advertised in a plug-in.

If the media type is one that Navigator handles itself (such as text/html or image/gif) Navigator calls its own internal routines. If the media type is not native to Navigator, but there is no plug-in or helper application to handle the type, Navigator displays a dialog box similar to the one shown in Figure 11.3.

Figure 11.3: If Navigator cannot find a plug-in or helper application to handle the media type, it announces that fact to the user.

If Navigator finds a matching plug-in on the list, it next checks to see if the plug-in has already been loaded. If the plug-in has not been loaded, Navigator makes a series of calls to the plug-in. The first of these calls is to methods provided by the SDK. Finally, the standard (cross-platform) initialize function, which is written by the plug-in programmer, is called. This function is named NPP_Initialize().

The Programmer's Start-up Code: NPP_Initialize  What you do in NPP_Initialize() is up to you and is largely determined by the design of your plug-in. The general rule is that all static data members of your classes should be initialized here. If you need to allocate disk files, memory, or other resources that will be shared by all instances of the plug-in, do this work here. If you want to check the platform to ensure that certain minimum resources are present, do it now.

If, for example, your plug-in expects to find an ODBC-compliant database on the platform and all instances will share one connection to the database, NPP_Initialize() is the appropriate place both to ensure that the database exists and to establish the connection.

The specification of NPP_Initialize() is as follows:

NPError NPP_Initialize(void)

The function takes no parameters and returns an error code. If NPP_Initialize() is successful, it should return NPERR_NOERR. If a failure occurs, it should return the appropriate error code (listed in npapi.h). If the plug-in is unsuccessful in allocating memory, for example, it can return NPERR_OUT_OF_MEMORY_ERROR.

After you exit NPP_Initialize(), the next event is the instantiation of your plug-in-the class constructors are called to make an instance of your plug-in. From this point, copies of this plug-in will be instantiated with no further calls to NPP_Initialize().

Instantiating a Copy of the Plug-In  At last, the executable image of the plug-in is loaded into memory, and Navigator and the plug-in know how to talk to each other. Any shared resources, such as class variables or database connections, are set up. The plug-in is ready to open its doors for business.

Recall that more than one copy of a plug-in may be present in memory at the same time. All copies will share the same code and the same class variables. Each instance will have its own instance variable. If the operating system supports preemptive multitasking, each copy may have its own thread of execution.

NPP_New()  To instantiate your plug-in, Navigator calls the plug-in's NPP_New() function. NPP_New()'s specification is as follows:

NPError NPP_New(NPMIMEType *pluginType, NPP instance, uint16 mode, int16 argc, 

char *argn[], char *argv[], NPSavedData *saved);

Recall that a plug-in can "sign up" for more than one MIME media type. The parameter pluginType is a pointer to the type actually specified by the stream or the <EMBED> tag. NPMIMEType is a typecast of a char pointer.

The mode tells the plug-in whether it was called as an embedded or full-page plug-in. Valid values include NP_EMBED and NP_FULL.

The three parameters argc, argn[], and argv[] are used to pass parameters in from the <EMBED> tag. Suppose the HTML writer writes the following:

<EMBED SRC="/path/to/data" HEIGHT=50 WIDTH=150 Zee=True Par=False Loop>

When Navigator calls NPP_New(), it will pass:

• argc=6
• argn={ "SRC", "HEIGHT", "WIDTH", "Zee", "Par", "Loop" }
• argv= { "/path/to/data", "50", "150", "True", "False", ""}

The type NPSavedData is a cast of a two-member structure, as follows:

typedef struct _NPSavedData
{
    int32  len;
    void*  buf;
} NPSavedData;

If you store data in NPSavedData when the plug-in is destroyed, Navigator associates this data with the current URL. If the same URL is requested later, Navigator will attempt to restore your saved data here in NPP_New().

A typical use of NPSavedData is to remember user selections. Another use is to remember how much of a data stream the plug-in displayed. If, for example, the plug-in presents an audio stream, NPSavedData can be used to store an index into the stream. If the user stops the play before the recording is complete, and later loads a page that points to the same audio stream, the plug-in may resume at the point where the previous playback stopped.

Your plug-in should check instance to make sure that it is not null. If Navigator passes a null pointer to your plug-in, the plug-in should return code NPERR_INVALID_INSTANCE_ERROR.

As part of NPP_New(), you probably will want to allocate some memory and build initial instances of your plug-in's classes. Calls to conventional new() or malloc() may fail, even if memory is available, because this memory may be controlled by Navigator and not the plug-in. Use NPN_MemAlloc() to allocate memory on the heap.

One approach to ensure that objects are allocated by using NPN_MemAlloc() is illustrated in the Plug-Ins SDK. Classes that require instance variables are derived from class CNetscapeMemObject. The Netscape programmers define new() and delete() operators as follows:

void* CNetscapeMemObject::operator new(size_t size)
{ 
  return NPN_MemAlloc( size ); 
}
void CNetscapeMemObject::operator delete( void* theThing, size_t size )
{ 
  NPN_MemFree( theThing ); 
}

NPP_NewStream()

After the instance and any standing classes are built, Navigator is ready to deliver the data to the plug-in. To determine how the plug-in prefers to receive the data, Navigator starts by calling NPP_NewStream().

The specification for NPP_NewStream() is as follows:

NPError NPP_NewStream(NPP instance, NPMIMEType type, NPStream *stream, 

NPBool seekable, uint16* stype);

The parameters instance and type have the same meaning they have when used in NPP_New(). Remember that, if you choose, you can read or change any data in instance->pdata.

The type NPStream is a cast of a structure, as follows:

typedef struct _NPStream
{
 void*   pdata;     /* plug-in private data */
 void*   ndata;     /* netscape private data */
 const char*  url;
 uint32  end;
 uint32  lastmodified;
 void*   notifyData;
} NPStream;

The members pdata and ndata have the same meaning they have in type NPP. You may store stream-specific data in pdata; you should leave ndata alone because it is private to Navigator.

The member url has the obvious meaning. The member end is the length of the stream, in bytes. If Navigator cannot determine the length of the stream, end is set to zero. This condition occurs if the server doesn't send a Content-length header, as, for example, if the output is being generated on-the-fly from a LiveWire application or CGI script.

The lastModified parameter should be interpreted as the date-time stamp of the stream, expressed in the number of seconds after midnight, January 1, 1970 (a date and time known as the UNIX epoch).

The function parameter stype is set, by default, to NP_NORMAL. If your plug-in leaves this parameter at NP_NORMAL, Navigator sends the data to the plug-in by using a series of NPP_WriteReady() and NPP_Write() calls, as described in the next section, "Reading the Data as a Stream." You can change stype to NP_ASFILEONLY, which tells Navigator to save the entire stream into a file in its disk cache, then return the path name of this file (in NPP_StreamAsFile()). This technique is described later in this chapter in "Reading the Data as a File."

If the parameter seekable is true, the plug-in can set stype to NP_SEEK. The parameter seekable is true if the stream is a local disk file, or is coming from a server that supports byterange requests. If seekable is false, the plug-in can still use NP_SEEK, but Navigator is forced to read the entire file from the server to a local file in the cache.

You will find how to transfer data by using NP_SEEK mode in a later section, "Calling for the Data in a Seekable Stream."

Reading the Data as a Stream  If the plug-in sets stype to NP_NORMAL in NPP_NewStream(), Navigator next calls NPP_WriteReady() to determine how many bytes to send to the plug-in. Typically, you would allocate a buffer in NPP_NewStream() and store a pointer to that buffer somewhere in the structure maintained under stream->pdata. On each call to NPP_WriteReady(), the plug-in would just return the capacity remaining in the buffer.

The specification for NPP_WriteReady() is as follows:

int32 NPP_WriteReady(NPP instance, NPStream *stream);

After calling NPP_WriteReady(), Navigator calls NPP_Write(), in which it sends a buffer full of data. The buffer may be larger than the amount specified in the plug-in's return to NPP_WriteReady(). If so, the plug-in is obligated only to accept the amount it advertised in NPP_WriteReady(). It should copy that much data out of Netscape's buffer and into its own (or simply consume the data directly from Netscape's buffer), and then return the amount actually consumed as the return value of NPP_Write(). The specification for NPP_Write() is as follows:

int32 NPP_Write(NPP instance, NPStream *stream, int32 offset, 

int32 len, void *buf);

The parameter offset is used to show where in the stream the current buffer fits. Offset zero is at the beginning of the stream. The parameter len indicates the length of the actual buffer.

If an error occurs while processing the stream, return a negative value from NPP_Write(). Navigator interprets this value as a request to destroy the stream, and calls the plug-in's own NPP_DestroyStream().

Reading the Data as a File  If the plug-in set NPP_NewStream()'s stype parameter to NP_ASFILEONLY, Navigator calls the plug-in's NPP_StreamAsFile() function. NPP_StreamAsFile()'s specification is:

void NPP_StreamAsFile(NPP instance, NPStream *stream, const char* fname);

Parameters instance and stream have the same meaning they have in other NPP_ functions. The parameter fname is the path to the file, either in the cache or elsewhere on the local disk. Use this path name to perform I/O on the file by using the functions of the native operating system.

Calling for the Data in a Seekable Stream  If you specify NP_SEEK as the stype mode in NPP_NewStream(), Navigator waits for your plug-in to request data. Call for the data by using the NPN_RequestRead() function:

NPError NPN_RequestRead((NPStream *stream, NPByteRange *rangeList);

An NPByteRange is a structure for accessing specific bytes in the stream. The structure is given by the following:

typedef struct _NPByteRange
{
    int32       offset;         /* negative offset means from the end */
    uint32      length;
    struct _NPByteRange* next;
} NPByteRange;

Note that the structure contains a pointer to other such structures. You can use this field to make an NPByteRange into a linked list, stringing NPByteRange structures together to request a series of non-contiguous byte ranges.

NPN_RequestRead() is the first NPN_ function we have seen. Recall that NPN_ functions are calls made by the plug-in back to Navigator. You find more information on NPN_RequestRead() and also the other NPN_ functions in Chapter 12, "Calling Navigator with NPN Methods."

Presenting the Data

Unless the plug-in is called as a background plug-in, Navigator will call NPP_SetWindow() to pass the plug-in a pointer to the plug-in's window. NPP_SetWindow() is specified by the following, where the exact nature of an NPWindow depends upon the platform:

NPError NPP_SetWindow(NPP instance, NPWindow *window);

On a Windows or UNIX machine (running the X-Window System), windows form a hier-archy. As shown in Figure 11.4, the window "owned" by Navigator can have subwindows. NPP_SetWindow() passes a handle to one of these subwindows to the plug-in. On Windows and UNIX platforms, these subwindows are native windows objects.

Figure 11.4: On Windows and X-Window UNIX machines, windows form a parent-child hierarchy.

On a Macintosh, Navigator runs in a native window, but doesn't spawn a child window to pass to the plug-in. Rather, Navigator constructs a native Macintosh drawing area, known as a GrafPort, and passes a pointer to the GrafPort in a structure Navigator calls NPPort.

An NPWindow is defined by the cross-platform structure, as follows:

typedef struct _NPWindow
{
    void*       window;     /* Platform specific window handle */
    uint32      x;          /* Position of top left corner relative */
    uint32      y;          /*   to a netscape page. */
    uint32      width;      /* Maximum window size */
    uint32      height;
    NPRect      clipRect;   /* Clipping rectangle in port coordinates */
                            /* Used by Mac only. */
#ifdef XP_UNIX
    void *      ws_info;        /* Platform-dependent additional data */
#endif /* XP_UNIX */
} NPWindow;

Using Macintosh GrafPorts  On the Macintosh, window points to an NPPort. The NPPort is defined by the following:

typedef struct NP_Port
{
    CGrafPtr    port;           /* GrafPort */
    int32       portx;          /* position inside the topmost window */
    int32       porty;
} NP_Port;

When operating on a Macintosh, use the coordinates of the clipRect to limit drawing. In this way, if the user scrolls an embedded plug-in window to the edge of the screen, the plug-in will not overwrite the scroll bar or the menus. The Macintosh Toolbox call ClipRect() changes the clipping rectangle of the current GrafPort. This function takes a pointer to a rect as its parameter, and interprets the rect as a clipping rectangle in local coordinates.

Programming on UNIX in the X Window System  Note that the UNIX version of NPWindow contains an additional member: ws_info, which points to an NPSetWindowCallbackStruct allocated by Navigator. The structure's members, given in the following structure, are the standard pieces of information any program needs to know about a window in the X Window System.

typedef struct
{
    int32               type;
    Display*            display;
    Visual*             visual;
    Colormap            colormap;
    unsigned int        depth;
} NPSetWindowCallbackStruct;

What to Do in NPP_SetWindow()  Whether you are building a plug-in for a Windows computer, a Macintosh, or a UNIX machine, the most important step to take each time NPP_SetWindows() is called is to draw a representation of the data. Experiment with an instrumented version of the plug-in, such as npZero.dll (introduced in Chapter 13, "Analysis of a Simple Plug-In"), to see when Navigator calls NPP_SetWindow(). You will find that NPP_SetWindow() is called when the window is resized, and may be called when the window is moved. You also may find that occasionally NPP_SetWindow() seems to be called for no reason. (Netscape is aware of this problem, but this behavior really doesn't hurt anything.) Your copy of the NPWindow pointer remains valid until the next time NPP_SetWindow() is called-you may want to store it in the instance so that you can compare the old window with the new one to see if NPP_SetWindow() was called unnecessarily.

Note, too, that if the HTML programmer specified your plug-in as hidden, you will never get an NPP_SetWindow() call. In this case, your plug-in should be prepared to initiate its task of presenting the data as soon as the data becomes available, and not wait for a window.

Handling the Interaction

In many cases, the programmer wants to interact with the user as long as the plug-in is active. The programmer may put up buttons, sliders, or pop-up menus in the plug-in's window. This section shows how to capture user events and make them available in the plug-in.

Once You Have the Keyboard Focus

The HTML page has loaded. Navigator, seeing an <EMBED> tag, is retrieving data from the Web server and has loaded your plug-in. Your plug-in is receiving data and has displayed that data in its assigned window. For many plug-ins, the day is over-their work is done.

For more sophisticated plug-ins, however, tasks still await. You have included user controls in your window, and you must wait while the user clicks your buttons or types in your text fields. In short, you are waiting for an event.

Getting Events  The major platforms supported by Navigator (OS/2 Warp, Windows, Macintosh, and UNIX) each have different mechanisms for notifying a program of a user action.

Each operating system provides a way for the programmer to register an interest in certain external events so that the application is notified by the operating system when these events occur.

All Windows messages have four parameters, regardless of where they come from or what they are telling your program:

• A window handle (an unsigned 16-bit integer named HWND)
• A message type (an unsigned 32-bit integer)
• An unsigned 32-bit integer to pass message-specific information
• A signed 32-bit parameter to pass message-specific information

The most common message types are Windows messages. In your documentation, all of these messages begin with the characters, WM_.

Remember that Netscape's call to NPP_SetWindow() passes a native window handle to the Windows plug-in. The operating system is prepared to dispatch events associated with this window to the plug-in. The plug-in just has to ask for them.

LONG theResult = -1;
switch(Message)
{
  case WM_PALLETTECHANGED:
  {
    ...
    break;
  }
  case WM_PAINT:
  {
    ...
    break;
  }
  default:
  {
    // this message was not for us; call old Window process
    ...
    break;
  }
}
return theResult;

If the WM_PALLETTECHANGED message or the WM_PAINT message ever reaches the plug-in, the plug-in now knows how to handle it. The question is, "How does the plug-in tell Windows that it wants these messages?"

The answer is a callback function. Every window in the Windows operating system has a list of functions known as WindowProc functions attached to it. A typical callback function contains the message-handling code just described.

Note that in the message-handling code fragment, the handler for default case is missing. Windows expects a WindowProc to maintain a pointer to any WindowProc it replaces so that if the new WindowProc cannot handle a message, it can forward it to its predecessor.

Windows makes it easy to reserve space for these pointers in their function, RegisterClass. Unfortunately, Navigator doesn't request this extra space, so plug-ins for Navigator 3.0 on Windows also must maintain a linked list. The code to implement this list is given in the nspi30 SDK (which is available online at http://home.netscape.com/eng/mozilla/3.0/handbook/plugins/index.html).

Figure 11.5 illustrates the process by which Windows dispatches messages.

Figure 11.5: Windows sends the message to the window's most recently attached callback function and expects the callback function to call its predecessor.

To install a new callback function, use the SetWindowLong() function, which you can use to change many different parameters of the window. For example, if This is a pointer to the current data structure that you stored in pData, you can put the following code in your implementation of NPP_SetWindow():

This->hWnd = (HWND)(DWORD)This->fWindow->window;
This->lpfnOldWndProc = 
  (FARPROC) SetWindowLong(This->hWnd,
                          GWL_WNDPROC,
                          (DWORD)myCallbackFunction);
AssociateInstance(This->hWnd, This);

When NPP_SetWindow() is called, this code sets the WindowProc of the window identified by hWnd to the callback function myCallbackFunction. Then it links the old WindowProc, carefully saved in This-> lpfnOldWndProc, by calling AssociateInstance().

When a message is sent to the window identified by hWnd, the callback function is invoked. If the message is on the list of messages handled by the switch statement, the appropriate action is taken and the function returns zero. Otherwise, the default case is taken and the old WindowProc tries to handle the message.

LONG_NP_LOADDS WINAPI myCallbackFunction ( HWND hWnd,
                                           WORD Message,
                                           WORD wParam,
                                           LONG lParam)
{
  PluginInstance* This = GetInstance(hWnd);
  LONG theResult = -1;
  switch(Message)
  {
    case WM_PALLETTECHANGED:
    {
      ...
      break;
    }
    case WM_PAINT:
    {
      ...
      break;
    }
    default:
    {
      // this message was not for us; call old Window process
      theResult = CallWindowProc(This->lpfnOldWndProc,
                                 hWnd,
                                 Message,
                                 wParam,
                                 lParam);
      break;
    }
  }
return theResult;
}

Look in the Microsoft-supplied file winuser.h to see the list of windows messages (WM_s) available. Which messages should your plug-in handle? You should certainly handle WM_PAINT. This message is sent whenever the window needs to be redrawn. It is sent once as the plug-in is starting, and then again whenever one of the following events occurs:

• A window needs resizing
• A portion of the window that was previously obscured becomes visible
• The contents of the window are scrolled
• The application invalidates the window by calling InvalidateRect() or InvalidateRgn()

Some of these events, like resizing, trigger NPP_SetWindow(), but play it safe and handle WM_PAINT directly.

You also may want to handle WM_PALETTECHANGED. This message is sent by Windows when a new window gets the keyboard focus. When the focus changes, the window with the focus sets its logical palette, which changes the system palette. The operating system sends WM_PALETTECHANGED to all visible windows, which gives them a chance to set their own logical palette.

You should recall from the section "Starting the Plug-In," earlier in the chapter, Windows and UNIX plug-ins get a native window, but Macintosh plug-ins get a GrafPort. One consequence of this implementation is that the plug-in sees all events, although it may handle very few. Otherwise, the practical effect of this difference is small.

When an event occurs, Netscape calls NPP_HandleEvent(). This function has the specification:

int16 NPP_HandleEvent(NPP instance, void *event);

The second parameter is a pointer to a standard Macintosh EventRecord. Macintosh events are like Windows messages. Event types include the following:

• Mouse events: sent if the mouse is within the bounds of the instance
• Key events: sent if the instance has text focus
• Update events: sent if the instance needs to be redrawn
• Activate events: sent to all instances in the window being activated or deactivated
• Suspend/Resume events: sent to all instances in all windows
• Null events: sent to all instances in all windows

In addition to the usual Macintosh events, Navigator adds three custom events:

• getFocusEvent: the user has moved the keyboard focus onto the instance by clicking it or tabbing into it. All keystrokes entered now may reasonably be expected to be handled by the plug-in. Return TRUE if your plug-in handles keyboard events and FALSE if it does not.
• loseFocusEvent: the user has moved the keyboard focus away from the instance. Your plug-in no longer receives keyboard events. When you receive a loseFocusEvent, you can validate any data the user entered or do any other processing that may be appropriate for your plug-in.
• adjustCursorEvent: the user has moved the mouse across the boundary of your plug-in. To give the cursor a special appearance while it is over your plug-in (for example, if the cursor should turn into an I-beam because the user may enter text), maintain the cursor state in your plug-in and toggle the cursor appearance when this event comes along.

If your plug-in does something special with the cursor when the mouse enters its rectangle, return TRUE in response to this event. Otherwise, return FALSE.

You can read the event type from the event->what field. Generally, your implementation of NPP_HandleEvent() should return TRUE if your plug-in handles the event and FALSE if it does not.

Typical code to implement NPP_HandleEvent() might include the following lines:

Bool theResult = FALSE;
switch (theEvent.what)
{
  case mouseDown:
  {
    Handle_Mouse_Down( &theEvent );
    theResult = TRUE;
    break;
  }
  case updateEvt:
  {
    BeginUpdate( window );
    EraseRgn( window->visRgn );
    Update( window );
    EndUpdate( window );
    theResult = TRUE;
    break;
  }
}
return theResult;

Which Macintosh events should your application handle? The updateEvt is analogous to the Windows message WM_PAINT, and should be handled in a similar fashion. Handle other events as needed by your plug-in.

The event model in the X Window System is similar to the one used by Windows and the Macintosh. You can still think in terms of the server sending events to the client to tell the client that its window needs to be updated. (X calls this event Expose.)

Your plug-in should certainly handle Expose, just as the Windows plug-in handles WM_PAINT and the Macintosh plug-in handles updateEvt. Recall that X widgets are implemented as windows in their own right-don't forget to forward events received by your plug-in to any off-the-Net or commercial widgets your plug-in uses.

Reading the Keyboard Events in Windows  Microsoft Windows, the X Window System, and the Macintosh OS each generate a variety of events or messages associated with the keyboard. This section shows how to capture simple key-down messages in a Windows plug-in.

Recall that Windows messages are handled by a WindowProc function. Your window's WindowProc gets no keyboard messages, however, unless you assign it the keyboard focus.

To give your plug-in window the keyboard focus, call SetFocus(), passing it the HWND to your window. A good place to add this line is at the bottom of your NPP_SetWindow() implementation so that your window is given the focus when it is first instantiated, as well as after any resizing or repainting.

Here's a fragment of the revised NPP_SetWindow():

NPError NP_LOADDS NPP_SetWindow(NPP instance, NPWindow* window)
{
  ...
  This->hWnd = (HWND)(DWORD)This->fWindow->window;
  ...
  // give our plug-in keyboard focus
  SetFocus (This->hWnd);
  return NPERR_NO_ERROR;
}

Next, add code to the window's callback function to handle the keyboard messages. Here's a portion of a WindowProc function to handle the Windows message WM_KEYDOWN:

LONG NP_LOADDS WINAPI SubClassFunc( HWND hWnd,
                                    WORD Message,
                                    WORD wParam,
                                    LONG lParam)
{
  PluginInstance* This = GetInstance(hWnd);
  int nVirtKey;
  LONG lKeyData; // not used in this example
  char buffer[2];
  switch (Message)
  {
  ...
  case WM_KEYDOWN:
  {
    // Windows uses "virtual keys" to accommodate non-Roman character sets.
    // Unicode is at the heart of Window's future.
    // When the message is WM_KEYDOWN, wParam holds the virtual key
    // and lParam holds extension information about the keypress
    nvirtKey = (int) wParam;
    lKeyData = lParam;

    // put the incoming character into a string
    buffer[0] = (char) nvirtKey;
    buffer[1] = NULL;

    // append the string into the instance's persistent buffer
    strcat(This->fBuffer, buffer);

    // trigger a repainting of the window
    InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
    break;
  }
  ...
  case WM_PAINT
  {
    PAINTSTRUCT paint;
    HDC hDC = BeginPaint(hWnd, &paint);
    TextOut(hDC, 0, 0, This->fBuffer, strlen(This->fBuffer));
    EndPaint(hWnd, &paint);
    break;
  }
...
}

Note that this code collects the keystrokes in a structure named fBuffer, which is a member of This. This is a pointer to an instance of class PluginInstance. Add fBuffer to class PluginInstance by adding the line shown in bold.

typedef struct _PluginInstance
{
  NPWindow*     fWindow;
  HWND          hWnd;
  uint16        fMode;
#ifdef STRICT
  WNDPROC       lpfnOldWndProc;
#else
  FARPROC       lpfnOldWndProc;
#endif
  NPSavedData*  pSavedInstanceData;
  char          fBuffer[80];
  PluginInstance* pNext;
} PluginInstance;