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.
230 lines
8.6 KiB
230 lines
8.6 KiB
<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 behaviors 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 TQString 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 TQString 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 TQString option, const TQString 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 TQString city, const TQString province,
|
|
const TQString 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
|
|
centers 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>kstars@30doradus.org</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>kstars-devel@lists.sourceforge.net</email> or submit a
|
|
wishlist item to bugzilla.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|