Chapter 4
Drawing and Event Handling

This chapter tells how to determine whether a plug-in is windowed or windowless, how to draw and redraw plug-ins, and how to handle plug-in events.

When it comes to determining the way a plug-in appears in a web page, you (and the web page author) have many options. The content provider who writes the web page determines its display mode: whether the plug-in is embedded, part of a layer, hidden, or displayed in its own separate page. You determine whether a plug-in is windowed or windowless by the way you define the plug-in itself.

• A windowed plug-in is drawn into its own native window (or portion of a native window) on a web page. A windowed plug-in is opaque, hiding the part of the page beneath its display window, and can be invoked in the top HTML layer of a page. This type of plug-in determines when it draws itself.
• A windowless plug-in does not require a native window. It is drawn in a target called a drawable, which corresponds to either the Communicator window or an off-screen bitmap. A drawable can be defined in several ways, depending on the platform. Windowless plug-ins can be opaque or transparent and can be invoked in HTML layers. A windowless plug-in draws itself only in response to a paint message from Communicator.

• The NPWindow Structure
• Drawing Plug-ins
• Windowed Plug-ins
• Windowless Plug-ins

NOTE: Windowless plug-ins are currently not supported on the X Windows platform. §

NOTE: When a plug-in is drawn to a window, the plug-in is responsible for preserving state information and ensuring that the original state is restored. §

The NPWindow Structure

typedef enum {
    NPWindowTypeWindow = 1,
    NPWindowTypeDrawable
} NPWindowType;
typedef struct _NPWindow
{
    void*   window;   /* Platform-specific handle      */
    uint32  x;        /* Position of top-left corner   */
    uint32  y;        /*   relative to a Netscape page */
    uint32  width;    /* Maximum window size           */
    uint32  height;
    NPRect  clipRect; /* Clipping rectangle in port coordinates */
#ifdef XP_UNIX
    void *  ws_info;  /* Platform-dependent additional data     */
#endif /* XP_UNIX */
    NPWindowType  type;   /* Whether this is a window or a drawable */

} NPWindow;

The x and y fields specify the top-left corner of the plug-in relative to the page.

The width and height fields specify the dimensions of the plug-in area. These values should not be modified by the plug-in.

The clipRect field defines the clipping rectangle of the plug-in in a coordinate system where the origin is the top-left corner of the drawable or window. Communicator calls NPP_SetWindow whenever the drawable changes.

The type field indicates the NPWindow type of the target area:

• NPWindowTypeWindow: Windowed plug-in. The window field holds a platform-specific handle to a window (as in Navigator 2.0 and Navigator 3.0).
• NPWindowTypeDrawable: Windowless plug-in. The window field holds a platform-specific handle to a drawable, as follows:

Windows: HDC
Mac OS: pointer to NP_Port structure.

In both cases, the drawable can be an off-screen pixmap.

The plug-in uses these methods to draw plug-ins and to handle events:

Plug-in Methods, called by Communicator:

• NPP_HandleEvent: Deliver a platform-specific event to the instance.
• NPP_Print: Request a platform-specific print operation for the instance.
• NPP_SetWindow: Set the window in which a plug-in draws.

• NPN_ForceRedraw: Force a paint message to a windowless plug-in.
• NPN_InvalidateRect: Invalidate an area in a windowless plug-in before repainting or refreshing.
• NPN_InvalidateRegion: Invalidate a region in a windowless plug-in before repainting or refreshing.

void NPP_Print(NPP instance, NPPrint *printInfo);

The PrintInfo parameter determines the print mode. It is set to either NP_FULL to indicate full-page plug-in printing, or NP_EMBED if this is an embedded plug-in printed as part of the window in which it is embedded.

• An embedded plug-in shares printing with Communicator. The plug-in prints the part of the page it occupies, and Communicator handles the rest of the printing process, including displaying print dialog boxes, getting the printer device context, and, of course, printing the rest of the page.
  
  An embedded plug-in can set the pluginPrinted field in its PrintInfo parameter to false (the default). This is a field of the _NPFullPrint substructure of the NPPrint structure. Communicator displays the necessary print dialog boxes and calls NPP_Print again. This time, PrintInfo->mode should be set to NP_EMBED.
• A full-page plug-in handles the print dialog boxes and printing process as it sees fit. In this case, before Communicator displays any print dialog boxes, NPP_Print is called with PrintInfo->mode equal to NP_FULL. On Mac OS, full-page printing requires that the field PrintInfo contain a standard Mac OS THPrint (see Printing.h).

