gecko/modules/plugin/test/testplugin

= Instructions for using the test plugin =

== MIME type ==

The test plugin registers itself for the MIME type "application/x-test".

== Rendering ==

By default, the plugin fills its rectangle with gray, with a black border, and
renders the user-agent string (obtained from NPN_UserAgent) centered in black.

The test plugin supports the following parameters:

* drawmode="solid"
The plugin will draw a solid color instead of the default rendering described
above. The default solid color is completely transparent black (i.e., nothing).

* color
This specifies the color to use for drawmode="solid". The value should be 8 hex
digits, 2 per channel in AARRGGBB format.

== Generic API Tests ==

* setUndefinedValueTest
Attempts to set the value of an undefined variable (0x0) via NPN_SetValue,
returns true if it succeeds and false if it doesn't. It should never succeed.

== NPRuntime testing ==

The test plugin object supports the following scriptable method:

* identifierToStringTest(ident)
Converts a string, int32 or double parameter 'ident' to an NPIdentifier and
then to a string, which is returned.

== Private browsing ==

The test plugin object supports the following scriptable methods:

* queryPrivateModeState
Returns the value of NPN_GetValue(NPNVprivateModeBool).

* lastReportedPrivateModeState
Returns the last value set by NPP_SetValue(NPNVprivateModeBool).

== Windowed/windowless mode ==

The test plugin is windowless by default.

The test plugin supports the following parameter:

* wmode="window"
The plugin will be given a native widget on platforms where we support this
(Windows and X).

The test plugin object supports the following scriptable method:

* hasWidget()
Returns true if the plugin has an associated widget. This will return true if
wmode="window" was specified and the platform supports windowed plugins.

== Plugin geometry ==

The test plugin supports the following scriptable methods:

* getEdge(edge)
Returns the integer screen pixel coordinate of an edge of the plugin's
area:
-- edge=0: returns left edge coordinate
-- edge=1: returns top edge coordinate
-- edge=2: returns right edge coordinate
-- edge=3: returns bottom edge coordinate
The coordinates are relative to the top-left corner of the top-level window
containing the plugin, including the window decorations. Therefore:
-- On Mac, they're relative to the top-left corner of the toplevel Cocoa
window.
-- On Windows, they're relative to the top-left corner of the toplevel HWND's
non-client area.
-- On GTK2, they're relative to the top-left corner of the toplevel window's
window manager frame.
This means they can be added to Gecko's window.screenX/screenY (if DPI is set
to 96) to get screen coordinates.
On the platforms that support window-mode plugins (Windows/GTK2), this only
works for window-mode plugins. It will throw an error for windowless plugins.

* getClipRegionRectCount()
Returns the number of rectangles in the plugin's clip region.
For plugins with widgets, the clip region is computed as the intersection of the
clip region for the widget (if the platform does not support clip regions
on native widgets, this would just be the widget's rectangle) with the
clip regions of all ancestor widgets which would clip this widget.
On the platforms that support window-mode plugins (Windows/GTK2), this only
works for window-mode plugins. It will throw an error for windowless plugins.
On Mac, all plugins have a clip region containing just a single clip
rectangle only. So if you request wmode="window" but the plugin reports
!hasWidget, you can assume that complex clip regions are not supported.

* getClipRegionRectEdge(i, edge)
Returns the integer screen pixel coordinate of an edge of a rectangle from the
plugin's clip region. If i is less than zero or greater than or equal to
getClipRegionRectCount(), this will throw an error. The coordinates are
the same as for getEdge. See getClipRegionRectCount() above for
notes on platform plugin limitations.

== Mouse events ==

The test plugin supports the following scriptable methods:

* getLastMouseX()
Returns the X coordinate of the last mouse event (move, button up, or
button down), relative to the left edge of the plugin, or -1 if no mouse
event has been received.

* getLastMouseX()
Returns the Y coordinate of the last mouse event (move, button up, or
button down), relative to the top edge of the plugin, or -1 if no mouse
event has been received.

== Instance lifecycle ==

The test plugin supports the following scriptable methods:

* startWatchingInstanceCount()
Marks all currently running instances as "ignored". Throws an exception if
there is already a watch (startWatchingInstanceCount has already been
called on some instance without a corresponding stopWatchingInstanceCount).

* getInstanceCount()
Returns the count of currently running instances that are not ignored.
Throws an exception if there is no watch.

* stopWatchingInstanceCount()
Stops watching. Throws an exception if there is no watch.

== NPAPI Timers ==

* unscheduleAllTimers()
Instructs the plugin instance to cancel all timers created via
NPN_ScheduleTimer.