Netscape DevEdge

Skip to: [content] [navigation]

TOC PREV NEXT

plug-ins!

NPN_SetValue

Sets various modes of plug-in operation.

Syntax 

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

Parameters

The function has the following parameters: 

instance
Pointer to the current plug-in instance.
 
variable

Values the function can set:

  • NPPVpluginWindowBool: Sets windowless mode for display of a plug-in; true=windowless, false=not windowless
  • NPPVpluginTransparentBool: Sets transparent mode for display of a plug-in; true=transparent, false=opaque
  • NPPVjavascriptPushCallerBool - Specifies whether you are pushing or popping the JSContext off the stack
  • NPPVpluginKeepLibraryInMemory - Tells browser that plugin dll should live longer than usual 
value
The value of the specified variable to be set, TRUE or FALSE.

Returns

  • If successful, the function returns NPERR_NO_ERROR.
  • If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see Error Codes.

Description

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

NPPVpluginWindowBool (Windows and Unix) specifies that plug-in operates in windowless mode. In this mode no window messages are send to the plug-in as there is no window associated with it, all the browser to plug-in commucations related to drawing and mouse and keyboard input are event based and accomplished via NPP_HandleEvent. To set windowless operation plugin calls NPN_SetValue with NPPVpluginWindowBool as its variable parameter and TRUE as its value parameter. As a default, plug-ins are windowd, so if NPP_New does not contain this call the plug-in is considered to be windowed.

NPPVpluginTransparentBool (Windows and Unix) specifies that a plug-in is either opaque or transparent. To specify an opaque mode, the plugin calls NPN_SetValue with NPPVpluginTransparentBool for its variable parameter and FALSE for its 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 of the stack (See the two-way scriptability article on the Mozilla Plug-ins project page for more details).

NPPVpluginKeepLibraryInMemory specifies that the plug-in 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 plug-in all plug-in instances get NPP_Destroy call, and if there is no more instances of the plug-in active the plug-in is called its NP_Shutdown method and the plug-in dll gets unloaded from memory. If this is not desired the plug-in 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. Plug-in 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 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);

See Also 

NPP_New, NPN_GetValue, NPP_SetValue

Netscape Communications
http://developer.netscape.com
TOC PREV NEXT
A–+R