Debian Codegraph @

doc/custom_plugins_en.html

raw
1 <?xml version="1.0" ?>
2 <!DOCTYPE html
3 PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
4 "DTD/xhtml1-strict.dtd">
5
6 <html xmlns="http://www.w3.org/1999/xhtml">
7 <head>
8 <link href="css/style.css" rel="stylesheet" type="text/css"/>
9 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
10 <title>Creating custom plugins for BKChem</title>
11 </head>
12 <body>
13 <h2>How to create a custom plugin for BKChem</h2>
14
15 <h3>What is a plugin</h3>
16
17 <p>From version <b>0.10.0-pre1</b> BKChem supports custom plugins, that is pieces of code that
18 can be inserted into BKChem without need of modification of the program. These are typically
19 written by users and provide some minor enhancements to the functionality of the program.</p>
20
21 <h3>How does BKChem handle plugins</h3>
22
23 <p>A BKChem plugin in general consists of two main parts. The first one is a short XML file that
24 describes the plugin. If you don't know anything about XML, just don't worry. It is so easy that even
25 I understand it :). The second part is a <a href="http://www.python.org">Python</a> script that
26 is the actual code of the plugin.</p>
27
28 <p>On startup BKChem searches in predefined directories (<i>plugins</i> directory in the BKChem installation
29 directory and <i>plugins</i> directory in the users <i>.bkchem</i> directory - located either in the installation
30 directory or the users HOME directory) and tries to read
31 all XML files (having extension .xml) and find if they describe some plugin. If yes, it performs
32 an action depending on the type of plugin.</p>
33
34 <p>At the time of writing of this document there are two distinct types of plugins that BKChem
35 supports. The default (and probably most interesting one) is the <b>script plugin</b>. For such
36 a plugin an entry into the menu is added and the plugin code is executed when the entry is
37 selected.</p>
38
39 <p>The second type of plugin is <b>mode plugin</b>. Modes are used in BKChem to provide different
40 types of actions to perform on the drawn objects. They are represented by the main toolbar of the
41 program. There is an "edit mode", "draw mode", "rotate mode" etc. A plugin of this type adds a
42 new mode to BKChem, enabling a new functionality. It is a little more complicated matter, because
43 it implies a deeper knowledge of BKChem to write such a plugin, and therefore is not described in
44 this material, yet.</p>
45
46
47 <h3>Writing a script plugin - brief tutorial</h3>
48
49 <h4>Foreword</h4>
50
51 <p>As mentioned above a plugin consist of two separate files - a XML document describing the
52 plugin and a Python script containing the actual code. In case of script plugin, the only file
53 that is read on BKChem startup is the XML file. If this file is successfully read, an entry is
54 added to the <i>Plugins</i> menu. The Python script is not executed until requested by the
55 user.</p>
56
57 <p>This fact has two major implications:</p>
58 <ul>
59 <li>a successful startup of BKChem and appearance of the
60 entry in BKChem menu does not mean the plugin will actually work
61 </li>
62 <li>each time you run the plugin from the menu, its source is re-read. This means that as long
63 as your plugin does not cause some inconsistencies in the internal state of the program, you
64 may debug and modify the plugin without restarting BKChem.
65 </li>
66 </ul>
67
68
69 <h4>The XML specification file</h4>
70
71 <p>The XML file describing the plugin is very short and simple as you can see on this
72 example:</p>
73
74
75 <pre>
76 &lt;?xml version="1.0" encoding="utf-8"?>
77
78 &lt;plugin>
79
80 &lt;meta>
81 &lt;author email="[email protected]">Beda Kosata&lt;/author>
82 &lt;description>
83 Finds all aromatic bonds in the current drawing (paper) and marks them
84 by setting their color to red.
85 &lt;/description>
86 &lt;/meta>
87
88 &lt;source>
89 &lt;file>red_aromates.py&lt;/file>
90 &lt;menu-text lang="en">Mark aromatic bonds&lt;/menu-text>
91 &lt;menu-text lang="cs">Označ aromatické vazby&lt;/menu-text>
92 &lt;/source>
93 &lt;/plugin>
94 </pre>
95
96
97
98 <p>The only necessary part is
99 content of the <b>&lt;source></b> tag, where the <b>&lt;file></b> tag says which file contains
100 the Python script and the <b>&lt;menu-text></b> tag says how the entry in the "Plugins" menu
101 for this plugin should be called.</p>
102
103 <p>The sample config file contains also a <b>meta</b> tag with information about the author and
104 the function of the plugin. It is considered good habit to provide these information if you are
105 going to distribute your plugins to other people. The description of the function of the plugin
106 will be shown in the program status-bar when the cursor is over the plugin menu entry.
107 </p>
108
109 <p>Both the <b>&lt;menu-text></b> and <b>&lt;description</b> elements may have an optional
110 <i>lang</i> attribute, that says in what language the text is. In this case more than one
111 such elements may be present with different <i>lang</i> attributes. BKChem will choose the one
112 that corresponds to the current language setting or uses the first one, if no matching language
113 is found.</p>
114
115 <h4>The Python script</h4>
116
117 <p>The heart (or maybe brain) of the plugin is the Python script. Inside this script you can use
118 any Python functions you want, there is no limit. <b>WARNING: Because of this, the plugins
119 present a possible threat to your computer. A plugin from an unknown source may delete all data
120 from you harddisk, send your private emails to strange people or even drink all your beer and
121 kick you out of your own house - you have been warned.</b></p>
122
123 <p>The way how the script communicates with BKChem is via a global variable <i>App</i> that
124 represents the instance of the BKChem application. You may call its methods, retrieve its
125 attributes etc.</p>
126
127 <p>Bellow is a sample script that find all aromatic bonds in all molecules present on the
128 current paper and sets their color to dark red.</p>
129
130 <pre>
131 # at first we cancel all selections
132 App.paper.unselect_all()
133
134 # App.paper is the current paper
135 # App.paper.molecules is a list of all molecules on this paper
136 for mol in App.paper.molecules:
137
138 # the aromaticity of bonds is not checked by default
139 # therefore we must at first call the mark_aromatic_bonds() method
140 mol.mark_aromatic_bonds()
141
142 # then we can loop over all the bonds
143 # and change the color of all the aromatic ones
144 for b in mol.bonds:
145 if b.aromatic:
146 b.line_color = "#aa0000"
147 b.redraw()
148 </pre>
149
150 <p>After the script finishes a new undo record is started automatically, therefor any changes by the plugin
151 are undoable in one step.</p>
152
153
154 <h4>Last word</h4>
155
156 <p>There are some sample plugins distributed together with BKChem (in the directory plugins
157 under the main BKChem directory (not the /bkchem/bkchem/plugins, but /bkchem/plugins). Some of
158 them are pretty simple, some a little more complex. Feel free to use them for studying or as
159 starting material for your own scripts.
160 </p>
161
162
163
164 </body>
165 </html>