On MS Windows, note that the coordinates for the window rectangle are in TWIPS format. For this reason, you need to convert the x- and y-coordinates using the Windows API call DPtoLP when you output text.

[Top] [Drawing Plug-ins]

Subsequent calls to NPP_SetWindow for a given instance usually mean that the window has been resized. If either window or window->window is null, the plug-in must not perform any additional graphics operations on the window and should free any associated resources.

NPError NPP_SetWindow(NPP instance, NPWindow *window);

The window parameter is a pointer to the drawing target for the plug-in. For windowless plug-ins, the platform-specific window information specified in window->window is a platform-specific handle to a drawable.

MS Windows and Unix For windowed plug-ins on MS Windows and Unix, the window->window field is a handle to a subwindow of the Netscape window hierarchy. §

Mac OS The window->window field points to an NP_Port structure. §

NPError NPN_GetValue(NPP instance,
                     NPNVariable variable, void *value);

Unix and MS Windows The queried information is returned in the variable parameter. This parameter is valid only for the Unix and MS Windows platforms. For Unix, the values are either the current display (NPNVxDisplay) or the application's context (NPNVxtAppContext). For MS Windows, the value is the native window on which plug-in drawing occurs (NPNVnetscapeWindow). §

You can also use NPN_GetValue to help create a menu or dialog box for a windowless plug-in.

[Top] [Getting Information]

The next section describes event handling in windowed plug-ins.

NOTE: The windowed plug-in was the only plug-in type in Navigator 2.0 and Navigator 3.0. §

On MS Windows and Unix, Communicator creates a child window for each plug-in instance and passes it a window through NPP_SetWindow. On Mac OS, the application uses NPP_SetWindow to dedicate a rectangular part of its graphics port to each instance. On any platform, the browser should be careful not to draw in the plug-in's area, and vice versa. The data structure passed in NPP_SetWindow is an NPWindow object, which contains the coordinates of the instance's area and various platform-specific data.

Typically, Communicator calls NPP_SetWindow after creating the instance so that the plug-in can begin drawing immediately. However, the browser can create invisible instances for which NPP_SetWindow is never called and a window is never created. This happens when plug-ins are invoked with the HTML EMBED tag with the HIDDEN attribute.

Communicator should call NPP_SetWindow again whenever the size or position of the instance changes, passing it the same NPWindow object each time, but with different values.

Communicator can also call NPP_SetWindow multiple times with different values for the window, including null. For example, if a user removes an instance from the page, Communicator should call NPP_SetWindow with a window value of null. This value prevents the instance from drawing further until it is pasted back on the page and NPP_SetWindow is called again with a new value.

• Mac OS
• MS Windows
• Unix

Because the plug-in and Communicator share the same graphics port, they share the responsibility for managing it correctly. Communicator sets up the port for the plug-in before passing the plug-in an update event in two ways:

• Communicator calls SetOrigin(npport->portx, npport->porty). This method makes the instance's upper-left coordinate equal to (0,0).
• Communicator sets the port's clip region to the region of the plug-in currently visible (not scrolled off the page, obscured by floating palettes, or otherwise hidden).

Communicator and the plug-in can both install Drag Manager handlers for the shared port. Because the Drag Manager calls both handlers no matter where the cursor is, Communicator does not show the drag highlight when the cursor is over an instance rectangle. Also, Communicator does nothing when a drop occurs within an instance rectangle. The plug-in can then show the drag highlight and handle drops when they occur within the instance rectangle.

Communicator is also responsible for sending the plug-in all events targeted to an instance, such as mouse clicks when the cursor is within the instance rectangle or suspend and resume events when the application is switched in and out. Events are sent to the plug-in with a call to NPP_HandleEvent; for a complete list of event types, see the reference entry for NPEvent.

[Top] [Windowed Plug-ins]

[Top] [Windowed Plug-ins]

[Top] [Windowed Plug-ins]

MS Windows and Unix

Windowless plug-ins provide the plug-in writer with some significant design possibilities:

