This paper discusses state, environments, tools, possibilities and further needs of KDE2 scripting. The language is kept as non-technical as possible to provide a introduction to users of the desktop. Examples are provided.
The release of kde2 2.2beta1 and koffice 1.1 beta3 lets one wonder how far kde is on the way to the business desktop. One part businesses relay on nowadays is scripting or call it automation. Unices are known for its very good scriptability through tools like the different terminals and environments like Perl or Python. KDE2 provides a easy access to application functionality by the DCOP interprocess communication protocol.
You should probably start by reading a little bit about DCOP at least the first section, "Model".
Technical: Server; Object; Function; Parameter; Parameter
Example: kdesktop; KDesktopIface; popupExecuteCommand; text; www.heise.de
In application: DCOPClient::registerAs() name; DCOPObject("KDesktopIface"); virtual void process()
Description:
Server: This is basically the application name. To have a server, the registration must be processed on application startup The Object: DCOPObject may have a name or not -> then you see a Hexadecimal number in kdcop 0x...
Function: This is a function in the DCOPObject
Parameter: This is used to define a parameter of a function
dcop kdesktop KDesktopIface popupExecuteCommand
bash
The "bourne again shell" allows scripting of DCOP through standard utilities (sed, ...) that are usually available on every Unix-type system [3, 4].
Python
Python is a part of all major Linux/Unix distributions and has a growing acceptance through the developer community. Its major advantage are the high level data types and the homogenous object orientation. There are bindings for xmlrpc, soap, Qt2 and soon kde2. For KDE2-developers theKompany provides the VeePee environment to python-script-enable programs [11]. Python is also used in the Zope application server [6, 7].
Perl
Probably the most commonly used scripting language on unices is perl. There are bindings for lots of standards. Since we use python this section might be extended by the appropriate people.
Uses the inter-process mechanisms provided by the used desktop environment.
DCOP
This is the inter-process communication service of KDE2. Since it is a integral part of KDE2 you can script DCOP enabled applications with all languages that have kde2 bindings or with the dcop utility [5] through the command line. Find a thorough description under [5].
DCOP-KAction-Bridge
This allows to automatically provide all KAction actions from within an application to the DCOP server with only initializing the DCOP server and the DCOPKActionProxy [14], Q7
DCOP-Qt-Bridge
This allows to automatically provide all Qt actions from within an application to the DCOP server with only initializing the DCOP server.
These scripting methods base on Internet/Intranet technologies and use them locally or globally. They mainly translate the xmlrpc/soap requests into DCOP.
xml-rpc
XML-RPC grew on the http-internet-standard and delivers its data by xml-structures.
ksoap
The discussion in [12] granroth@kde.org, the maker of kxmlrpc, and Dan Pilone suggested that it will follow not to far in the future. Check out http://apps.kde.com once in a while. It should come up. Since this would mean to implement some sort of DCOP handling scripting might also be possible then.
Issues for remote scripting
There are escaping issues for the slashes, hex-addresses and other special chars.
VeePee
This is a framework to simplify embedding of python scripting into applications by developers [11].
The steps for a developer to get VeePee integrated in the application.
VeePee provides more in depth scripting capabilities with more direct access to app-functionality and higher speed. On the other hand VeePee only supports app-bindings to Python.
This is done by recording mouse movements, mouse clicks and pressed keys. There is no complete macro recorder available.
The khotkeys utility is ported from kde1 to kde2 and lost most of its functionality. Right now it is configured through kmenuedit. Special functions seam to be possible through editing the khotkeysrc file. Documentation is not provided though.
A lot of automation tasks in office environments have to handle data. Database access is usually handled by ODBC and the likes. Since Qt will provide database plugins in Qt 3.0 (due in september 2001) any further development of database access from within koffice and kdebase applications (kword, kaddressbook) is stalled right now.
kdevelop
(checked kdevelop 3.0 aka Gideon 0.2 and kdevelop 2.0)
kdevelop does not add dcop interfaces to its application templates nor does it automatically generate DCOP-interfaces according to user interface files. Since a lot of functions of an application are triggered through UI-actions automated generation of DCOP-interfaces could ease development of DCOP functionality.
Gideon is designed to be a cross language development platform. Perl, Python and PHP are already supported with easily accessible tutorials and source code highlightning. This functionality combined with the upper suggestions and a kdcop enhanced for DCOP-KAction-Bridge and DCOP-Qt-Bridge function browsing gives kdevelop the potential to also be a script development environment for kde2 in the future.
A command line utility (cli)to browse dcop apps and functionality and execute dcop commands. Checkout the examples in listing 13.17 [8] or read man:dcop
In a terminal type (the # lines are remarks):
Example 1: We want to set a new location in the location bar. How do we explore this funcionality. This shows the konqueror DCOP-Qt Bridge
konqueror &
dcop
# do you see konqueror?
dcop konqueror
# this shows you all the modules. Some are browsable in kdcop, some are only accessible with dcop cli.
dcop konqueror qt
# only the objects are interesting here.
dcop konqueror qt objects | grep locationToolBar
# You see a list of Qt-DCOP-Bridged objects. The grep helps to sort out the interesting once.
# They are not browsable in kdcop. We select the obvious one.
dcop konqueror 'qt/konqueror-mainwindow#1/locationToolBar/history combo/combo edit'
# this shows us all Qt-functions to manipulate the combo edit box. you see, the setProperty and property functions are listed.
# we need to know two parameters for setProperty, one for property.
dcop konqueror 'qt/konqueror-mainwindow#1/locationToolBar/history combo/combo edit' properties
# one interesting property is "text".
dcop konqueror 'qt/konqueror-mainwindow#1/locationToolBar/history combo/combo edit' setProperty
# error. wrong parameters. but now which parameters are asked for?
# remember the text entry? it is not readonly, so let's write to it.
dcop konqueror 'qt/konqueror-mainwindow#1/locationToolBar/history combo/combo edit' setProperty text 'http://dot.kde.org'
# check your konqueror window, it has the new path now.
# click return and get the news.
dcop konqueror 'qt/konqueror-mainwindow#1/locationToolBar/history combo/combo edit' property sizeHint
# nice to know how big it is. try others yourself.
dcop konqueror 'qt/konqueror' slotClearLocationBar
# check the location bar. It's empty now :-).
# how did i find this? delete the last word and check.
Example 2:
dcop konqueror KonquerorIface openBrowserWindow www.heise.de
# that opens a new browser
Example 3:
kaddressbook &
# start the app first. In a script you must wait now to let the app time to startup.
dcop kaddressbook KAddressBookIface addEntry
# nice, isn't it
Example 4: Checkout the kword DCOPKActionProxy DCOP-KAction Bridge (works the same way with other programs)
kword &
# start kword
dcop kword default getViews
# the upper is needed that the following works.
dcop kword View-0 actions
# now you see all available actions
dcop kword View-0 action configure
# you get a pathname that you use in the next step
dcop kword View-0/action/configure activate
Hexadecimal Module Name
Some applications do not set a name for DCOP Modules (fixed by David Faure in kpresenter and kspread as of cvs 2001-07-17). Therefor there is one or more (if a dynamic module is loaded by executing a getView) DCOP-modules that have an arbitrary and changing hex number, which is in fact the address in memory. The address(es) change(s) with each start of the program. That does not prevent programability through scripts. Though scripts would first have to find out the actual number of the module where the function is. This is possible by executing e.g. a dcop kpresenter (hex addresses only in versions pre koffice 1.1) and get the address. It is unknown to the author if in python-xmlrpc a hexnumber could be used in a functioncall through escaping. The dcop command line utility works though and is useable through python too.
Unnamed Functions
It is mandatory to name actions. Though widgets, layouts, timers etc. do not have to be named and therefor often are left unnamed by developers. Sometimes interesting stuff might be left unnamed too. Since it is easy to fix, send a request with the dcop line of what you suggest to be named to the maintainer of the application. Try in terminal: dcop konqueror qt objects |grep locationToolBar
Guessing or knowing widgets
To explore a application thoroughly it is a good help to load the ui files into Qt-Designer and checkout the properties of the widgets of interest.
This application helps to get an quick overview about DCOP functionality in several programs. It is an easily useable visual browser. Use this utility for browsing the dcop interface of different applications.
This is a list to get a idea which apps DCOP Interfaces are easily browseable through the tool "kdcop".
Non: Application not listed in kdcop
(App does not register a dcop-server)
KPaint, KView, Aethera, KuickShow, KChart
Basic: Infrastructure functions and the Qt-Bridge are browsable
ark, KDict
Extended: Smaller Apps with some functionality browsable
Konqueror, KAddressbook, Kmail, Kicker, KOrganizer, KDict, noatun, KDict, KNotes, kicker: These smaller apps export a lot of their functionality to DCOP. Since complexity is low they are best suited for testing and learning as well as examples with great show-effect.
Strong: More functions and KAction-Bridge are browsable and named
(kpresenter and kspread both have named interfaces as off cvs 2001-07-17 or distribution koffice 1.1 final)
kpresenter, kspread, kword, Kivio: As the most mature of the koffice apps these provide an extensive DCOP function portfolio. The KAction interface loads after issuing e.g. dcop kword default getViews, restart kdcop afterwards.
Best check out the applications mentioned in the last chapter and start with knotes. If you have KDE2 2.2beat1 or earlier, start the application first, then start kdcop. In kdcop concentrate on the sub-entries getViews (to load a dynamic interface as in kword -- restart kdcop), actions (to see all the KAction-Bridged actions) and under qt objects (to view all the qt objects). Try doubleclicking the different functions and this way try execute them.
Integrate kdcop into gideon by makeing it a kde-part that allows gideon programmers to browse the running programs for allowed DCOP functions (probably a function description could be linked through lxr.kde.org or otherwise). kdcop would then send the command string in the different scripting languages to gideon (for e.g. c++ python, kxmlrpc or a comming soap).
The bindings on both sides (server kxmlrpc and client e.g. xmlrpclib.py) totally encapsulate the xml. But the data transfer has to be converted from and to xml. More capable DCOP-functions quite often need or return Qt or KDE specific data structures like ASYNC. Right now QStringList is about the most special data type [10] successfully to be used with python-xmlrpc.
There is some security checking to make sure that only a authorized scripts can access functionality. [13]
kxmlrpcd
in the terminal dcop (is kxmlrpcd listed?), else kxmlrpcd --help and kxmlrpcd -daemon
python
in the terminal python (do you get ">>>"?) exit with ctrl-d. Else install the RPMs from your distribution CD.
python-dcop and kxmlrpc
Script kxmlrpc-test.py
#!/usr/bin/python
# Copyright (C) 2001 Olaf M. Zanger <olaf.zanger@gmx.net> free to deliver under GPL if this header is kept.
from xmlrpclib import *
import os
import time
rc = open(os.environ['HOME'] + '/.kxmlrpcd', 'r')
config = string.split(rc.read(), ',')
port = config[0]
auth = config[1]
ex1 = os.system('noatun &')
time.sleep(3)
# wait until noatun is up and running
noatun = Server("http://localhost:" + port +"/noatun")
noatun.Noatun.playpause(auth)
time.sleep(3)
noatun.Noatun.play(auth)
Q1: What does a program need to do to provide some functionality via DCOP?
A1: The application needs to register with dcop on startup, inherit a class from DCOPObject, and name the object. This is shown in [1].
Q2: What is needed to implement a DCOP-Qt-Bridge?
A2: As long as the application registers with DCOP on startup.
nothing. it is part of every and each kde-program automatically.
Q3: If i browse with the dcop cli in the konqueror objects I see heaps of unnamed functions. Are these bugs? How can i find out about these?
A3: All objects are not named, that's not really a bug, that's life. Qt objects exist very independently from dcop, people didn't name all objects from the start. There are a lot of internal, non-interesting objects anyway.
Q4: Why do some objects have an arbitrary hex number (like 0x8234234) instead of a name?
A4: the developer forgot to name the DCOPObjects. you might submit a bug report to the appropriate person.
Q5: How do i find out about the parameters of a function?
(e.g. that "dcop konqueror 'qt/konqueror-mainwindow#1/locationToolBar/history combo/combo edit' setProperty text 'YEAH'" needs "text" as QCString)?
A5: Remove the last two parameters, you'll see how it is guessed. The setProperty function is listed there with the requested parameters. To see the properties, you simply call properties instead of setProperty. This way you can explore everything from the dcop command line tool, simply do it one step after the other (i.e. one word after the other in the command line).
Q6: With kdcop i can browse knotes dcop functions under "KNotesIface". Why is that impossible with knotes qt dcop functions?
A6: Functionality to browse the DCOP-KAction-Bridge and the DCOP-Qt-Bridge is not implemented in kdcop use dcop instead.
Q7: Briefly, what does a developer need to do to implement a DCOP-KAction-Bridge?
A7: The action bridge is in fact called "action proxy", and is activated using the KDCOPActionProxy class. For example, developers might study at konqueror's, or koffice's KoViewIface and KoDocumentIface [14].
Q8: I can't translate "dcop konqueror 'qt/konqueror' slotClearLocationBar" into the appropriate python kxmlrpc format?
A8: This is not about DCOP. You're hitting a python syntax problem (not solved though).
[1] http://kdelxr.nadmm.com/source/kdebase/kxmlrpc/test/testxmlrpc.cpp
[2] http://kdewebcvs.nebsllc.com/cgi-bin/cvsweb.cgi/kdebase/kxmlrpc/test/testxmlrpc.cpp
[3] http://kdelxr.nadmm.com/source/kdebase/kxmlrpc/test/testxmlrpc.sh
[4] http://kdewebcvs.nebsllc.com/cgi-bin/cvsweb.cgi/kdebase/kxmlrpc/test/testxmlrpc.sh
[5] http://www.andamooka.org/reader.pl?pgid=kde20develch13
[6] http://kdelxr.nadmm.com/source/kdebase/kxmlrpc/test/testxmlrpc.py
[7] http://kdewebcvs.nebsllc.com/cgi-bin/cvsweb.cgi/kdebase/kxmlrpc/test/testxmlrpc.py
[8] http://www.andamooka.org/reader.pl?pgid=kde20develch13lev1sec7
[9] http://www.pythonware.com/downloads/xmlrpc-0.9.8-990621.zip
[10] http://kdelxr.nadmm.com/source/kdebase/kxmlrpc/test/TESTING
[11] http://www.thekompany.com/projects/vp/overview.php3?dhtml_ok=0
[12] http://kt.zork.net/kde/kde20010629_16.html#2
[13] http://developer.kde.org/documentation/kde2arch/xmlrpc.html
[14] http://developer.kde.org/documentation/kde2arch/actionpattern.html
Olaf M. Zanger <Olaf.zanger@gmx.net>
The author worked with WinNT until he switched to SuSE Linux and KDE2 for development of web applications with Zope and PostgreSQL.
0.0.9 2001-07-16 gui-lords.org
First public release basing on very limited information and about 12h research.
0.1.7 2001-07-17 check
Checkthrough
I'd like to thank David Faure for his very responsive help (even at 2 am :-).
KWord koffice 1.1beta3, dcop, kdcop
Provided Examples
Bern, 2001-07-15. This document is provided as is with no warranties whatsoever. It may be distributed under the terms of the GPL Version 2.0 as long as this statement is provided. © Olaf M. Zanger <Olaf.zanger@gmx.net>