summaryrefslogtreecommitdiffstats
path: root/kjsembed/docs/examples/html2text/test.htm
diff options
context:
space:
mode:
Diffstat (limited to 'kjsembed/docs/examples/html2text/test.htm')
-rw-r--r--kjsembed/docs/examples/html2text/test.htm208
1 files changed, 208 insertions, 0 deletions
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 @@
+<html>
+<head>
+<style type="text/css">
+<!--
+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;
+}
+-->
+</style>
+</head>
+<body>
+<h1> KJSEmbed</h1>
+<h3>Introduction</h3>
+<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.</p>
+<h3>Features</h3>
+<p>To give you an idea of what KJSEmbed provides, here is a brief summary of the
+ more interesting features:</p>
+<ul>
+ <li>KParts plugin for extending existing KDE applications with scripts. </li>
+ <li>KPart for embedding Javascript in your own applications.</li>
+ <li>Console dialog that can be used to execute Javascript interactively.</li>
+ <li>Command line tool for running scripts (this can even operate without an
+ X server if you don't need to display a GUI).</li>
+ <li>Define new KActions using XML.</li>
+ <li>Scripts can access the properties and slots of QObjects as if they were
+ normal Javascript properties and methods.</li>
+ <li>Scripts can load dialogs and widgets created with Qt Designer.</li>
+ <li>Scripts can create instances of anu QWidget subclass supported by QWidgetFactory.</li>
+ <li>Making your own QObjects/QWidgets available for scripting is one-liner.</li>
+ <li>Scripts can traverse the widget tree, so your entire application can be
+ made scriptable without explicitly binding every object.</li>
+</ul>
+<h3>First Steps - The Console Dialog</h3>
+<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.</p>
+<pre>
+-- Enter a JS expression and press enter --
+kjs> 10+20
+30
+kjs> print("Hello World!")
+Hello World!
+undefined
+kjs> Math.sin(0)
+0
+kjs> Math.cos(0)
+1
+</pre>
+<p class="imgcaption">Figure 1: The KJSEmbed Console Dialog</p>
+<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:</p>
+<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("RunButton")
+RunButton (QPushButton)
+kjs> console.child("RunButton").text = "Go!"
+Go!
+kjs> console.caption = "Different Title"
+Different Title
+kjs> console.child("Title").hide()
+undefined
+</pre>
+<p class="imgcaption">Figure 2: Modifying the Console Dialog</p>
+<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).</p>
+<h3>Displaying A Grep Dialog</h3>
+<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.</p>
+<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+"'"+search+"' "+files;
+
+// Print the command line
+print( cmd );
+</pre>
+<p class="precaption">Listing 1: A Script That Displays the Grep Dialog</p>
+<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.</p>
+<p align="center"><img src="grepdlg.png" alt="Grep Dialog Screenshot" width="327" height="241"></p>
+<p class="imgcaption">Figure 3: The Grep Dialog</p>
+<p>When this script is run you'll see a dialog like the one shown in figure 3.</p>
+<h3>Extending Applications with Javascript Plugins</h3>
+<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. </p>
+<pre>
+function html2text( html )
+{
+ var text = html.replace( /<[^>]*>/g, '' );
+ text = text.replace( /"/g, '"' );
+ text = text.replace( /</g, '<' );
+ text = text.replace( /&/g, '&' );
+ return text;
+}
+
+function text2html( text )
+{
+ var html = text.replace( /&/g,"&");
+ html = html.replace( /"/g,""");
+ html = html.replace( /</g,"<");
+ return html;
+}
+</pre>
+<p>The details...</p>
+<pre><!DOCTYPE actionset><br><actionset><br><header><br> <name>html2text_actions</name><br> <label>HTML To Text Actions</label><br> <script type="js" src="html2text_plugin.js"></script><br></header><br><action><br> <name>html_to_text</name><br> <type>KAction</type><br> <icons>text</icons><br> <label><text>Convert HTML To Text</text></label><br> <statustext>Converts the selected text from HTML to text.</statustext><br> <script type="js">kpart.selectedText = html2text( kpart.selectedText )</script><br></action><br><action><br> <name>text_to_html</name><br> <type>KAction</type><br> <icons>html</icons><br> <label><text>Quote For HTML</text></label><br> <statustext>Quotes the selected text for inclusion in an HTML document.</statustext><br> <script type="js">kpart.selectedText = text2html( kpart.selectedText )</script><br></action><br></actionset><br></pre>
+<p><br>
+ The xmlgui:</p>
+<pre>
+<!DOCTYPE kpartgui><br><kpartplugin name="html2text_plugin" library="libkjsembedplugin"><br><MenuBar><br> <Menu name="tools"><Text>&Tools</Text><br> <Action name="html_to_text"/><br> <Action name="text_to_html"/><br> <Action name="jsconsole"/><br> </Menu><br></MenuBar><br></kpartplugin><br> </pre>
+<h3>Missing</h3>
+<ul>
+ <li>XMLActions</li>
+ <li>Plugin</li>
+ <li>MainWindow</li>
+</ul>
+<h3>References</h3>
+<dl>
+ <dt><a href="http://www.mozilla.org/js/language/">http://www.mozilla.org/js/language/</a></dt>
+ <dd>Javascript (ECMAScript) language information.</dd>
+</dl>
+<h3>To Do</h3>
+<ul>
+ <li>Replace figures 1 and 2 with images</li>
+ <li></li>
+</ul>
+<p> </p>
+<p> </p>
+<p> </p>
+</body>
+</html>
generated by cgit v1.2.1 (git 2.18.0) at 2024-07-05 12:07:47 +0000