NPN_SetValue

« Gecko Plugin API Reference « Browser Side Plug-in API

Summary

Implemented by browsers. This call is used to inform the browser of variable information controlled by the plugin.

Syntax

#include <npapi.h>
 
NPError NPN_SetValue(NPP         instance,
                     NPPVariable variable, 
                     void        *value);

Parameters

The function has the following parameters:

instance: Pointer to the plugin instance setting the variable.

variable

Values the function can set:

NPPVpluginWindowBool: Sets windowed/windowless mode for plugin display; true=windowed, false=windowless
NPPVpluginTransparentBool: Sets transparent mode for display of a plugin; true=transparent, false=opaque
NPPVjavaClass
NPPVpluginWindowSize
NPPVpluginTimerInterval
NPPVpluginScriptableInstance
NPPVpluginScriptableIID
NPPVjavascriptPushCallerBool: Specifies whether you are pushing or popping the JSContext off the stack
NPPVpluginKeepLibraryInMemory: Tells browser that the plugin dll should live longer than usual
NPPVpluginNeedsXEmbed
NPPVpluginScriptableNPObject
NPPVformValue
NPPVpluginDrawingModel

value: The value of the specified variable to be set.

Returns

If successful, the function should return NPERR_NO_ERROR.
If unsuccessful, the function should return the most relevant NPAPI error code. For possible values, see Error Codes.

Description

A good place to set plugin operation mode such as windowless mode is NPP_New, so the browser knows right away what mode the plugin is designed to operate in.

NPPVpluginWindowBool (Windows and Unix) specifies that the plugin operates in windowed mode. The alternative is windowless where no window messages are sent to the plugin as there is no window associated with it. In windowless mode all the browser to plugin communications related to drawing, mouse, and keyboard input are accomplished via NPP_HandleEvent. To set windowless operation, call NPN_SetValue with NPPVpluginWindowBool as the variable parameter and FALSE as the value parameter. By default, plugins are windowed.

NPPVpluginTransparentBool (Windows and Unix) specifies that a plugin is either opaque or transparent. To specify an opaque mode, the plugin calls NPN_SetValue with NPPVpluginTransparentBool for the variable parameter and FALSE for the value parameter. To specify a transparent mode, the value parameter should be set to TRUE.

NPPVjavascriptPushCallerBool sets whether you are pushing or popping the appropriate JSContext off the stack (see the two-way scriptability article on the Mozilla Plugins project page for more details).

NPPVpluginKeepLibraryInMemory specifies that the plugin does not want to be unloaded from memory after the page which initiated it has gone. Normally, when the browser navigates away from the page containing the plugin, all plugin instances get an NPP_Destroy call, and if there are no more instances of the plugin active, the plugin calls its NP_Shutdown method and the plugin dll gets unloaded from memory. If this is not desired, the plugin can instruct the browser not to unload the dll and not to call NP_Shutdown when the page is left. In such a case all this will be done on the browser shutdown. The plugin calls NPN_SetValue any time with NPPVpluginKeepLibraryInMemory as variable parameter and value set to TRUE. By default, the dll will be unloaded from memory preceded by an NP_Shutdown call.

Remarks

All four variable values are boolean. Although the function prototype has type of value void *, the actual boolean should be placed there, not a pointer to a boolean. The browser code reads this parameter as follows (NPPVpluginWindowBool as an example):

NPError NP_EXPORT _setvalue(NPP npp, NPPVariable variable, void *value)
{
 ...
 BOOL bWindowless = (value == NULL);
 ...
}

So the proper way to call this function from a plug-in would be:

BOOL bWindowed = FALSE;

NPN_SetValue(npp, NPPVpluginWindowBool, (
      void *)bWindowed);