Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 255 insertions, 0 deletions

diff --git a/nsplugins/README b/nsplugins/README
new file mode 100644
index 000000000..5b45594ab
--- /dev/null
+++ b/nsplugins/README
@@ -0,0 +1,255 @@
+nsplugins
+=========
+
+The 'nsplugins' directory contains various tools used to utilize Netscape(R)
+browser plugins in KDE applications.
+
+ - ./       - common headers and utilities
+
+ - viewer/  - provides means to embed a Netscape(R) browser plugin
+              into a KDE application.
+
+ - sdk/     - headers from the Netscape(R) browser plugin SDK.
+
+ - control/ - KDE Control Center applet for managing plugins
+
+ - test/    - simple applications to test nsplugin
+
+ - wrapper/ - currently unused.
+
+
+At the time of writing, nsplugins supports Navigator 4 API plugins
+and doesn't support new Mozilla XPCOM components.
+
+Parts
+=====
+
+The Netscape(R) browser plugin support consists of 3 parts:
+- "PluginPart" KPart which is embedded into KHTML pages
+  (alone, it looks no different than a gray rectangle)
+- "nspluginviewer", a separate application which is capable of
+  actually loading and playing the various Netscape(R) plugins.
+- "pluginscan", a small utility to scan predefined directories
+  for Netscape(R) browser plugins.
+
+PluginPart's responsibility is to run "nspluginviewer" and instruct
+it to display the plugin inside its' rectangle.
+
+* KParts is KDE's standard for embeddable objects, much like
+  Microsoft's OLE.
+
+PluginPart / nspluginviewer separation
+======================================
+
+Plugins contain 3rd-party code which might crash if badly written
+(especially inside our "Netscape emulation" environment).
+The PluginPart runs inside the memory space of the embedding application,
+making the embedding application susceptible to a crash in the PluginPart.
+In our case, the "embedding application" would be the browser, and having
+the whole browser shut down just because some plugin crashed is bad.
+By loading and talking to the plugin is a separate process
+("nspluginviewer"), we prevent such crashes from taking
+the browser down with them -- the worst that could happen
+is the plugin suddenly disappearing from the page, revealing
+PluginPart's gray background.
+
+nspluginviewer to PluginPart communications
+===========================================
+
+The communications between the PluginPart and nspluginviewer
+are done via DCOP. Messages which nspluginviewer could send
+to PluginPart include:
+- requestURL(url, target) - make the browser load a URL
+- statusMessage(msg)      - change the status bar in the
+                            embedding application
+
+(For an updated list of messages, see NSPluginCallbackIface.h)
+
+When received, those messages are mapped to functions in
+NSPluginCallback, which in turn calls PluginPart functions.
+
+* DCOP is KDE's standard for RPC, typically used by local
+  processes to pass messages.
+
+PluginPart to nspluginviewer communications
+===========================================
+
+nspluginviewer's window is, all in all, a simple X11 window,
+it can be resized, focused and unfocused with standard X11 functions
+as long as we know its' window ID.
+
+PluginPart gets a NSPluginInstance (from NSPluginLoader::newInstance),
+which it sees as a regular QWidget. e.g. it can resize the QWidget and
+nspluginviewer's window will resize.
+
+This magic happens thanks to KJavaEmbed which NSPluginInstance inherits.
+KJavaEmbed inherits QWidget and hooks up to QWidget's events, mapping
+those events to the appropriate X11 window operations.
+Resizing, focusing in and out is about all PluginPart could ever do
+with the nspluginviewer.
+
+How does KJavaEmbed know the window ID of the nspluginviewer window?
+NSPluginInstance retrieves it from nspluginviewer with a DCOP call
+("int winId()") and gives it to KJavaEmbed.
+
+Main classes
+============
+
+- PluginPart class (plugin_part.h, plugin_part.cpp)
+  
+  A KParts::ReadOnlyPart.
+  
+- PluginFactory class (plugin_part.h, plugin_part.cpp)
+
+  Creates PluginPart objects.
+
+- NSPluginInstance class (nspluginloader.h, nspluginloader.cpp)
+
+  PluginPart's "looking glass" to "nspluginviewer".
+
+- NSPluginLoader class (nspluginloader.h, nspluginloader.cpp)
+
+  Responsible for starting a new independant process of the
+  plugin viewer and initiating DCOP communications with it.
+  
+- NSPluginCallbackIface (NSPluginCallbackIface.h)
+
+  Defines functions which the nspluginviewer can call in the PluginPart.
+  Those function calls would be transfered over DCOP and implemented
+  in PluginPart's NSPluginCallback class.
+
+
+Plugin Scanner
+==============
+
+Implemented in: pluginscan.cpp
+
+Utility which scans for Netscape(R) browser plugins in pre-defined
+directories (according to KDE's configuration) and writes down
+information about the located plugins into the plugin information
+cache. To locate all the plugins, it doesn't limit itself to files
+with .so extension. A forking mechanism is implemented to prevent
+faulty .so's from crashing the scanning process.
+	
+This utility is usually not invoked standalone, but used by the
+KDE Control Center applet which invokes it on:
+- explicit request (ie. pressing "Scan for new plugins" button)
+- KDE startup (in the applet's initialization code)
+- first time the applet is ran
+
+	
+Viewer
+======
+
+Implemented in: viewer/
+
+The viewer is a KDE component used to embed Netscape(R) plugins
+into KDE applications (such as KHTML / Konqueror). To the plugin, it
+emulates a Netscape(R) browser, while outside - it offers a standard KParts
+object.
+
+NSPluginCallbackIface.h
+
+  Defines functions which the nspluginviewer can call in the PluginPart.
+  Those function calls would be transfered over DCOP and implemented
+  in PluginPart's NSPluginCallback class.
+
+kxt.h, kxt.cpp
+
+  ...
+	
+resolve.h
+
+  Some macros to resolve symbols.
+	
+nsplugin.h, nsplugin.cpp
+
+  The implementation of the interface between KDE and the Netscape(R)
+  browser plugin as a KParts object.
+	
+  Note: This file implements its own NSPluginInstance, which should
+  not be confused with PluginPart's NSPluginInstance.
+
+  It implements:
+  - The Netscape(R) emulation side:
+    g_NPN_* functions, which implement Netscape(R) browser
+    plugin API NPN_* C methods accordingly. Our emulation
+    of a Netscape(R) browser is as good as those functions are.
+    
+    By definition, all functions are passed with an NPN ("plugin
+    instance") struct, and each NPN has an 'ndata'  pointer member.
+    That's good news to us, since we now can use it to point to
+    our NSPluginInstance object.
+    
+    Those functions contain the minimum necessary code to
+    call the NSPluginInstance function for the requested operation
+
+  - The KDE side:
+    NSPluginInstance implements functions for various g_NPN_*
+    operations. Typically those operations will be passed via DCOP
+    to the PluginPart -- e.g. a operation which changes the window's
+    status bar.
+	
+viewer.cpp
+
+  A standalone application that executes Netscape plugins.
+
+Control Center applet
+=====================
+
+The Control Center applet allows the user to:
+- Add additional directories which "pluginscan" would scan for
+  Netscape(R) plugins. 
+- See which plugins "pluginscan" found (by reading the plugin cache). 
+- Force a "pluginscan" rescan.
+
+The KDE Control Center API is well documented in the KDE SDK.
+
+Compatibility notes
+===================
+
+Although nsplugins strive for full compatibility with the Netscape(R)
+browser plugin execution environment, it still lacks the following features:
+
+- LiveConnect (Netscape Navigator 3.0) Java / JavaScript connectivity
+
+  Support for LiveConnect (for JavaScript support) requires:
+  - Reimplementation of Netscape's JRI functions (see sdk/jri.h)
+    to communicate back (via DCOP?) with the PluginPart, which'll
+    signal them to KHTML's KJS interpretor. KParts::BrowserExtension
+    should be extended to support those signals. Of course, only
+    JRI calls in the "netscape.javascript" namespace should be handled.
+  - Implementation of g_NPN_GetJavaEnv and g_NPN_GetJavaPeer
+    (currently they're empty placeholders).
+  - Implementing g_NPN_GetValue(NPNVjavascriptEnabledBool, ...)
+    (currently always returns "false").
+    Should involve adding a slot to KParts::BrowserExtension
+    and making KHTML signal it whenever JS gets enabled or disabled.
+
+  LiveConnect will probably never be supported due to JRE ABI issues, and
+  the fact that we need to have a JRE with JNI inside the nspluginviewer.
+  LiveConnect is almost obsolete as well.  XPConnect will not be integrated
+  either.
+
+The current support is enough to run common plugins such as Macromedia(R)
+Flash(R) and RealPlayer(R), but some of their functionality might be missing.
+For instance, Flash(R) animations cannot call user-defined JavaScript
+routines nor can the user control the Flash(R) animation via JavaScript.
+
+Additional documentation
+========================
+
+Additional documentation on the Netscape(R) plugin API is available at:
+
+- http://developer.netscape.com/docs/manuals/plugins.html
+- http://www.mozilla.org/docs/plugin.html
+
+Author
+======
+
+This README was authored Ilya Konstantinov <kde-devel@future.shiny.co.il>.
+Thanks go to Matthias Hoelzer-Kluepfel and Stefan Schimanski for writing
+the actual code and making it all possible.
+
+Present maintainer of the nsplugin code is George Staikos <staikos@kde.org>
+