1
<section id="ctrl-write" xmlns:xi="http://www.w3.org/2001/XInclude">
2
<title>Writing Controls</title>
4
<section><title>Important Rules!</title>
6
<para>Before you start publishing controls, please thoroughly read these
7
rules. They make both your and the users' lives easier.</para>
10
<listitem>Before writing a new control, please check if the functionality
11
you need has already been implemented by somebody else. There's no point
12
in having two or more controls with different interfaces doing the same
15
<listitem>If there already is a control doing what you want, but you want
16
to make a more efficient implementation, please implement the interfaces
17
of the other control to ensure backwards compatibility.</listitem>
19
<listitem><emphasize>Never</emphasize> put applet-specific functionality
20
into a control! Controls are meant to be shared among applets.</listitem>
22
<listitem>Never publish a control without obeying rules 1 - 3!</listitem>
30
<section><title>Anatomy of Controls</title>
32
<para>Controls are Python classes derived from the <literal>Control</literal>
33
base class and from the interfaces which they implement. The base class
34
can be loaded from <literal>libdesklets.controls</literal>:</para>
37
from libdesklets.controls import Control
40
<para>Each control has its own directory, which at least consists of the
41
<filename>__init__.py</filename> file. That file initializes the control
42
and provides a function <function>get_class()</function> returning the
43
main class (not an instance of the class) of the control.</para>
45
<para>The typical directory structure of a control looks like:</para>
52
<para>The control directory has to include all interface files from which the
54
By convention, the filenames of interface files start with an
55
"<filename>I</filename>" to distinguish them from regular files.
56
The file <filename>__init__.py</filename> is also mandatory. If neccessary,
57
a control can also include other files as well, which are loaded by the
58
initialization file. You should, however, keep in mind to design controls
59
as generic as possible.</para>
64
<section><title>Deriving from Interfaces</title>
66
<para>Every control implements one or more interfaces. Since an interface
67
is a simple Python class, you just have to derive your control from the
68
interface classes:</para>
71
from libdesklets.controls import Control
72
from IMyInterface import IMyInterface
74
class MyControl(Control, IMyInterface):
78
Control.__init__(self)
84
def get_class(): return MyControl
87
<para>Because interfaces are implementation-less, there is no
88
super-constructor to invoke for them.</para>
90
<para>Always remember to derive from the <literal>Control</literal> class and
91
to invoke its constructor to get a valid control class.</para>
97
<section><title>Implementing Properties</title>
99
<para>Every property in the interfaces must be implemented by creating
100
appropriate <literal>property</literal> objects.</para>
102
<para>Python's <literal>property</literal> constructor takes four arguments,
103
of which are all optional. From the Python inline help:</para>
105
<programlisting><
added
removed
doc/book/ctrl-write.xml
