-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathscriptrunner_help.py
245 lines (232 loc) · 8.16 KB
/
scriptrunner_help.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
"""
Help strings used in the plugin:
htmlhelp: HTML for the Help tab - deprecated; help now displayed in browser
htmlabout: HTML for the About tab
"""
def htmlhelp():
"""
Return the html used to populate the Help tab.
"""
return """<html>
<body>
<h2>Script Runner Help</h2>
<br>
<i>Run it like you own it</i>
<p>
<a href="#design">Design Options</a><br>
<a href="#requirements">Requirements for Your Script</a><br>
<a href="#working_with_scripts">Working with Scripts</a><br>
<a href="#editing_a_script">Editing a Script</a><br>
<a href="#passing_arguments">Passing Arguments</a></br>
</p>
<a name="design"/>
<p>
The Script Runner allows you to execute a script in QGIS to automate
a task. The script can use two approaches to access the QGIS API:
</p>
<ol>
<li>Use the qgis.utils.iface object</li>
<li>Import qgis.core and qgis.gui</li>
</ol>
<p>
In the first method, you are limited to to only those methods supported
by the QgisInterface class. In the second you have full access to the
PyQGIS API.
</p>
<a name="requirements"/>
<h4>Requirements</h4>
<p>
In order for Script Runner to execute your script you must define a
<em>run_script</em> function that accepts a single argument.
This is the standard entry point used by Script Runner. A reference to
the qgis.utils.iface object will be passed to your
<em>run_script</em> function.
You don't have to use the iface object in your script but your
<em>run_script</em> function must accept it as an argument.
</p>
<p>
Here is an example of a simple <em>run_script</em> function:
</p>
<pre>
def run_script(iface):
ldr = Loader(iface)
ldr.load_shapefiles('/vmap0_shapefiles')
</pre>
<p>
In this example, the <em>run_script</em> creates an instance (ldr) of a
class named Loader that is defined in the same source file. It then calls a
method in the Loader class named load_shapefiles to do something useful---in
this case, load all the shapefiles in a specified directory.
</p>
<p>
Alternatively, you could choose not to use classes and just do everything
within the <em>run_script</em> function, including having it call functions
in the same script or others you might import. The important thing is to be
sure you have defined a <em>run_script</em> function. If not, Script Runner
won't load your script.
</p>
<a name="working_with_scripts"/>
<h4>Working with Scripts</h4>
<p>
To run a script, you must add it to Script Runner using the <em>Add
Script</em> tool on the toolbar. This will add it to a list in the left
panel. This list of scripts is persisted between uses of QGIS. You can
remove a script using the <em>Remove Script</em> tool. This just removes it
from the list; it does nothing to the script file on disk.
</p>
<p>
Once you have a script loaded, you can click the <em>Script Info</em> tool
to populate the Info and Source tabs in the panel on the right. The Info tab
contains the docstring from your module and then a list of the classes,
methods, and functions found in the script. Having a proper docstring at the
head of your script will help you determine the puprose of script. </p>
<p>
You can view the source of the script on the Source tab. This allows you
to quickly confirm that you are using the right script and it does what you
think it will.
</p>
<a name="editing_a_script"/>
<h4>Editing a Script</h4>
<p>
The context menu (right-click on a script) has an <em>Edit script in external
editor</em> option---this will open the script in the default system
editor used for Python source files. If you wish to use a different editor,
you can enter the full path to the editor on the Preferences dialog.
</p>
<p>
This feature allows you to quickly make edits to your script during
development. Once edited, be sure to click the *Reload* button to pull in
the new version. You can leave the script open in your editor during the
edit->reload->run cycle.
</p>
<a name="passing_arguments"/>
<h4>Passing Arguments</h4>
<p>
You can pass one or more arguments to your script. Your <em>run_script</em>
function must include an argument preceded by <tt>**</tt>:
</p>
<pre>
def run_script(iface, **args):
</pre>
<p>
To run the script, click the <em>Run script with arguments</em> button and
enter the arguments in the form: key=value.
</p>
<p>
For example, if your script needs the path to a raster, you would enter the
argument as:
<pre>
path='/data/myraster.tif'
</pre>
<p>
In your <em>run_script</em> function you then access the path using:
</p>
<pre>
args['path']
</pre>
<p>
Arguments can be either numeric or string. Arguments are separated by commas
and all strings must be quoted. For example:
<pre>
buffer_size=100, path='/data/myvectors.shp'
</pre>
</body>
</html>"""
def htmlabout():
"""
Return the html used to populate the About tab.
"""
return """<html>
<body>
<h3>Script Runner - Version 2.0.1</h3>
<p>
Script Runner lets you run Python scripts in QGIS to automate and perform
repetitive tasks.
</p>
<p>
Author: Gary Sherman, Copyright © 2012-2013 GeoApt LLC</p>
<p>
Email:
<a href="mailto:[email protected]?Subject=Script Runner">
</p>
<p>
Repository: <a href="https://github.com/g-sherman/Script-Runner">
https://github.com/g-sherman/Script-Runner</a>
</p>
<p>
Bug Tracker: <a href="http://hub.qgis.org/projects/scriptrunner">
http://hub.qgis.org/projects/scriptrunner</a>
</p>
<p>
Please report issues and feature requests using the Bug Tracker.
</p>
<h4>Credits</h4>
<ul>
<li>Syntax highlighting taken from:
<a href="http://diotavelli.net/PyQtWiki/Python%20syntax%20highlighting">
http://diotavelli.net/PyQtWiki/Python%20syntax%20highlighting</a>
"Based on existing work by Carson Farmer and Christophe Kibleur, and an
example on the SciPres wiki."</li>
</ul>
<h4>Changelog</h4>
<ul>
<li>2.0.1</li>
<ul>
<li>New icons and bug fixes</li>
</ul>
</ul>
<ul>
<li>1.991</li>
<ul>
<li>Fix minor error when fetching the list of loaded scripts</li>
</ul>
</ul>
<ul>
<li>1.99</li>
<ul>
<li>Fix issues with scripts that are moved, renamed or deleted</li>
<li>Allow creation of a starter script by typing in a file name when adding a script</li>
<li>List of scripts is now sorted</li>
<li>Warning messages displayed in red in the console</li>
</ul>
</ul>
<ul>
<li>0.8</li>
<ul>
<li>Changes to work with the 2.0 API. No new features are implemented
in this version.</li>
</ul>
</ul>
<ul>
<li>0.71</li>
<ul>
<li>For mandatory arguments, prompt by name</li>
<li>A single run button is now used to run scripts with or without arguments</li>
<li>Fixed bug that prevented syntax highlighting from working when
reloading a script</li>
<li>Updated documentation</li>
<li>Moved help from tab to button that opens Sphinx doc in browser</li>
</ul>
</ul>
<ul>
<li>0.6</li>
<ul>
<li>Script output is logged to the Script Runner window<li>
<li>Script output can be logged to disk</li>
<li>Preferences dialog allows control of output and logging options</li>
<li>Exceptions in scripts are displayed without interfering with
console/logging output</li>
<li>Context menu (right-click) to access script functions</li>
<li>Edit script function uses system default editor or one you specify
in preferences</li>
<li>
<li>Arguments can be passed to a script using keyword arguments</li>
</ul>
<li>0.5</li>
<ul>
<li>Double-click on script to show info/source</li>
<li>Fix problem with info under master (issue #5034)</li>
</ul>
</body>
</html>"""