You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
214 lines
9.5 KiB
214 lines
9.5 KiB
<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 TQObjects, 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 TDEActions using XML.</li>
|
|
<li>Scripts can connect signals to slots.</li>
|
|
<li>Scripts can access the properties and slots of TQObjects 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 TQWidget subclass supported by TQWidgetFactory.</li>
|
|
<li>Making your own TQObjects/TQWidgets 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.child(1)
|
|
CmdEdit (TQComboBox)
|
|
kjs> console.child(2)
|
|
RunButton (TQPushButton)
|
|
kjs> console.child("RunButton")
|
|
RunButton (TQPushButton)
|
|
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 child() methods, or by name
|
|
using the child() method (you can also use getElementById() if you
|
|
want a DOM-style API. 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). Again,
|
|
there is a DOM-like way to do this - the setAttribute() and
|
|
getAttribute() methods. 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 TQLineEdit 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 TQLineEdits
|
|
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 TQCheckBoxes
|
|
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( /&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;
|
|
}
|
|
</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>TDEAction</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>TDEAction</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>&amp;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>
|
|
|