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

6 files changed, 277 insertions, 0 deletions

diff --git a/kjsembed/docs/examples/html2text/html2text.js b/kjsembed/docs/examples/html2text/html2text.js
new file mode 100644
index 00000000..a8d6dd9a
--- /dev/null
+++ b/kjsembed/docs/examples/html2text/html2text.js
@@ -0,0 +1,7 @@
+Factory.load('html2text_plugin.js');
+
+var line = readLine();
+while ( line != null ) {
+      print( html2text(line) );
+      line = readLine();
+}
diff --git a/kjsembed/docs/examples/html2text/html2text_plugin.js b/kjsembed/docs/examples/html2text/html2text_plugin.js
new file mode 100644
index 00000000..61146537
--- /dev/null
+++ b/kjsembed/docs/examples/html2text/html2text_plugin.js
@@ -0,0 +1,19 @@
+
+function html2text( html )
+{
+    var text = html.replace( /<[^>]*>/g, '' );
+    text = text.replace( /&quot;/g, '"' );
+    text = text.replace( /&lt;/g, '<' );
+    text = text.replace( /&amp;/g, '&' );
+
+    return text;
+}
+
+function text2html( text )
+{
+    var html = text.replace( /&/g,"&amp;");
+    html = html.replace( /"/g,"&quot;");
+    html = html.replace( /</g,"&lt;");
+
+    return html;
+}
diff --git a/kjsembed/docs/examples/html2text/html2text_plugin.xml b/kjsembed/docs/examples/html2text/html2text_plugin.xml
new file mode 100644
index 00000000..634b88cd
--- /dev/null
+++ b/kjsembed/docs/examples/html2text/html2text_plugin.xml
@@ -0,0 +1,24 @@
+<!DOCTYPE actionset>
+<actionset>
+<header>
+    <name>html2text_actions</name>
+    <label>HTML To Text Actions</label>
+    <script type="js" src="html2text_plugin.js"></script>
+</header>
+<action>
+    <name>html_to_text</name>
+    <type>KAction</type>
+    <icons>text</icons>
+    <label><text>Convert HTML To Text</text></label>
+    <statustext>Converts the selected text from HTML to text.</statustext>
+    <script type="js">kpart.selectedText = html2text( kpart.selectedText )</script>
+</action>
+<action>
+    <name>text_to_html</name>
+    <type>KAction</type>
+    <icons>html</icons>
+    <label><text>Quote For HTML</text></label>
+    <statustext>Quotes the selected text for inclusion in an HTML document.</statustext>
+    <script type="js">kpart.selectedText = text2html( kpart.selectedText )</script>
+</action>
+</actionset>
diff --git a/kjsembed/docs/examples/html2text/html2text_pluginui.rc b/kjsembed/docs/examples/html2text/html2text_pluginui.rc
new file mode 100644
index 00000000..7738100c
--- /dev/null
+++ b/kjsembed/docs/examples/html2text/html2text_pluginui.rc
@@ -0,0 +1,10 @@
+<!DOCTYPE kpartgui>

+<kpartplugin name="html2text_plugin" library="libkjsembedplugin">

+<MenuBar>

+ <Menu name="tools"><Text>&amp;Tools</Text>

+  <Action name="html_to_text"/>

+  <Action name="text_to_html"/>

+  <Action name="jsconsole"/>

+ </Menu>

+</MenuBar>

+</kpartplugin>

diff --git a/kjsembed/docs/examples/html2text/test.htm b/kjsembed/docs/examples/html2text/test.htm
new file mode 100644
index 00000000..457327d0
--- /dev/null
+++ b/kjsembed/docs/examples/html2text/test.htm
@@ -0,0 +1,208 @@
+&lt;html>
+&lt;head>
+&lt;style type=&quot;text/css&quot;>
+&lt;!--
+h1 {
+	background-color: #ccccee;
+	text-align: center;
+}
+h3 {
+	background-color: #ccccee;
+}
+li {
+	padding: 4px;
+}
+pre {
+	background-color: #CCCCCC;
+	margin-right: 16px;
+	margin-left: 16px;
+	padding: 6px;
+}
+.imgcaption {
+	font-weight: bold;
+	text-align: center;
+}
+.precaption {
+	font-weight: bold;
+	text-align: center;
+}
+-->
+&lt;/style>
+&lt;/head>
+&lt;body>
+&lt;h1> KJSEmbed&lt;/h1>
+&lt;h3>Introduction&lt;/h3>
+&lt;p>KJSEmbed is a library for embedding the KJS Javascript (ECMAScript) interpreter 
+  in KDE applications. It provides developers with an easy way to allow users 
+  to extend application, and can even be used with applications that have not 
+  been designed with this in mind thanks to a KParts plugin. In addition, KJSEmbed 
+  provides a command line tool for running scripts so users can easily create 
+  simple applications of their own in Javascript. KJSEmbed scripts are surprisingly 
+  powerful because they access the properties and slots of QObjects, and can even 
+  load widgets and dialogs created with Qt's graphical dialog editor.&lt;/p>
+&lt;h3>Features&lt;/h3>
+&lt;p>To give you an idea of what KJSEmbed provides, here is a brief summary of the 
+  more interesting features:&lt;/p>
+&lt;ul>
+  &lt;li>KParts plugin for extending existing KDE applications with scripts. &lt;/li>
+  &lt;li>KPart for embedding Javascript in your own applications.&lt;/li>
+  &lt;li>Console dialog that can be used to execute Javascript interactively.&lt;/li>
+  &lt;li>Command line tool for running scripts (this can even operate without an 
+    X server if you don't need to display a GUI).&lt;/li>
+  &lt;li>Define new KActions using XML.&lt;/li>
+  &lt;li>Scripts can access the properties and slots of QObjects as if they were 
+    normal Javascript properties and methods.&lt;/li>
+  &lt;li>Scripts can load dialogs and widgets created with Qt Designer.&lt;/li>
+  &lt;li>Scripts can create instances of anu QWidget subclass supported by QWidgetFactory.&lt;/li>
+  &lt;li>Making your own QObjects/QWidgets available for scripting is one-liner.&lt;/li>
+  &lt;li>Scripts can traverse the widget tree, so your entire application can be 
+    made scriptable without explicitly binding every object.&lt;/li>
+&lt;/ul>
+&lt;h3>First Steps - The Console Dialog&lt;/h3>
+&lt;p>The quickest way to see what KJSEmbed can do is with kjscmd, a tool for running 
+  scripts from the command line. To begin, we'll run kjscmd without any parameters 
+  which brings up the KJSEmbed console dialog. The console provides an easy way 
+  to run short (one line) scripts, as you can see in figure 1 the scripts have 
+  full access to the core Javascript language, and to standard objects such as 
+  Math. In addition to the standard Javascript operations, this screenshot also 
+  demonstrates the global function print() provided by KJSEmbed.&lt;/p>
+&lt;pre>
+-- Enter a JS expression and press enter --
+kjs> 10+20
+30
+kjs> print(&amp;quot;Hello World!&amp;quot;)
+Hello World!
+undefined
+kjs> Math.sin(0)
+0
+kjs> Math.cos(0)
+1
+&lt;/pre>
+&lt;p class=&quot;imgcaption&quot;>Figure 1: The KJSEmbed Console Dialog&lt;/p>
+&lt;p>Things get more interesting when you realise that we also have access to the 
+  widgets that make up the dialog, as you can in figure 2:&lt;/p>
+&lt;pre>
+kjs> console
+JSConsoleWidget (KJSEmbed::JSConsoleWidget)
+kjs> console.childCount()
+4
+kjs> console.childAt(1)
+CmdEdit (QComboBox)
+kjs> console.childAt(2)
+RunButton (QPushButton)
+kjs> console.child(&amp;quot;RunButton&amp;quot;)
+RunButton (QPushButton)
+kjs> console.child(&amp;quot;RunButton&amp;quot;).text = &amp;quot;Go!&amp;quot;
+Go!
+kjs> console.caption = &amp;quot;Different Title&amp;quot;
+Different Title
+kjs&amp;gt; console.child(&amp;quot;Title&amp;quot;).hide()
+undefined
+&lt;/pre>
+&lt;p class=&quot;imgcaption&quot;>Figure 2: Modifying the Console Dialog&lt;/p>
+&lt;p>As you can see, the console dialog has been made available to scripts as the 
+  global variable 'console'. We can access the child widgets that make up the 
+  dialog either by index using the childCount() and childAt() methods, or by name 
+  using the child() method. As well as being able to see the widgets, we can modify 
+  them by setting properties - in this example, we modify the caption property 
+  of the widget 'console' (changing the window title) and the text property of 
+  the widget 'RunButton' (changing the label it displays). For the sake of completeness, 
+  the final command illustrates the other way of modifying widgets available to 
+  us - it calls hide() slot of the widget 'Title' (what this does is left as an 
+  exercise for the reader).&lt;/p>
+&lt;h3>Displaying A Grep Dialog&lt;/h3>
+&lt;p>Now that we've seen how to use kjscmd interactively, lets take a look at a 
+  more complex example that displays a dialog for running grep. The complete script 
+  is shown in listing 1 and as you'll see, is very simple. Loading and displaying 
+  the dialog takes only two lines of code because KJSEmbed provides a built-in 
+  Factory object that supports Designer files, most of the work is getting the 
+  values out of the dialog and building the command line.&lt;/p>
+&lt;pre>
+// Create and show the dialog
+var dlg = Factory.loadui('grepdlg.ui');
+dlg.exec();
+
+// Extract the parameters
+var search = dlg.child('search_edit').text;
+var files = dlg.child('files_edit').text;
+var matchcase = dlg.child('case_check').checked;
+var invert =  dlg.child('invert_check').checked;
+
+// Build the command line
+var options;
+if ( matchcase ) {
+    options = '-i';
+}
+if ( invert ) {
+    options += ' -v';
+}
+
+cmd = 'grep '+options+&amp;quot;'&amp;quot;+search+&amp;quot;' &amp;quot;+files;
+
+// Print the command line
+print( cmd );
+&lt;/pre>
+&lt;p class=&quot;precaption&quot;>Listing 1: A Script That Displays the Grep Dialog&lt;/p>
+&lt;p>In order to find out what the user asked us to search for we need to extract 
+  the contents of the various fields in our dialog. We know that the field for 
+  entering the text to be searched for is a QLineEdit called 'search_edit', so 
+  we can use the child() method to get hold of it (this method searches through 
+  the children of an object until it finds one with a matching name). Once we've 
+  found the right object getting hold of the text is easy because all QLineEdits 
+  make their contents available as a property called 'text'. The code that gets 
+  the value of the check boxes is almost identical, except that these are QCheckBoxes 
+  so it's the 'checked' property we're interested in.&lt;/p>
+&lt;p align=&quot;center&quot;>&lt;img src=&quot;grepdlg.png&quot; alt=&quot;Grep Dialog Screenshot&quot; width=&quot;327&quot; height=&quot;241&quot;>&lt;/p>
+&lt;p class=&quot;imgcaption&quot;>Figure 3: The Grep Dialog&lt;/p>
+&lt;p>When this script is run you'll see a dialog like the one shown in figure 3.&lt;/p>
+&lt;h3>Extending Applications with Javascript Plugins&lt;/h3>
+&lt;p>As its name implies KJSEmbed is not just a tool for writing standalone Javascript 
+  tools, it also provides facilities for extending existing applications, these 
+  facilities being with a KParts plugin for running scripts. The next example 
+  uses the plugin to add a simple HTML-to-text action to Kate, the standard KDE 
+  editor. &lt;/p>
+&lt;pre>
+function html2text( html )
+{
+   var text = html.replace( /&amp;lt;[^&amp;gt;]*&amp;gt;/g, '' );
+   text = text.replace( /&amp;amp;quot;/g, '&amp;quot;' );
+   text = text.replace( /&amp;amp;lt;/g, '&amp;lt;' );
+   text = text.replace( /&amp;amp;amp;/g, '&amp;amp;' );
+   return text;
+}
+
+function text2html( text )
+{
+   var html = text.replace( /&amp;amp;/g,&amp;quot;&amp;amp;amp;&amp;quot;);
+   html = html.replace( /&amp;quot;/g,&amp;quot;&amp;amp;quot;&amp;quot;);
+   html = html.replace( /&amp;lt;/g,&amp;quot;&amp;amp;lt;&amp;quot;);
+   return html;
+}
+&lt;/pre>
+&lt;p>The details...&lt;/p>
+&lt;pre>&amp;lt;!DOCTYPE actionset&amp;gt;&lt;br>&amp;lt;actionset&amp;gt;&lt;br>&amp;lt;header&amp;gt;&lt;br>    &amp;lt;name&amp;gt;html2text_actions&amp;lt;/name&amp;gt;&lt;br>    &amp;lt;label&amp;gt;HTML To Text Actions&amp;lt;/label&amp;gt;&lt;br>    &amp;lt;script type=&amp;quot;js&amp;quot; src=&amp;quot;html2text_plugin.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;br>&amp;lt;/header&amp;gt;&lt;br>&amp;lt;action&amp;gt;&lt;br>    &amp;lt;name&amp;gt;html_to_text&amp;lt;/name&amp;gt;&lt;br>    &amp;lt;type&amp;gt;KAction&amp;lt;/type&amp;gt;&lt;br>    &amp;lt;icons&amp;gt;text&amp;lt;/icons&amp;gt;&lt;br>    &amp;lt;label&amp;gt;&amp;lt;text&amp;gt;Convert HTML To Text&amp;lt;/text&amp;gt;&amp;lt;/label&amp;gt;&lt;br>    &amp;lt;statustext&amp;gt;Converts the selected text from HTML to text.&amp;lt;/statustext&amp;gt;&lt;br>    &amp;lt;script type=&amp;quot;js&amp;quot;&amp;gt;kpart.selectedText = html2text( kpart.selectedText )&amp;lt;/script&amp;gt;&lt;br>&amp;lt;/action&amp;gt;&lt;br>&amp;lt;action&amp;gt;&lt;br>    &amp;lt;name&amp;gt;text_to_html&amp;lt;/name&amp;gt;&lt;br>    &amp;lt;type&amp;gt;KAction&amp;lt;/type&amp;gt;&lt;br>    &amp;lt;icons&amp;gt;html&amp;lt;/icons&amp;gt;&lt;br>    &amp;lt;label&amp;gt;&amp;lt;text&amp;gt;Quote For HTML&amp;lt;/text&amp;gt;&amp;lt;/label&amp;gt;&lt;br>    &amp;lt;statustext&amp;gt;Quotes the selected text for inclusion in an HTML document.&amp;lt;/statustext&amp;gt;&lt;br>    &amp;lt;script type=&amp;quot;js&amp;quot;&amp;gt;kpart.selectedText = text2html( kpart.selectedText )&amp;lt;/script&amp;gt;&lt;br>&amp;lt;/action&amp;gt;&lt;br>&amp;lt;/actionset&amp;gt;&lt;br>&lt;/pre>
+&lt;p>&lt;br>
+  The xmlgui:&lt;/p>
+&lt;pre>
+&amp;lt;!DOCTYPE kpartgui&amp;gt;&lt;br>&amp;lt;kpartplugin name=&amp;quot;html2text_plugin&amp;quot; library=&amp;quot;libkjsembedplugin&amp;quot;&amp;gt;&lt;br>&amp;lt;MenuBar&amp;gt;&lt;br> &amp;lt;Menu name=&amp;quot;tools&amp;quot;&amp;gt;&amp;lt;Text&amp;gt;&amp;amp;amp;Tools&amp;lt;/Text&amp;gt;&lt;br>  &amp;lt;Action name=&amp;quot;html_to_text&amp;quot;/&amp;gt;&lt;br>  &amp;lt;Action name=&amp;quot;text_to_html&amp;quot;/&amp;gt;&lt;br>  &amp;lt;Action name=&amp;quot;jsconsole&amp;quot;/&amp;gt;&lt;br> &amp;lt;/Menu&amp;gt;&lt;br>&amp;lt;/MenuBar&amp;gt;&lt;br>&amp;lt;/kpartplugin&amp;gt;&lt;br> &lt;/pre>
+&lt;h3>Missing&lt;/h3>
+&lt;ul>
+  &lt;li>XMLActions&lt;/li>
+  &lt;li>Plugin&lt;/li>
+  &lt;li>MainWindow&lt;/li>
+&lt;/ul>
+&lt;h3>References&lt;/h3>
+&lt;dl>
+  &lt;dt>&lt;a href=&quot;http://www.mozilla.org/js/language/&quot;>http://www.mozilla.org/js/language/&lt;/a>&lt;/dt>
+  &lt;dd>Javascript (ECMAScript) language information.&lt;/dd>
+&lt;/dl>
+&lt;h3>To Do&lt;/h3>
+&lt;ul>
+  &lt;li>Replace figures 1 and 2 with images&lt;/li>
+  &lt;li>&lt;/li>
+&lt;/ul>
+&lt;p>&amp;nbsp;&lt;/p>
+&lt;p>&amp;nbsp;&lt;/p>
+&lt;p>&amp;nbsp;&lt;/p>
+&lt;/body>
+&lt;/html>
diff --git a/kjsembed/docs/examples/html2text/text2html.js b/kjsembed/docs/examples/html2text/text2html.js
new file mode 100755
index 00000000..7e4311ca
--- /dev/null
+++ b/kjsembed/docs/examples/html2text/text2html.js
@@ -0,0 +1,9 @@
+#!/usr/bin/env kjscmd
+
+Factory.load('html2text_plugin.js');
+
+var line = readLine();
+while ( line != null ) {
+      print( text2html(line) );
+      line = readLine();
+}