• You can place a windowless plug-in within a section; other sections can exist both above and below it. For information about using sections or layers, see Dynamic HTML in Netscape Communicator.
• You can create transparent plug-ins. In this case, Communicator draws the part of the page that exists behind the plug-in. The windowless plug-in draws only the parts of itself that are opaque. This way, the plug-in can draw an irregularly shaped area, such as a figure, or text over the existing background.
• Communicator supports off-screen drawing of plug-ins. This makes it possible to manipulate plug-in contents. For example, a 3D application could use the contents of a plug-in as a texture map.

• Specifying That a Plug-in Is Windowless
• Invalidating the Drawing Area
• Forcing a Paint Message
• Making a Plug-in Opaque
• Making a Plug-in Transparent
• Creating Pop-up Menus and Dialog Boxes
• Event Handling for Windowless Plug-ins

NPError NPN_SetValue(NPP instance,
                     NPPVariable variable, void *value);

To specify that a plug-in is windowless, use NPN_SetValue with NPPVpluginWindowBool as the value of variable and false as the value of value. The plug-in makes this call from its NPP_New method. If a plug-in does not make this call, it is considered a windowed plug-in.

NPN_SetValue
typedef enum {
    ...
    ...
    NPPVpluginWindowBool,
    NPPVpluginTransparentBool
} NPPVariable;
NPError    NPN_SetValue(NPP instance, NPPVariable variable, void *value);

• They invalidate the specified drawing area prior to repainting or refreshing.
• They pass an update event or a paint message to the plug-in.

void NPN_InvalidateRect(NPP instance, NPRect *invalidRect);

void NPN_InvalidateRegion(NPP instance, NPRegion invalidRegion);

Both methods cause the NPP_HandleEvent method to pass an update event or a paint message to the plug-in.

#ifdef XP_MAC
typedef RgnHandle NPRegion;
#elif defined(XP_WIN)
typedef HRGN NPRegion;
#elif defined(XP_UNIX)
typedef Region NPRegion;
#else
typedef void* NPRegion;
#endif /* XP_MAC */

void NPN_InvalidateRect(NPP instance, NPRect *invalidRect);
void NPN_InvalidateRegion(NPP instance, NPRegion invalidRegion);

void NPN_ForceRedraw(NPP instance);

A plug-in must not draw into its drawable unless it receives a paint message. It does not need to call the platform-specific function to begin painting within a window. That is, the plug-in does not call BeginPaint on Windows or BeginUpdate on Mac OS.

MS Windows

A windowless plug-in is transparent by default. To make a transparent plug-in opaque, call NPN_SetValue to set NPPVpluginTransparentBool to false. The plug-in can call this method any time after specifying that it is a windowless plug-in.

[Top] [Windowless Plug-ins]

• plug-in that is smaller than the area specified by the enclosing EMBED or OBJECT tag
• plug-in with nonrectangular boundaries

Windowless plug-ins are transparent by default. If you want to make an opaque windowless plug-in transparent, call the NPN_SetValue method and set NPPVpluginTransparentBool to the value true. The plug-in can call this method any time after specifying that it is a windowless plug-in.

[Top] [Windowless Plug-ins]

A windowless plug-in does not draw in its own native window. Instead, it draws directly in the drawable given to it. This behavior presents a problem if you need to display pop-up menus and modal dialog boxes in a plug-in; a plug-in needs a parent window in order to create windows like these.

To deal with this problem on MS Windows, use NPN_GetValue to find out where the plug-in draws. Use NPNVnetscapeWindow as the value for the variable parameter.

NPError NPN_GetValue(NPP instance,
                     NPNVariable variable, void *value);

In many cases, a plug-in may still have to create its own window (a transparent child window of the Netscape window) to act as the owner window for pop-up menus and modal dialog boxes. You can give this transparent child window its own WindowProc process. The plug-in can use this to deal with WM_COMMAND messages sent to it as a result of tracking the pop-up menu or modal dialog box.

[Top] [Windowless Plug-ins]

int16 NPP_HandleEvent(NPP instance, NPEvent *event);

This code shows the specific data passed through this method for each platform:

#ifdef XP_MAC
typedef EventRecord NPEvent;
#elif defined(XP_WIN)
typedef struct _NPEvent {
    int16    event;
    int16    wParam;
    int32    lParam;
} NPEvent;
#elif defined(XP_UNIX)
typedef XEvent NPEvent;
#else
typedef void NPEvent;
#endif /* XP_MAC */

int16 NPP_HandleEvent(NPP instance, NPEvent* event);

[Top] [Windowless Plug-ins]

Last Updated: 01/15/97 16:36:49