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.
379 lines
17 KiB
379 lines
17 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN
|
|
"http://www.w3.org/TR/html4/loose.dtd"">
|
|
<html>p
|
|
<head>
|
|
<title>Examples</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<meta name="GENERATOR" content="Quanta Plus">
|
|
</head>
|
|
<p>
|
|
<DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0">
|
|
<TR><TH COLSPAN="3" ALIGN="center">Python Bindings for KDE (PyKDE-3.16.0)</TH></TR>
|
|
<TR><TD WIDTH="10%" ALIGN="left" VALIGN="bottom"><A HREF="examples.html" ACCESSKEY="P">Prev</A></TD>
|
|
<TD WIDTH="80%" ALIGN="center" VALIGN="bottom"></TD>
|
|
<TD WIDTH="10%" ALIGN="right" VALIGN="bottom"><A HREF="limits.html" ACCESSKEY="N">Next</A></TD>
|
|
</TR>
|
|
</TABLE><HR ALIGN="LEFT" WIDTH="100%"></DIV>
|
|
|
|
<h1>DCOP and Extensions</h1>
|
|
<p>
|
|
DCOP is KDE's acronym for it's "Desktop Communications-Oriented Protocol" - basically a
|
|
lightweight and simple mechanism for inter-process communications (IPC). DCOP allows two
|
|
running applications to exchange messages or other information or exercise control over
|
|
each other.
|
|
</p>
|
|
<p>
|
|
While the DCOP implementation is convenient for C++ programmers, it presents some difficulties
|
|
for Python programmers. The DCOP extensions that have been added to PyKDE should make most
|
|
DCOP applications (either DCOP-client or DCOP-enabled applications) simple to write and
|
|
reliable to run
|
|
</p>
|
|
<h2>What Extensions?</h2>
|
|
There are three basic extensions added to PyKDE that are not part of KDE itself:
|
|
<dl>
|
|
<dt>Packing/Unpacking QByteArrays</dt>
|
|
<dd>
|
|
DCOP passes data between applications using QByteArrays. QByteArrays can be difficult to
|
|
pack or unpack using PyQt or PyKDE, so PyKDE has additional methods (dcop_add and dcop_next)
|
|
to make these operations simpler in Python
|
|
</dd>
|
|
<dt>Client Extensions</dt>
|
|
<dd>
|
|
PyKDE's DCOP client extensions make it easy and natural to call DCOP methods in other
|
|
DCOP-enabled applications - the application or DCOP object being referenced look like
|
|
Python classes, and the method being called looks to the programmer like a Python method.
|
|
</dd>
|
|
<dt>DCOP Enabling (Export) Extensions</dt>
|
|
<dd>
|
|
Another set of extensions makes it trivial to expose an application's methods via DCOP to
|
|
other applications. All that is required is to subclass a pre-written Python class and
|
|
provide a list of the methods to expose, along with a method signature listing the name
|
|
of the method, it's return type, and the the types of its arguments.
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
The methods for packing/unpacking QByteArrays are available to the programmer, but are
|
|
primarily used transparently by the other PyKDE DCOP extensions. The client and export extensions
|
|
are two Python modules that are included and installed as part of PyKDE.
|
|
</p>
|
|
|
|
<h2>Calling DCOP Methods</h2>
|
|
<p>
|
|
Accessing a DCOP method in another application requires 3 pieces of information: the name of
|
|
the application to be accessed, the name of the DCOP object which holds the method to be
|
|
called, and the name of the method itself.
|
|
</p>
|
|
|
|
<h3>Collection the Information</h3>
|
|
<p>
|
|
The easiest way to collect the required information is to use the kdcop application that
|
|
comes with PyKDE. kdcop is graphical application that looks like the image shown.
|
|
</p>
|
|
<IMG src="images/kdcop1.png" align="middle" border="0">
|
|
<h3>Application/Object/Method Information</h3>
|
|
<p>
|
|
Look at the entry for kicker, which has been expanded in the image. Underneath kicker (the
|
|
application name - kicker is the panel on the standard KDE screen) is a list of DCOP objects,
|
|
for example, Panel. Under each object is a list of methods the application/object exposes, for
|
|
example, "int panelPosition ()". This indicates the method panelPosition takes no arguments
|
|
and returns an integer.
|
|
</p>
|
|
<h3>Writing the Code</h3>
|
|
<p>
|
|
There are two ways to use the DCOP extensions to call the panelPosition method. The first is
|
|
from the application level, the second is from the object level. We can use the "application
|
|
level" in this case, because the object name "Panel" can be valid Python identifier (not all
|
|
object names have this property).
|
|
</p>
|
|
<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%">
|
|
<TR><TD><PRE CLASS="PROGRAMLISTING">
|
|
import dcopext
|
|
# ! other imports not shown !
|
|
|
|
app = KApplication ()
|
|
dcop = app.dcopClient ()
|
|
|
|
d = dcopext.DCOPApp ("kicker", dcop)
|
|
ok, panelPos = d.Panel.panelPosition ()
|
|
|
|
</PRE></TD></TR></TABLE>
|
|
<p>
|
|
That's all there's to it in this case. We import dcopext, which contains the client extension
|
|
classes; from the KApplication instance, we "borrow" the DCOPClient instance (dcop); we create a
|
|
DCOPApp instance, passing it the name of the app ("kicker") and the DCOPClient instance; we
|
|
call kicker's Panel object's panelPosition method (d.Panel.panelPosition); lastly, the integer
|
|
value is returned to our application (panelPos) as the second item in a tuple - the first element
|
|
of the tuple (ok) is a boolean value indicating whether the call succeeded (True) or failed (False).
|
|
</p>
|
|
<p>
|
|
Many of the DCOP object names can't be used as Python identifiers (for example,"0x8239ae0" or
|
|
KIO::Scheduler in kicker, or EditInterface#1, which kwrite exports). In that case, it's
|
|
necessary to write the code at the object level, constructing a DCOPObj instead of a
|
|
DCOPApp (DCOPApp actually constructs a DCOPObj behind the scenese in the example above).
|
|
</p>
|
|
<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%">
|
|
<TR><TD><PRE CLASS="PROGRAMLISTING">
|
|
import dcopext
|
|
# ! other imports not shown !
|
|
|
|
o = dcopext.DCOPObj ("kicker", dcop, "Panel")
|
|
ok, panelPos = o.panelPosition ()
|
|
|
|
</PRE></TD></TR></TABLE>
|
|
<p>
|
|
In this example, 'o' is a DCOPObj. In constructing 'o', we add a string representation of
|
|
the name of the object ("Panel") to the application name and DCOPClient object. We then
|
|
use the DCOPObj 'o' to call the the method (panelPosition) that the object supports.
|
|
</p>
|
|
<h3>More on Application Names</h3>
|
|
<p>
|
|
In the example above, kicker was the name of the application and the id we used to reference
|
|
the application as well. kicker is an example of a unique application - only one instance of
|
|
kicker can be running at any time.
|
|
</p>
|
|
<p>
|
|
Many applications (konqueror, for example) can have several instances running at the same
|
|
time. kdcop would display multiple instances like this:
|
|
</p>
|
|
<IMG src="images/kdcop2.png" border="0">
|
|
<p>
|
|
kdcop shows 3 instances of konqueror running in the example above. To perform a DCOP call in
|
|
this case, we'd need to know which instance of konqueror we want to send the call to. The
|
|
suffix on each instance of konqueror is the PID of the instance running. We simply pass the
|
|
full id (app name + pid - eg konqueror-14409) when constructing DCOPApp or DCOPObj.
|
|
</p>
|
|
<p>
|
|
If you instantiate the application you want to communicate with from your own application (that
|
|
will be making the DCOP calls), methods like KApplication.startServiceByDesktopName will
|
|
let you start the app and also return both the PID of the started app and the complete
|
|
identifier string needed to initiate DCOP communications. The identifier's name portion may or
|
|
may not be the same as the name of the application (see the example_dcopexport.py example program,
|
|
whose ID is "petshop-####" (#### is the PID of the application instance).
|
|
</p>
|
|
<h3>Data Types</h3>
|
|
The DCOP extensions will support any of the following C++ data types:
|
|
<table><TR><TD>char</TD><TD>short</TD><TD>int</TD></TR>
|
|
<TR><TD>long</TD><TD>unsigned char</TD><TD>unsigned short</TD></TR>
|
|
<TR><TD>unsigned int</TD><TD>unsigned long</TD><TD>uchar</TD></TR>
|
|
<TR><TD>ushsort</TD><TD>uint</TD><TD>ulong</TD></TR>
|
|
<TR><TD>Q_INT32</TD><TD>pid_t</TD><TD>float</TD></TR>
|
|
<TR><TD>double</TD><TD>QString</TD><TD>QStringList</TD></TR>
|
|
<TR><TD>QCString</TD><TD>KURL</TD><TD>KURL::List</TD></TR>
|
|
<TR><TD>QSize</TD><TD>QRect</TD><TD>QRegion</TD></TR>
|
|
<TR><TD>QFont</TD><TD>QCursor</TD><TD>QPixmap</TD></TR>
|
|
<TR><TD>QColor</TD><TD>QColorGroup</TD><TD>QPalette</TD></TR>
|
|
<TR><TD>QBrush</TD><TD>QWidget::FocusPolicy</TD><TD>DCOPRef</TD></TR>
|
|
<TR><TD>QVariant</TD><TD>QDate</TD><TD>QTime</TD></TR>
|
|
<TR><TD>QDateTime</TD><TD>QImage</TD><TD>QKeySequence</TD></TR>
|
|
<TR><TD>QPen</TD><TD>QPicture</TD><TD>QPointArray</TD></TR>
|
|
<TR><TD>QValueList<DCOPRef></TD><TD>QValueList<QCString></TD><TD>QMap<QCString,DCOPRef></TD></TR>
|
|
<TR><TD>QMap<QCString,DCOPRef></TD><TD></TD><TD></TD></TR>
|
|
</table>
|
|
<p>
|
|
Data conversion between C++ and Python types is done transparently. The integer types
|
|
map to Python int or Python long, the decimal types to Python double. A Python string
|
|
can be used for any argument that requires a QString or QCString (return types will
|
|
always be the Qt object type). The QValueList types take or return a Python list of the
|
|
indicated object. The QMap types take or return a Python dict with the first type as
|
|
the key and the second type as data. All other types use the same object type in
|
|
Python and Qt (for instance, QPoint or QStringList).
|
|
</p>
|
|
<p>
|
|
It's possible to add support for more types in the future. To be added, a type requires
|
|
a pair of overloaded QDataStream operators ("<<" and ">>"). Types must also
|
|
exist in the libs that PyQt and PyKDE support - types specific to applications (like
|
|
konqueror) cannot be supported at this time.
|
|
</p>
|
|
<h3>Other Extension Features</h3>
|
|
<p>
|
|
The dcopext module consists of 3 classes (DCOPApp, DCOPObj and DCOPMeth) corresponding to
|
|
applications, objects and methods respectively. These classes have additional variables and methods:
|
|
<ul>
|
|
<li> DCOPApp.objects - returns a list of the applications DCOP objects. example: d.objects</li>
|
|
<li> DCOPApp.object(objname) - returns a DCOPObj for the DCOPObject. example: d.object ("Panel")</li>
|
|
<li> DCOPObj.methods - returns a list of the methods and object has. example: o.methods</li>
|
|
<li> DCOPObj.method (methname) - returns an DCOPMeth instance corresponding to the method, which
|
|
can be called. example: o.method("panelPosition")</li>
|
|
<li> DCOPMeth.valid - returns whether the method is valid or not (True/False). example:
|
|
d.Panel.panelPosition.valid</li>
|
|
<li>DCOPMeth.rtype - a method's return type. example d.Panel.panelPosition.rtype</li>
|
|
<li>DCOPMeth.argtypes - a list of the method's argument types. example d.Panel.panelPosition.argtypes</li>
|
|
<li>DCOPMeth.argnames - a list of the method's argument names. example d.Panel.panelPosition.argnames</li>
|
|
</ul>
|
|
<p>
|
|
If a method isn't valid, it's rtype, argtypes and argnames values will all be None.
|
|
</p>
|
|
</p>
|
|
<h2>DCOP Enabling a Python Application</h2>
|
|
<p>
|
|
Enabling a Python application to handle DCOP calls is even simpler than making calls as a
|
|
DCOP client. Suppose a Python application has two methods we want to appear as int getValue()
|
|
and void setValue(int). The corresponding Python methods are get_value() set_value(i).
|
|
We want to export these methods under the object "Value". Here's the code:
|
|
</p>
|
|
<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%">
|
|
<TR><TD><PRE CLASS="PROGRAMLISTING">
|
|
from dcopexport import DCOPExObj
|
|
# ! other imports not shown !
|
|
|
|
class ValueObject (DCOPExObj):
|
|
def __init__ (self, id="Value"):
|
|
DCOPExObj.__init__ (self, id)
|
|
self.value = 0
|
|
|
|
self.addMethod ("int getValue()", self.get_value)
|
|
self.addMethod ("void setValue(int)", self.set_value)
|
|
|
|
def get_value(self):
|
|
return self.value
|
|
|
|
def set_value (self, i):
|
|
self.value = i
|
|
|
|
</PRE></TD></TR></TABLE>
|
|
<p>
|
|
Note that the module for the DCOPExObj class is "dcopexport". The Python methods may be
|
|
part of the DCOPExObj subclass, part of another class, or global Python functions. They
|
|
must be callable from the DCOPExObj subclass being created. The dcopexport extension takes
|
|
care of everything else, including the "functions()" method which applications (yours or
|
|
kdcop, for example) can call to find out which methods are available and their return
|
|
and argument types. You can have multiple instances of DCOPExObj in a program. All of
|
|
the data types listed above are supported transparently - you don't have to pack or
|
|
unpack QByteArrays.
|
|
</p>
|
|
<h2>Packing and Unpacking QByteArrays</h2>
|
|
<p>
|
|
NOTE: It isn't necessary to use the dcop_add and dcop_next functions or worry about
|
|
QByteArrays at all when using dcopext or dcopexport as shown above. Those modules
|
|
handle the packing and unpacking details automatically behind the scenes.
|
|
</p>
|
|
<p>
|
|
The dcop_add and dcop_next functions are available in the PyKDE tdecore module (they
|
|
may be relocated to a different module in the future). They use a QDataStream to operate
|
|
on a QByteArray. The QByteArray can be thought of as a stack (a FIFO stack though) -
|
|
dcop_add pushes objects onto the stack, dcop_next pops objects off the stack. The first
|
|
object popped off will be the first object pushed on, etc.
|
|
</p>
|
|
<p>
|
|
The dcop_add function is actually a group of overloaded functions, some of which take
|
|
different argument counts. Here are some examples:
|
|
</p>
|
|
<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%">
|
|
<TR><TD><PRE CLASS="PROGRAMLISTING">
|
|
from tdecore import dcop_add, dcop_next
|
|
from qt import QByteArray, QDataStream, IO_ReadOnly, IO_WriteOnly, QString,\
|
|
QCString, QValueList<QCString>
|
|
from dcopext import numericTypes, stringTypes
|
|
|
|
b = QByteArray ()
|
|
s = QDataStream (b, IO_WriteOnly)
|
|
|
|
i = 6
|
|
d = 3.14
|
|
t = QString ("Hello, World")
|
|
x = QCString ("One")
|
|
y = QCString ("Two")
|
|
z = QCString ("Three")
|
|
l = [x, y, z]
|
|
|
|
dcop_add (s, i, "long")
|
|
dcop_add (s, d, "double")
|
|
dcop_add (s, t)
|
|
dcop_add (s, x)
|
|
dcop_add (s, l, "QValueList<QCString>")
|
|
|
|
</PRE></TD></TR></TABLE>
|
|
<p>
|
|
Notice that for numeric types (integer or decimal) an additional string is needed to
|
|
specify the C++ type of the object - that's because Python has only 3 basic numeric
|
|
types, while C++ has at least 10 basic numeric types plus variations via typedefs.
|
|
</p>
|
|
<p>
|
|
Also, the QValueList (and QMap - not shown) type needs a qualifier - a Python list
|
|
type doesn't know (or care) what the type of its elements is.
|
|
</p>
|
|
<p>
|
|
Other types (QString, QCString) are uniquely typed, so no modifier is needed.
|
|
</p>
|
|
<p>
|
|
While it may change in the future, dcop_add right now retains the variable argument lists.
|
|
You can handle this in your own code easily if you import "numericTypes" and
|
|
"stringTypes" from dcopext as shown above. The following code will sort things out:
|
|
</p>
|
|
|
|
<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%">
|
|
<TR><TD><PRE CLASS="PROGRAMLISTING">
|
|
# atype is the type of the argument being processed (as a string)
|
|
# value is the object being packed into the QByteArray
|
|
|
|
if atype in numericTypes:
|
|
dcop_add (s, value, atype)
|
|
elif atype in stringTypes and isinstance (value, str):
|
|
dcop_add (s, eval ("%s('%s')" % (atype, value)))
|
|
elif atype.startswith ("QMap") or atype.startswith ("QValueList"):
|
|
dcop_add (params, value, atype)
|
|
else:
|
|
dcop_add (s, value)
|
|
|
|
</PRE></TD></TR></TABLE>
|
|
<p>
|
|
At least in DCOP related applications, all of the necessary type information is always
|
|
easily available. The first if clause above processes numeric types; the second if
|
|
clause allows you to use Python strings in place of Qt's QString or QCString types; the
|
|
third if clause handles QValueList and QMap based types; the else clause handles
|
|
everything else.
|
|
</p>
|
|
<p>
|
|
Unpacking a QByteArray is simpler - dcop_next always takes a QDataStream instance and
|
|
a type name string. The code below assumes the same set of imports as above:
|
|
</p>
|
|
<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%">
|
|
<TR><TD><PRE CLASS="PROGRAMLISTING">
|
|
|
|
# b is a QByteArray to be unpacked
|
|
s = QDataStream (b, IO_ReadOnly)
|
|
|
|
i1 = dcop_next (s, "long")
|
|
d1 = dcop_next (s, "double")
|
|
t1 = dcop_next (s, "QString")
|
|
x1 = dcop_next (s, "QCString")
|
|
l1 = dcop_next (s, "QValueList<QCString>")
|
|
|
|
</PRE></TD></TR></TABLE>
|
|
<p>
|
|
Of course the type specified in dcop_next to unpack the object must match the type of
|
|
the object originally packed, and must happen in the same order (you can't use this to cast or convert types). i1, d1, etc
|
|
should contain the same values as i, d, etc above.
|
|
</p>
|
|
<p>
|
|
The types that dcop_add/dcop_next can handle are the same types listed in the dcopext
|
|
section above.
|
|
</p>
|
|
<h2>Thanks</h2>
|
|
<p>
|
|
The code for dcopext and dcopexport is based on pydcop.py and pcop.cpp written by Torben Weis
|
|
and Julian Rockey. It's available in the dcoppython/ section of the kde-bindings source code,
|
|
and can be used to implement DCOP communication without using PyQt or PyKDE.
|
|
</p>
|
|
|
|
<DIV CLASS="NAVFOOTER">
|
|
<HR ALIGN="LEFT" WIDTH="100%">
|
|
<TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" >
|
|
<TR>
|
|
<TD WIDTH="33%" ALIGN="left" VALIGN="top"><A HREF="examples.html" ACCESSKEY="P">Prev</A></TD>
|
|
<TD WIDTH="34%" ALIGN="center" VALIGN="top"><A HREF="index.html" ACCESSKEY="H">Home</A></TD>
|
|
<TD WIDTH="33%" ALIGN="right" VALIGN="top"><A HREF="limits.html" ACCESSKEY="N">Next</A></TD>
|
|
</TR>
|
|
<TR>
|
|
<TD WIDTH="33%" ALIGN="left" VALIGN="top">Templates and Example Programs</TD>
|
|
<TD WIDTH="34%" ALIGN="center" VALIGN="top"> </TD>
|
|
<TD WIDTH="33%" ALIGN="right" VALIGN="top">General Limitations</TD>
|
|
</TR>
|
|
</TABLE>
|
|
</DIV>
|
|
|
|
</body>
|
|
</html>
|