NPAPI:Models

Status

Accepted.

Problem Summary

In order to allow revised event and drawing APIs, NPAPI now includes the concept of event and drawing models. Plugins can negotiate with browsers to select an event and a drawing model on a per instance basis.

Specification

NPAPI Event and Drawing Models

• Last modified: April 22, 2010
• Authors: Anders Carlsson (Apple), Josh Aas (Mozilla Corporation), Tim Omernick (Apple)
• Contributors:

Browsers should include support for variables that allow the plugin to query for event and drawing model support via NPN_GetValue. Variables for model support should be named based on the following examples:

• Mac OS X Cocoa event model: NPNVsupportsCocoaBool
• Mac OS X Core Graphics drawing model: NPNVsupportsCoreGraphicsBool

There will be platform-specific default event and drawing models, which may not have a named designation for legacy reasons. When there is no designation, plugins can assume support for the default model exists. If there is a designation, plugins should not assume support for any model, even the default model.

Plugins may select their drawing and event models from those that the browser supports on a per-instance basis during NPP_New. Changing models outside of NPP_New is not allowed. Event and drawing models are selected by calling NPN_SetValue and setting the NPPVpluginEventModel and NPPVpluginDrawingModel variables to the desired values, where the values are NPEventModel and NPDrawingModel enum values, respectively.

An example of drawing model negotiation, in which the plugin requires the Core Graphics drawing model:

static NPError NPP_New(NPMIMEType pluginType, NPP instance,
                       uint16 mode, int16 argc, char* argn[],
                       char* argv[], NPSavedData* saved)
{
    // Check if the browser supports the CoreGraphics drawing model
    NPBool supportsCoreGraphics = FALSE;
    NPError err = browser->getvalue(instance,
                                    NPNVsupportsCoreGraphicsBool,
                                    &supportsCoreGraphics);
    if (err != NPERR_NO_ERROR || !supportsCoreGraphics)
        return NPERR_INCOMPATIBLE_VERSION_ERROR;

    // Set the drawing model
    err = browser->setvalue(instance,
                            NPPVpluginDrawingModel,
                            (void*)NPDrawingModelCoreGraphics);
    if (err != NPERR_NO_ERROR)
        return NPERR_INCOMPATIBLE_VERSION_ERROR;

    return NPERR_NO_ERROR;
}

Per-platform Default Models

• Windows (all versions)
  • Windowed plugins
    • Event model: Native HWND event handling, model undesignated
    • Drawing model: Draw to HWND, model undesignated
  • Windowless Plugins
    • Event model: Legacy Win32-based event handling, model undesignated
    • Drawing model: Legacy Win32-based drawing, model undesignated
• Linux
  • Windowed plugins
    • Event model: Native X event handling, model undesignated
    • Drawing model: Native X drawing, model undesignated
  • Windowless Plugins
    • Event model: Legacy X event handling, model undesignated
    • Drawing model: Legacy X drawing, model undesignated
• Mac OS X
  • 32-bit
    • Event model: Carbon, NPEventModelCarbon
    • Drawing model: Quickdraw, NPDrawingModelQuickDraw
  • 64-bit
    • Event model: Cocoa, NPEventModelCocoa
    • Drawing model: Core Graphics, NPDrawingModelCoreGraphics