summaryrefslogtreecommitdiffstats
path: root/xparts/doc
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commit90825e2392b2d70e43c7a25b8a3752299a933894 (patch)
treee33aa27f02b74604afbfd0ea4f1cfca8833d882a /xparts/doc
downloadtdebindings-90825e2392b2d70e43c7a25b8a3752299a933894.tar.gz
tdebindings-90825e2392b2d70e43c7a25b8a3752299a933894.zip
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/kdebindings@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'xparts/doc')
-rw-r--r--xparts/doc/gtkxpart.fig55
-rw-r--r--xparts/doc/gtkxpart.pngbin0 -> 5917 bytes
-rw-r--r--xparts/doc/kparts.fig71
-rw-r--r--xparts/doc/kparts.pngbin0 -> 5916 bytes
-rw-r--r--xparts/doc/kxpart.fig55
-rw-r--r--xparts/doc/kxpart.pngbin0 -> 6749 bytes
-rw-r--r--xparts/doc/kxparthost.fig15
-rw-r--r--xparts/doc/kxparthost.pngbin0 -> 1652 bytes
-rw-r--r--xparts/doc/xparts.fig48
-rw-r--r--xparts/doc/xparts.html293
-rw-r--r--xparts/doc/xparts.pngbin0 -> 4197 bytes
11 files changed, 537 insertions, 0 deletions
diff --git a/xparts/doc/gtkxpart.fig b/xparts/doc/gtkxpart.fig
new file mode 100644
index 00000000..fc0669bd
--- /dev/null
+++ b/xparts/doc/gtkxpart.fig
@@ -0,0 +1,55 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4
+100.00
+Single
+-2
+1200 2
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 10125 2025 13050 2025 13050 3600 10125 3600 10125 2025
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 13500 3375 13500 2700 11925 2700 11925 3375 13500 3375
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 10125 4950 13050 4950 13050 6525 10125 6525 10125 4950
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 13500 6300 13500 5625 11475 5625 11475 6300 13500 6300
+2 1 0 4 0 7 100 0 20 0.000 0 0 -1 1 1 2
+ 1 1 2.00 120.00 120.00
+ 1 1 2.00 120.00 120.00
+ 12825 5625 12825 3375
+2 1 0 2 0 7 100 0 -1 0.000 0 0 19 1 0 2
+ 1 1 1.00 60.00 120.00
+ 10800 6525 10350 7875
+2 2 0 1 0 7 100 0 -1 0.000 0 0 19 0 0 5
+ 9225 7875 11700 7875 11700 9900 9225 9900 9225 7875
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 9450 9000 11025 9000 11025 9675 9450 9675 9450 9000
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 12375 8775 12375 8100 10800 8100 10800 8775 12375 8775
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 9225 11250 10350 11250 10350 11925 9225 11925 9225 11250
+2 1 0 2 0 7 100 0 -1 0.000 0 0 19 1 0 2
+ 1 1 1.00 60.00 120.00
+ 9900 9675 9675 11250
+2 1 1 2 0 7 100 0 -1 4.500 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 10350 9675 10350 11025
+2 2 1 1 0 7 100 0 -1 4.000 0 0 -1 0 0 5
+ 9000 11025 11700 11025 11700 12150 9000 12150 9000 11025
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 13050 9675 13050 9000 11250 9000 11250 9675 13050 9675
+4 0 0 100 0 0 12 0.0000 4 135 825 12375 3150 XPartHost\001
+4 0 0 100 0 0 12 0.0000 4 180 2040 10350 2475 KXPartHost : public KPart\001
+4 0 0 100 0 0 12 0.0000 4 180 1125 12150 6075 XPartManager\001
+4 0 0 100 0 0 12 0.0000 4 135 1680 13050 4275 DCOP communication\001
+4 0 0 100 0 0 12 0.0000 4 105 480 9900 7425 create\001
+4 0 0 100 0 0 12 0.0000 4 135 735 9450 8550 GtkXPart\001
+4 0 0 100 0 0 12 0.0000 4 180 1410 10350 5400 GtkXPartManager\001
+4 0 0 100 0 0 12 0.0000 4 135 1155 9675 9450 GtkMozEmbed\001
+4 0 0 100 0 0 12 0.0000 4 135 450 11250 8550 XPart\001
+4 0 0 100 0 0 12 0.0000 4 135 570 9450 11700 Mozilla\001
+4 0 0 100 0 0 12 0.0000 4 105 480 9225 10575 create\001
+4 0 0 100 0 16 12 0.0000 4 180 1560 10575 10575 load shared object\001
+4 0 0 100 0 0 12 0.0000 4 135 1410 11475 9450 BrowserExtension\001
diff --git a/xparts/doc/gtkxpart.png b/xparts/doc/gtkxpart.png
new file mode 100644
index 00000000..32e85e54
--- /dev/null
+++ b/xparts/doc/gtkxpart.png
Binary files differ
diff --git a/xparts/doc/kparts.fig b/xparts/doc/kparts.fig
new file mode 100644
index 00000000..afed114f
--- /dev/null
+++ b/xparts/doc/kparts.fig
@@ -0,0 +1,71 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4
+100.00
+Single
+-2
+1200 2
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 1575 2025 2925 2025 2925 2700 1575 2700 1575 2025
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 2925 2025 4275 2025 4275 2700 2925 2700 2925 2025
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 1575 1350 4275 1350 4275 2700 1575 2700 1575 1350
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 7425 3150 8550 3150 8550 3825 7425 3825 7425 3150
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 6300 3150 7425 3150 7425 3825 6300 3825 6300 3150
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 6300 2475 8550 2475 8550 3150 6300 3150 6300 2475
+2 1 0 2 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 2250 2700 1800 4275
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 1125 4275 2475 4275 2475 4950 1125 4950 1125 4275
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 2700 4275 3600 4275 3600 4950 2700 4950 2700 4275
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 900 6075 2475 6075 2475 6750 900 6750 900 6075
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 2925 6075 4050 6075 4050 6750 2925 6750 2925 6075
+2 1 0 2 0 7 100 0 -1 0.000 0 0 19 1 0 2
+ 1 1 1.00 60.00 120.00
+ 1800 4950 1350 6075
+2 1 0 2 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 2025 4950 3600 6075
+2 1 0 2 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 2475 2700 3150 4275
+2 2 1 1 0 7 100 0 -1 4.000 0 0 -1 0 0 5
+ 675 4050 4275 4050 4275 6975 675 6975 675 4050
+2 1 1 2 0 7 100 0 -1 4.500 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 3600 2700 3600 4050
+3 2 0 2 0 7 100 0 -1 0.000 0 1 0 3
+ 1 1 1.00 60.00 120.00
+ 6300 3600 5400 4050 4270 4243
+ 0.000 -1.000 0.000
+3 2 0 2 0 7 100 0 -1 0.000 0 1 0 3
+ 1 1 1.00 60.00 120.00
+ 4275 2025 5625 2250 6300 2700
+ 0.000 -1.000 0.000
+4 0 0 100 0 16 12 0.0000 4 135 1035 5175 4500 offer service\001
+4 0 0 100 0 0 12 0.0000 4 180 960 1800 2475 KLibFactory\001
+4 0 0 100 0 0 12 0.0000 4 135 900 3150 2475 KLibLoader\001
+4 0 0 100 0 16 12 0.0000 4 180 945 2475 1800 Application\001
+4 0 0 100 0 16 12 0.0000 4 180 1155 5400 2025 query service\001
+4 0 0 100 0 0 12 0.0000 4 180 750 7650 3600 KSyCoCa\001
+4 0 0 100 0 16 12 0.0000 4 135 660 6525 3600 KTrader\001
+4 0 0 100 0 16 12 0.0000 4 135 315 7200 2925 KIO\001
+4 0 0 100 0 0 12 0.0000 4 105 480 1575 3375 create\001
+4 0 0 100 0 16 12 0.0000 4 135 450 1575 4725 KPart\001
+4 0 0 100 0 0 12 0.0000 4 135 450 2925 4725 KPart\001
+4 0 0 100 0 0 12 0.0000 4 135 1410 900 6525 BrowserExtension\001
+4 0 0 100 0 0 12 0.0000 4 135 810 3150 6525 TextEditor\001
+4 0 0 100 0 0 12 0.0000 4 180 1110 1575 5850 queryInterface\001
+4 0 0 100 0 0 12 0.0000 4 180 1110 3150 5625 queryInterface\001
+4 0 0 100 0 0 12 0.0000 4 105 480 2475 3825 create\001
+4 0 0 100 0 16 12 0.0000 4 180 1560 3600 3375 load shared object\001
diff --git a/xparts/doc/kparts.png b/xparts/doc/kparts.png
new file mode 100644
index 00000000..b2d534b3
--- /dev/null
+++ b/xparts/doc/kparts.png
Binary files differ
diff --git a/xparts/doc/kxpart.fig b/xparts/doc/kxpart.fig
new file mode 100644
index 00000000..ce238956
--- /dev/null
+++ b/xparts/doc/kxpart.fig
@@ -0,0 +1,55 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4
+100.00
+Single
+-2
+1200 2
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 10125 2025 13050 2025 13050 3600 10125 3600 10125 2025
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 13500 3375 13500 2700 11925 2700 11925 3375 13500 3375
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 10125 4950 13050 4950 13050 6525 10125 6525 10125 4950
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 13500 6300 13500 5625 11475 5625 11475 6300 13500 6300
+2 1 0 4 0 7 100 0 20 0.000 0 0 -1 1 1 2
+ 1 1 2.00 120.00 120.00
+ 1 1 2.00 120.00 120.00
+ 12825 5625 12825 3375
+2 1 0 2 0 7 100 0 20 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 10575 7200 9225 10125
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 11475 6525 13050 6525 13050 7200 11475 7200 11475 6525
+2 1 1 2 0 7 100 0 -1 4.500 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 12375 7200 12375 8550
+2 2 1 1 0 7 100 0 -1 4.000 0 0 -1 0 0 5
+ 7875 8550 13050 8550 13050 11475 7875 11475 7875 8550
+2 2 0 1 0 7 100 0 -1 0.000 0 0 19 0 0 5
+ 8325 9000 10800 9000 10800 11025 8325 11025 8325 9000
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 11925 9900 11925 9225 10350 9225 10350 9900 11925 9900
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 8550 10125 9675 10125 9675 10800 8550 10800 8550 10125
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 10125 6525 11475 6525 11475 7200 10125 7200 10125 6525
+2 1 0 2 0 7 100 0 -1 0.000 0 0 19 1 0 2
+ 1 1 1.00 60.00 120.00
+ 10086 6059 8775 9000
+4 0 0 100 0 0 12 0.0000 4 135 825 12375 3150 XPartHost\001
+4 0 0 100 0 0 12 0.0000 4 180 2040 10350 2475 KXPartHost : public KPart\001
+4 0 0 100 0 0 12 0.0000 4 180 1260 10350 5400 KXPartManager\001
+4 0 0 100 0 0 12 0.0000 4 180 1125 12150 6075 XPartManager\001
+4 0 0 100 0 0 12 0.0000 4 135 1680 13050 4275 DCOP communication\001
+4 0 0 100 0 0 12 0.0000 4 180 960 10350 6975 KLibFactory\001
+4 0 0 100 0 0 12 0.0000 4 135 900 11700 6975 KLibLoader\001
+4 0 0 100 0 16 12 0.0000 4 180 1560 12600 7875 load shared object\001
+4 0 0 100 0 0 12 0.0000 4 135 450 10800 9675 XPart\001
+4 0 0 100 0 0 12 0.0000 4 135 450 8775 10575 KPart\001
+4 0 0 100 0 0 12 0.0000 4 105 480 10350 7875 create\001
+4 0 0 100 0 0 12 0.0000 4 180 570 8550 9450 KXpart\001
+4 0 0 100 0 0 12 0.0000 4 105 480 8775 7650 create\001
diff --git a/xparts/doc/kxpart.png b/xparts/doc/kxpart.png
new file mode 100644
index 00000000..70ae2e5f
--- /dev/null
+++ b/xparts/doc/kxpart.png
Binary files differ
diff --git a/xparts/doc/kxparthost.fig b/xparts/doc/kxparthost.fig
new file mode 100644
index 00000000..fa34c141
--- /dev/null
+++ b/xparts/doc/kxparthost.fig
@@ -0,0 +1,15 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4
+100.00
+Single
+-2
+1200 2
+2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
+ 10125 2025 13050 2025 13050 3600 10125 3600 10125 2025
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 13500 3375 13500 2700 11925 2700 11925 3375 13500 3375
+4 0 0 100 0 0 12 0.0000 4 135 825 12375 3150 XPartHost\001
+4 0 0 100 0 0 12 0.0000 4 180 2040 10350 2475 KXPartHost : public KPart\001
diff --git a/xparts/doc/kxparthost.png b/xparts/doc/kxparthost.png
new file mode 100644
index 00000000..d223e687
--- /dev/null
+++ b/xparts/doc/kxparthost.png
Binary files differ
diff --git a/xparts/doc/xparts.fig b/xparts/doc/xparts.fig
new file mode 100644
index 00000000..6ac73ff2
--- /dev/null
+++ b/xparts/doc/xparts.fig
@@ -0,0 +1,48 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4
+100.00
+Single
+-2
+1200 2
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 5175 4050 5175 3375 3600 3375 3600 4050 5175 4050
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 5400 5850 5400 5175 3600 5175 3600 5850 5400 5850
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 3600 8325 3600 7650 1800 7650 1800 8325 3600 8325
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 5850 8325 5850 7650 4050 7650 4050 8325 5850 8325
+2 1 0 2 0 7 100 0 20 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 3375 6975 2925 7650
+2 1 0 2 0 7 100 0 20 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 4050 6975 4950 7650
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 6750 6975 6750 6300 5175 6300 5175 6975 6750 6975
+2 1 0 2 0 7 100 0 20 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 4725 5850 5850 6300
+2 1 0 2 0 7 100 0 20 0.000 0 0 -1 1 0 2
+ 1 1 1.00 60.00 120.00
+ 4275 5850 3825 6300
+2 4 0 1 0 7 100 0 20 0.000 0 0 19 0 0 5
+ 4500 6975 4500 6300 2925 6300 2925 6975 4500 6975
+2 1 0 4 0 7 100 0 20 0.000 0 0 -1 1 1 2
+ 1 1 2.00 120.00 120.00
+ 1 1 2.00 120.00 120.00
+ 4500 5175 4500 4050
+4 0 0 100 0 0 12 0.0000 4 135 825 4050 3825 XPartHost\001
+4 0 0 100 0 0 12 0.0000 4 180 1125 3825 5625 XPartManager\001
+4 0 0 100 0 0 12 0.0000 4 135 1410 2025 8100 BrowserExtension\001
+4 0 0 100 0 0 12 0.0000 4 135 810 4500 8100 TextEditor\001
+4 0 0 100 0 0 12 0.0000 4 135 450 5625 6750 XPart\001
+4 0 0 100 0 0 12 0.0000 4 135 450 3375 6750 XPart\001
+4 0 0 100 0 0 12 0.0000 4 105 480 5625 6075 create\001
+4 0 0 100 0 0 12 0.0000 4 180 1110 4725 7425 queryInterface\001
+4 0 0 100 0 0 12 0.0000 4 180 1110 1800 7425 queryInterface\001
+4 0 0 100 0 0 12 0.0000 4 135 1680 4725 4725 DCOP communication\001
+4 0 0 100 0 0 12 0.0000 4 105 480 3375 6075 create\001
diff --git a/xparts/doc/xparts.html b/xparts/doc/xparts.html
new file mode 100644
index 00000000..0ff872be
--- /dev/null
+++ b/xparts/doc/xparts.html
@@ -0,0 +1,293 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <title>XParts - Extending KParts</title>
+ </head>
+
+ <body>
+<center>
+<h1>XParts - Extending KParts</h1>
+ <small>Matthias Ettrich, Simon Hausmann, Lars Knoll</small>
+</center>
+
+ <p>This article briefly describe the concepts, architecture and
+ reasoning behind the XParts technology. The purpose of XParts is
+ to extend KParts over language, toolkit, process and machine
+ bounderies. XParts makes it possible to write KDE components with
+ almost any toolkit or language an author prefers or to turn
+ existing applications into KDE components quite easily.
+
+ <p>In addition, XParts is also an important glueing technology to
+ make KParts available in other component based systems or to
+ utilize non-KPart components transparently as KParts.
+
+ <h4>Classic KParts</h4>
+
+ <p>In order to understand, what is extending about XParts, first a
+ brief overview on how KParts work.
+
+ <img src="kparts.png">
+
+ <p>Imagine an application - for example the integrated file manager
+ "Konqueror" - wants to utilize a component that handles the
+ "text/html" mimetype. It therefore asks the trader of the KIO
+ subsystem whether such a service is available and where. The
+ trader uses the system configuration cache to localize an
+ appropriate service that fits with the user's preferences. The
+ system configuration cache is a service type database
+ constructed from the desktop files of a KDE setup. In the case
+ of "text/html", the trader will very like return KDE's builtin
+ HTML viewer dubbed KHtml. This viewer is is most certainly
+ available as a KPart component. The application will then - via
+ KLibLoader and KLibFactory - load the shared library object that
+ implements the component and create a KPart instance. The
+ LibLoader keeps track of any objects created in the loaded
+ library and will automatically unload it after all objects have
+ been deleted.
+
+ <p>If the application does not only want to display HTML, but
+ act as a full featured browser, the plain KPart interface is not
+ sufficient. If the user clicks on a link, for example, the HTML
+ component has to request a new URL. This kind of interaction is
+ defined in the BrowserExtension interface. An application can
+ query the KParts for additonal interfaces and get handles to
+ them in case those are available. In the example case of KHtml,
+ the BrowserExtension interface is exported. In the case of a
+ text editor component, it's very likely that the TextEditor
+ interface is available.
+
+ <h4>In-process components</h4>
+
+ <p>The beauty of KParts is its simplicity. It's a clean and
+ flexible in-process approach with all its advantages:
+ <ul>
+ <li> lightweight - components share the same application
+ context and all its allocated resources.
+ <li> synchronious - calls are predictable, there are no
+ timeouts to wait for and no events to process in an uncertain
+ amount of time.
+ <li> stable - neither race conditions nor rare exceptions
+ can occur
+ <li> extremely powerful - there are virtually no
+ limitations to how a component API can look like (including
+ passing pointers) or what a plugin can do with an application.
+ </ul>
+
+ <p>Those advantages are unvaluable for a lightweight and tightly
+ integrated office suite like KOffice. However, there are no silver
+ bullets and most certainly there are drawbacks when the system is
+ used in settings with different requirements.
+
+ <p>Take the fourth item, it's comprehensive power while
+ maintaining simplicity. This was one of the main requirements of
+ the KOffice team, and it alone almost determines an in-process
+ approach with dynamically loadable shared objects. In a generic
+ browser like Konqueror, the requirements for integrated components
+ are not as high as with an office suite. In an office suite,
+ different components operate on one single document, whereas in a
+ browser, the components basically provide different views for
+ given Urls. To illustrate this issue, imagine how far the web
+ came with such primitive and inflexible component technology like
+ Netscape plugins. They did most of what people wanted to do with
+ browser plugins, though, and so became a huge success.
+
+ <h4>Out-of-process components</h4>
+
+ <p>To sum this up: for multi-view applications like a generic
+ browser, there's no technical argument why out-of-process
+ components could not be sufficient. So let's look closer at the
+ specific advantages of such a solution.
+
+ <ul>
+ <li>With out-of-process components, it's much easier to provide
+ applications as components that do not support being loaded
+ dynamically as shared library objects. Typical examples are
+ programs written in interpreted languages. With a pure in-process
+ model, one would have to be able to load the interpreter as
+ embedded language.
+
+ <li>If a component handles the event loop differently from the
+ embedding application, an complete event loop merger is
+ required. This glueing code can be tricky and might not work well
+ in all cases. It's much easier for out-of-process components to
+ provide full toolkit independence.
+
+ <li> components of the same type could share one process
+ context. Not sure where this is actually useful, but it has most
+ certainly some technical beauty attached to it.
+
+ </ul>
+
+ <p>Let's pick a concrete example. Imagine that you - for whatever
+ reason - want to offer the Mozilla rendering engine (gecko) as
+ KPart, so that users have an an alternative to KDE's builtin
+ rendering engine KHtml.
+
+ <p>The first step of such a project is to find out, whether
+ Mozilla already is available as a reusable component that could
+ form the basis of a KDE integration. And in fact, it is. A small
+ library called GtkMozEmbed makes it possible to load the entire
+ Mozilla as a single Gtk widget, i.e. the rendering engine gecko,
+ the networking protocol implementations, the javascript
+ interpreter and whatever else Mozilla.org comes up with. The
+ MozEmbed library works pretty similar to KParts. Once
+ instantiated, it dynamically loads all libraries required by
+ Mozilla. As an interesting side note, all Unix filemanager
+ projects that utilize Mozilla (for example the Nautilus
+ filemanager) use this library to embed mozilla. This means you are
+ in good company using a stock MozEmbed library, as you don't have
+ to maintain this code but somebody else will do it for you.
+
+ <p>Now that we have a dynamically loaded Gtk widget, how do we
+ turn that into a KPart? Quite straight forward. There is a
+ QGtkWidget extension available for Qt, that lets you use Gtk
+ widgets in your Qt applications. You simply create a QGtkWidget
+ with a pointer to the Gtk widget you get from MozEmbed and insert
+ that into your KPart. Then you do a few trivial reimplementations
+ of the virtual functions of the BrowserExtension interface that
+ map to the corresponding functions of Mozilla and you are
+ done. The result is a fully functional Konqueror that uses Mozilla
+ as backend - or rather a fully functional Mozilla that uses
+ Konqueror as graphical user interface, however you want to look at
+ it.
+
+ <h4>Trouble ahead</h4>
+
+ <p> While the skedged solution works, there are some unmentioned
+ and ugly details. First of all, Mozilla uses the event loop of
+ glib, while Konqueror uses Qt. Unfortunatly, mixing both event
+ loops is not possible with the current release of glib, unless one
+ want to end up with an application that constantly requires some
+ CPU to run, even when being idle. While this seems to be ok for
+ today's Java virtual machines, it's not acceptable by KDE's
+ quality standards. Until glib 2.0 is released, you need to patch
+ glib in order to make the QGtkWidget work properly. No big deal
+ for most Linux users, still a hassle. And keep in mind that glib
+ is a fairly open system. If the component was written in some
+ other toolkit, it might be possible that glueing code is
+ impossible to get right, without wasting at least a bit of CPU.
+
+ <p>The second problem is Mozilla's size. It's by no means an
+ ordinary component. In fact, it's a magnitude larger than the
+ Konqueror framework. And since Mozilla and Konqueror do not share
+ the same graphics toolkit, the toolkit's size has to be added to
+ that. It seems odd to load and unload such a huge amount of code -
+ and it can to lead to all kind of problems when trying to unload
+ it again.
+
+ <p>To make things worse, Mozilla wasn't even released as final
+ version yet. While it is already quite usable, it's stability is
+ still far from being production quality. This doesn't matter too
+ much for a standalone browser, but can really hurt with a
+ component. A standalone browser usually is supposed to display one
+ web page. If it crashes, this page is gone, so the user simply
+ tries again. With a generic browser like Konqueror, there is not
+ just one component active at a time, but several. There might be
+ some directory views, an embedded console, another toplevel window
+ window, an imaged preview and much more. A crashing Mozilla would
+ take all those component with it - and leave the user with only
+ half of its prior desktop.
+
+ <p>Imagine that some users define Mozilla to be the primary
+ component to handle text/html in Konqueror. After some testing, all
+ works well and they continue using it. A couple of days later, they
+ might have forgotten the configuration change they did. Whenever
+ they now hit a web page where Mozilla crashes, they will blame
+ Konqueror. This we don't want. No code is perfect, but if a crash
+ occurs in our code, at least it's our crash. That means, we can fix
+ it and we can provide newer versions.
+
+ <p>Thus, from a maintainance and support point of you, it is not
+ acceptable for KDE to run code inprocess that is not actually
+ maintained or controlled by the team, at least not in the default
+ setup.
+
+ <h4>Out-of-process components</h4>
+
+ <p>For the given reasons, it makes a lot of sense to extend KParts
+ over process bounderies. In addition, we also win a high degree of
+ toolkit and language independency.
+
+ <p>To make this work, we have to identify the streamable parts of
+ the KParts interface and offer them via some kind of middleware.
+
+ <p>We chose KDE's native desktop middleware, the desktop
+ communication protocol (DCOP) to establish the communication. In
+ addition to the fact that DCOP was explicitely designed for these
+ kind of tasks, there are some more benefits:
+ <ul>
+ <li> DCOP runs already on the desktop, i.e. there are no additonal costs
+ in terms of resource consumption.
+ <li> Does not put any limitations onto the interfaces as long as
+ data types are streamable
+ <li> Server architecture makes it easy and robust to detect
+ crashes on either side.
+ </ul>
+
+ There are several DCOP implementations available. The reference
+ implementation is the one using C++ and Qt that is used in KDE
+ applications. For Mozilla, we would choose a plain ANSI-C
+ implementation that uses glib.
+
+ <p>The following picture shows the interface structure:
+
+ <p> <img src="xparts.png">
+
+ <p>The main thing that differs from KParts is the
+ <em>XPartHost</em> interface that is responsible for embedding a
+ part. The missing link now is a standard KPart component that
+ implements the <em>XPartHost</em> interface. Via this
+ <b>KXPartHost</b> component, it is possible to use any XPart
+ transparently as KPart without changing a single line of code:
+ <p>
+ <img src="kxparthost.png">
+
+ <p>On the other side of the fence, we need an implementation of
+ the <em>XPartManager</em> interface and can serve us with
+ <em>XPart</em> interfaces. We provide this through the
+ relatively highlevel and generic classes GtkXPartManger and
+ GtkXPart, as shown in the next picture:
+ <p>
+ <img src="gtkxpart.png">
+ <p> The GtkXPart is a standard Gtk widget that can have a MozEmbed
+ widget as child widget. The only code that is necessary to write
+ is the code used to connect the <em>BrowserExtension</em>
+ interface to the corresponding functions of Mozilla.
+
+ <h4>External KParts</h4>
+
+ <p>The same technique can now be used to utilize standard KPart
+ components in an out-of-process fashion via the XPart system. All
+ we need is a KXPartManager that wraps standard KParts in
+ KXParts. The KXParts then export the <em>XPart</em> interface. The
+ complete structure is shown in the next picture:
+ <p><img src="kxpart.png">
+
+ <h4>Conclusion</h4> <p> Although the implementation of the
+ external mozilla part is more a proof of concept than a finished
+ xpart, we have shown a clean way to realize out of process
+ components on top of KParts. It could also be shown that this
+ approach is both language and toolkit independent.
+
+ <p>To accomplish this task, not a <em>single</em> line of code
+ in konqueror had to be changed. All we did was providing yet
+ another independent KPart component.
+
+ <p>By writing a small wrapper it is possible to embed any kind of
+ visual component. In addition, we can provide generic wrappers for
+ any kind of visual component model, as long as those models are
+ powerful enough to describe their interfaces and GUI requirements
+ at runtime. This includes KParts (eg. KOffice components), Bonobo
+ components (like the Nautilus MP3 viewer) and Uno components
+ provided by OpenOffice (formerly known as StarOffice).
+
+ <hr>
+ <address><a href="mailto:ettrich@kde.org">Matthias Ettrich</a></address>
+ <address><a href="mailto:hausmann@kde.org">Simon Hausmann</a></address>
+ <address><a href="mailto:knoll@kde.org">Lars Knoll</a></address>
+<!-- Created: Tue Oct 17 18:08:25 CEST 2000 -->
+<!-- hhmts start -->
+Last modified: Tue Apr 3 20:39:13 CEST 2001
+<!-- hhmts end -->
+ </body>
+</html>
diff --git a/xparts/doc/xparts.png b/xparts/doc/xparts.png
new file mode 100644
index 00000000..3193842a
--- /dev/null
+++ b/xparts/doc/xparts.png
Binary files differ