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
246
247
248
|
<chapter id="dcop">
<title
>Scripting KStars: The DCOP Interface</title>
<para
>One of the goals of &kstars; is to provide the ability to playback complicated behaviours from a script. This will allow you to create <quote
>virtual tours</quote
> of the heavens, and will enable teachers to construct classroom demos to illustrate certain astronomical concepts. It is already possible to write such scripts for &kstars;, although not all of the desired functions have been included. Also, while we will eventually have a GUI-based script builder tool, the scripts must currently be written by hand. This chapter will explain how to write &kstars; scripts. </para>
<para
>The &kde; architecture provides the necessary framework for scriptable applications via the <abbrev
>DCOP</abbrev
> interface. <abbrev
>DCOP</abbrev
> stands for <quote
>Desktop Communication Protocol</quote
>; through <abbrev
>DCOP</abbrev
>, &kde; applications can be controlled by other applications, from a terminal prompt, or through a text script. </para>
<sect1 id="dcop-interface">
<title
>DCOP Functions</title>
<para
>The &kstars; <abbrev
>DCOP</abbrev
> Interface includes the following functions: <itemizedlist>
<listitem
><para
><function
> lookTowards( const QString direction )</function
>: Point the display focus in a direction specified by the argument. This can be the name of any object in the sky, or one of the following directional words or abbreviations: zenith (or z), north (n), northeast (ne), east (e), southeast (se), south (s), southwest(sw), west(w), northwest (nw). </para
></listitem>
<listitem
><para
><function
> setRaDec( double ra, double dec )</function
>: Point the display focus at the specified equatorial coordinates. </para
></listitem>
<listitem
><para
><function
> setAltAz(double alt, double az)</function
>: Point the display focus at the specified horizontal coordinates. </para
></listitem>
<listitem
><para
><function
> zoomIn()</function
>: Increase the display's Zoom level. </para
></listitem>
<listitem
><para
><function
> zoomOut()</function
>: Decrease the display's Zoom level. </para
></listitem>
<listitem
><para
><function
> defaultZoom()</function
>: Reset the display to Zoom level = 3 (the default). </para
></listitem>
<listitem
><para
><function
> setLocalTime(int yr, int mth, int day, int hr, int min, int sec)</function
>: Set the simulation clock to the specified date and time. </para
></listitem>
<listitem
><para
><function
> waitFor( double t )</function
>: Pause for t seconds before continuing with subsequent script commands. </para
></listitem>
<listitem
><para
><function
> waitForKey( const QString k )</function
>: Halt the script execution until the user presses the specified key. At this point, you cannot specify combination keystrokes (such as <keycombo action="simul"
>&Ctrl;<keycap
>C</keycap
></keycombo
>); just use simple keys. You can type <quote
>space</quote
> to indicate the spacebar. </para
></listitem>
<listitem
><para
><function
> setTracking( bool track )</function
>: Toggle whether tracking mode is engaged. </para
></listitem>
<listitem
><para
><function
> changeViewOption( const QString option, const QString value )</function
>: Adjust a view option. There are dozens and dozens of options available; basically everything you can change in the <guilabel
>Configure &kstars; Window</guilabel
> can be changed here as well. The first argument is the name of the option (the names are taken from the <filename
>kstarsrc</filename
> configuration file), and the second argument is the desired value. The argument parser is designed to be robust, so if you accidentally send it bad data it should fail gracefully. </para
></listitem>
<listitem
><para
><function
> setGeoLocation( const QString city, const QString province, const QString country )</function
>: Change the observing location to the specified city. If no city matching the argument strings is found, then nothing happens. </para
></listitem>
<listitem
><para
><function
> stop()</function
> [clock]: Halt the simulation clock. </para
></listitem>
<listitem
><para
><function
> start()</function
> [clock]: Start the simulation clock. </para
></listitem>
<listitem
><para
><function
> setScale(float s)</function
> [clock]: Set the rate of the simulation clock. s=1.0 corresponds to real time; 2.0 is twice as fast as real-time, etc. </para
></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="dcop-test">
<title
>Testing the DCOP Functions</title>
<para
>You can try out the DCOP functions very easily using the <application
>kdcop</application
> program. When you run <application
>kdcop</application
>, you will see a tree-list of all running programs; if &kstars; is running it will be listed. Most of the <abbrev
>DCOP</abbrev
> functions are listed under the <quote
>KStarsInterface</quote
> heading, but the clock functions are listed under <quote
>clock</quote
>. Double-click on any function to execute it. If the function requires arguments, a window will open in which you can input the values. </para>
</sect1>
<sect1 id="dcop-script">
<title
>Writing a DCOP Script</title>
<para
><abbrev
>DCOP</abbrev
> functions can also be called from the UNIX command line, and these can be encapsulated in a script. We will create an example script that switches to Equatorial coordinates, points the display at the Moon, zooms in a bit, and accelerates the clock to 1 hour per second. After tracking the Moon for 20 seconds, the clock is paused and the display zooms out. You can use this script as a template for making new scripts. I will list the entire script first, and then explain its various parts. </para>
<para>
<programlisting
>#!/bin/bash
#KStars script: Track the Moon!
#
KSTARS=`dcopfind -a 'kstars*'`
MAIN=KStarsInterface
CLOCK=clock#1
dcop $KSTARS $MAIN changeViewOption UseAltAz false
dcop $KSTARS $MAIN lookTowards Moon
dcop $KSTARS $MAIN defaultZoom
dcop $KSTARS $MAIN zoomIn
dcop $KSTARS $MAIN zoomIn
dcop $KSTARS $MAIN zoomIn
dcop $KSTARS $MAIN zoomIn
dcop $KSTARS $MAIN zoomIn
dcop $KSTARS $CLOCK setScale 3600.
dcop $KSTARS $CLOCK start
dcop $KSTARS $MAIN waitFor 20.
dcop $KSTARS $CLOCK stop
dcop $KSTARS $MAIN defaultZoom
##
</programlisting>
</para>
<para
>Save this script to a file. The filename can be anything you like; I suggest something descriptive like <filename
>trackmoon.kstars</filename
>. Then type the following command to make the script executable: <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>trackmoon.kstars</parameter
> </userinput
>. The script can then be executed at any time by typing <userinput
><command
>./trackmoon.kstars</command
></userinput
> in the folder which contains the script. Note that the script will only work if an instance of &kstars; is already running. You can use the <command
>dcopstart</command
> command in a script to launch a new instance &kstars;. </para>
<para
>Now to the explanation of the script. The top line identifies the file as a <command
>BASH</command
> shell script. The following two lines are <firstterm
>comments</firstterm
> (any line beginning with <quote
>#</quote
> is a comment, and is ignored by the shell). The next three lines define some convenience variables that will be used later. The <varname
>KSTARS</varname
> variable identifies the currently-running &kstars; process, using the <command
>dcopfind</command
> command. <varname
>MAIN</varname
> and <varname
>CLOCK</varname
> identify the two <abbrev
>DCOP</abbrev
> interfaces associated with &kstars;. </para>
<para
>The remainder of the script is the actual list of <abbrev
>DCOP</abbrev
> calls. The first command sets the display to use Equatorial coordinates by setting the <quote
>UseAltAz</quote
> option to <quote
>false</quote
> (again, you can see a list of all options that <quote
>changeViewOption</quote
> can use by examining your <filename
>kstarsrc</filename
> configuration file). The next command centres the display on the Moon, and automatically engages tracking. We then set the default zoom level, and then zoom in five times. Next, the clock's timescale is set to 1 hour per second (3600 seconds is one hour), and the clock is started (in case it was not already running). The next line pauses the script for 20 seconds while we track the Moon as it moves across the sky. Finally, we stop the clock and reset the zoom level to its default setting. </para>
<para
>We hope you enjoy the scripting abilities of KStars. If you create an interesting script, please email it to <email
>[email protected]</email
>; we would like to see what you have done, and may post some scripts on our webpage. Also, if you have any ideas for how to improve scripting (or any part of &kstars;), let us know at <email
>[email protected]</email
> or submit a wishlist item to bugzilla. </para>
</sect1>
</chapter>
|
