From 90825e2392b2d70e43c7a25b8a3752299a933894 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: 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 --- kjsembed/docs/tutorial/grepdlg.png | Bin 0 -> 3236 bytes kjsembed/docs/tutorial/kjsembed.html | 213 ++++++++++++++++++++++++++ kjsembed/docs/tutorial/passwordfileviewdlg.ui | 205 +++++++++++++++++++++++++ 3 files changed, 418 insertions(+) create mode 100644 kjsembed/docs/tutorial/grepdlg.png create mode 100644 kjsembed/docs/tutorial/kjsembed.html create mode 100644 kjsembed/docs/tutorial/passwordfileviewdlg.ui (limited to 'kjsembed/docs/tutorial') diff --git a/kjsembed/docs/tutorial/grepdlg.png b/kjsembed/docs/tutorial/grepdlg.png new file mode 100644 index 00000000..b61bc511 Binary files /dev/null and b/kjsembed/docs/tutorial/grepdlg.png differ diff --git a/kjsembed/docs/tutorial/kjsembed.html b/kjsembed/docs/tutorial/kjsembed.html new file mode 100644 index 00000000..a304c3de --- /dev/null +++ b/kjsembed/docs/tutorial/kjsembed.html @@ -0,0 +1,213 @@ + + + + + +

KJSEmbed

+

Introduction

+

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.

+

Features

+

To give you an idea of what KJSEmbed provides, here is a brief summary of the + more interesting features:

+ +

First Steps - The Console Dialog

+

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.

+
+-- 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
+
+

Figure 1: The KJSEmbed Console Dialog

+

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:

+
+kjs> console
+JSConsoleWidget (KJSEmbed::JSConsoleWidget)
+kjs> console.childCount()
+4
+kjs> console.child(1)
+CmdEdit (QComboBox)
+kjs> console.child(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
+
+

Figure 2: Modifying the Console Dialog

+

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).

+

Displaying A Grep Dialog

+

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.

+
+// 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 );
+
+

Listing 1: A Script That Displays the Grep Dialog

+

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.

+

Grep Dialog Screenshot

+

Figure 3: The Grep Dialog

+

When this script is run you'll see a dialog like the one shown in figure 3.

+

Extending Applications with Javascript Plugins

+

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.

+
+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;
+}
+
+

The details...

+
<!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>
+


+ The xmlgui:

+
+<!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>
+

Missing

+ +

References

+
+
http://www.mozilla.org/js/language/
+
Javascript (ECMAScript) language information.
+
+

To Do

+ +

 

+

 

+

 

+ + + diff --git a/kjsembed/docs/tutorial/passwordfileviewdlg.ui b/kjsembed/docs/tutorial/passwordfileviewdlg.ui new file mode 100644 index 00000000..5ff8c59c --- /dev/null +++ b/kjsembed/docs/tutorial/passwordfileviewdlg.ui @@ -0,0 +1,205 @@ + +password_viewer + + QDialog + + name + password_viewer + + + geometry + + 0 + 0 + 493 + 357 + + + + caption + Password File Viewer + + + sizeGripEnabled + true + + + + margin + 11 + + + spacing + 6 + + + QLabel + + name + TextLabel1 + + + font + + 12 + 1 + + + + text + Password File Viewer + + + + Line + + name + Line1 + + + orientation + Horizontal + + + + + name + Spacer2 + + + orientation + Horizontal + + + sizeType + Expanding + + + sizeHint + + 20 + 20 + + + + + QPushButton + + name + PushButton5 + + + text + &Dismiss + + + + QListView + + + text + User Name + + + clickable + true + + + resizeable + true + + + + + text + Password + + + clickable + true + + + resizeable + true + + + + + text + User Id + + + clickable + true + + + resizeable + true + + + + + text + Group Id + + + clickable + true + + + resizeable + true + + + + + text + Real Name + + + clickable + true + + + resizeable + true + + + + + text + Home Directory + + + clickable + true + + + resizeable + true + + + + + text + Shell + + + clickable + true + + + resizeable + true + + + + name + view + + + + + + + -- cgit v1.2.1