doc/kstars/dcop.docbook

   1 <chapter id="dcop">
   2 <title>Scripting KStars: The DCOP Interface</title>
   3 <para>
   4 One of the goals of &kstars; is to provide the ability to playback
   5 complicated behaviors from a script.  This will allow you to
   6 create <quote>virtual tours</quote> of the heavens, and will enable
   7 teachers to construct classroom demos to illustrate certain
   8 astronomical concepts.  It is already possible to write such scripts
   9 for &kstars;, although not all of the desired functions have been
  10 included.  Also, while we will eventually have a GUI-based script
  11 builder tool, the scripts must currently be written by hand.  This
  12 chapter will explain how to write &kstars; scripts.
  13 </para>
  14 <para>
  15 The &kde; architecture provides the necessary framework for scriptable
  16 applications via the <abbrev>DCOP</abbrev> interface.
  17 <abbrev>DCOP</abbrev> stands for <quote>Desktop Communication
  18 Protocol</quote>; through <abbrev>DCOP</abbrev>, &kde; applications
  19 can be controlled by other applications, from a terminal prompt, or
  20 through a text script.
  21 </para>
  22
  23 <sect1 id="dcop-interface">
  24 <title>DCOP Functions</title>
  25 <para>
  26 The &kstars; <abbrev>DCOP</abbrev> Interface includes the following
  27 functions:
  28
  29 <itemizedlist>
  30 <listitem><para><function>
  31 lookTowards( const QString direction )</function>:
  32 Point the display focus in a direction specified by the argument.
  33 This can be the name of any object in the sky, or one of the following
  34 directional words or abbreviations: zenith (or z), north (n),
  35 northeast (ne), east (e), southeast (se), south (s), southwest(sw),
  36 west(w), northwest (nw).
  37 </para></listitem>
  38
  39 <listitem><para><function>
  40 setRaDec( double ra, double dec )</function>:
  41 Point the display focus at the specified equatorial coordinates.
  42 </para></listitem>
  43
  44 <listitem><para><function>
  45 setAltAz(double alt, double az)</function>:
  46 Point the display focus at the specified horizontal coordinates.
  47 </para></listitem>
  48
  49 <listitem><para><function>
  50 zoomIn()</function>:
  51 Increase the display's Zoom level.
  52 </para></listitem>
  53
  54 <listitem><para><function>
  55 zoomOut()</function>:
  56 Decrease the display's Zoom level.
  57 </para></listitem>
  58
  59 <listitem><para><function>
  60 defaultZoom()</function>:
  61 Reset the display to Zoom level = 3 (the default).
  62 </para></listitem>
  63
  64 <listitem><para><function>
  65 setLocalTime(int yr, int mth, int day, int hr, int min, int sec)</function>:
  66 Set the simulation clock to the specified date and time.
  67 </para></listitem>
  68
  69 <listitem><para><function>
  70 waitFor( double t )</function>:
  71 Pause for t seconds before continuing with subsequent script commands.
  72 </para></listitem>
  73
  74 <listitem><para><function>
  75 waitForKey( const QString k )</function>:
  76 Halt the script execution until the user presses the specified key.
  77 At this point, you cannot specify combination keystrokes (such as
  78 <keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>); just use
  79 simple keys.  You can type <quote>space</quote> to indicate the
  80 spacebar.
  81 </para></listitem>
  82
  83 <listitem><para><function>
  84 setTracking( bool track )</function>:
  85 Toggle whether tracking mode is engaged.
  86 </para></listitem>
  87
  88 <listitem><para><function>
  89 changeViewOption( const QString option, const QString value )</function>:
  90 Adjust a view option.  There are dozens and dozens of options available;
  91 basically everything you can change in the <guilabel>Configure &kstars;
  92 Window</guilabel> can be changed here as well.  The first argument is
  93 the name of the option (the names are taken from the
  94 <filename>kstarsrc</filename> configuration file), and the second
  95 argument is the desired value.  The argument parser is designed to be
  96 robust, so if you accidentally send it bad data it should fail
  97 gracefully.
  98 </para></listitem>
  99
 100 <listitem><para><function>
 101 setGeoLocation( const QString city, const QString province,
 102 const QString country )</function>:
 103 Change the observing location to the specified city.  If no city matching
 104 the argument strings is found, then nothing happens.
 105 </para></listitem>
 106
 107 <listitem><para><function>
 108 stop()</function> [clock]:
 109 Halt the simulation clock.
 110 </para></listitem>
 111
 112 <listitem><para><function>
 113 start()</function> [clock]:
 114 Start the simulation clock.
 115 </para></listitem>
 116
 117 <listitem><para><function>
 118 setScale(float s)</function> [clock]:
 119 Set the rate of the simulation clock.  s=1.0 corresponds to real time;
 120 2.0 is twice as fast as real-time, etc.
 121 </para></listitem>
 122 </itemizedlist>
 123 </para>
 124 </sect1>
 125
 126 <sect1 id="dcop-test">
 127 <title>Testing the DCOP Functions</title>
 128 <para>
 129 You can try out the DCOP functions very easily using the
 130 <application>kdcop</application> program.  When you run
 131 <application>kdcop</application>, you will see a tree-list of all
 132 running programs; if &kstars; is running it will be listed.  Most of
 133 the <abbrev>DCOP</abbrev> functions are listed under the
 134 <quote>KStarsInterface</quote> heading, but the clock functions are
 135 listed under <quote>clock</quote>.  Double-click on any function to
 136 execute it.  If the function requires arguments, a window will open
 137 in which you can input the values.
 138 </para>
 139 </sect1>
 140
 141 <sect1 id="dcop-script">
 142 <title>Writing a DCOP Script</title>
 143 <para>
 144 <abbrev>DCOP</abbrev> functions can also be called from the UNIX
 145 command line, and these can be encapsulated in a script.  We will
 146 create an example script that switches to Equatorial coordinates,
 147 points the display at the Moon, zooms in a bit, and accelerates
 148 the clock to 1 hour per second.  After tracking the Moon
 149 for 20 seconds, the clock is paused and the display zooms out.
 150 You can use this script as a template for making new scripts.
 151 I will list the entire script first, and then explain its various
 152 parts.
 153 </para>
 154 <para>
 155 <programlisting>
 156 #!/bin/bash
 157 #KStars script: Track the Moon!
 158 #
 159 KSTARS=`dcopfind -a 'kstars*'`
 160 MAIN=KStarsInterface
 161 CLOCK=clock#1
 162 dcop $KSTARS $MAIN  changeViewOption UseAltAz false
 163 dcop $KSTARS $MAIN  lookTowards Moon
 164 dcop $KSTARS $MAIN  defaultZoom
 165 dcop $KSTARS $MAIN  zoomIn
 166 dcop $KSTARS $MAIN  zoomIn
 167 dcop $KSTARS $MAIN  zoomIn
 168 dcop $KSTARS $MAIN  zoomIn
 169 dcop $KSTARS $MAIN  zoomIn
 170 dcop $KSTARS $CLOCK setScale 3600.
 171 dcop $KSTARS $CLOCK start
 172 dcop $KSTARS $MAIN  waitFor  20.
 173 dcop $KSTARS $CLOCK stop
 174 dcop $KSTARS $MAIN  defaultZoom
 175 ##
 176 </programlisting>
 177 </para>
 178 <para>
 179 Save this script to a file.  The filename can be anything you like; I
 180 suggest something descriptive like
 181 <filename>trackmoon.kstars</filename>.  Then type the following command
 182 to make the script executable:
 183 <userinput><command>chmod</command> <option>a+x</option>
 184 <parameter>trackmoon.kstars</parameter>
 185 </userinput>.  The script can then be executed at any time by typing
 186 <userinput><command>./trackmoon.kstars</command></userinput> in the
 187 folder which contains the script.  Note that the script will only
 188 work if an instance of &kstars; is already running.  You can use the
 189 <command>dcopstart</command> command in a script to launch a new instance
 190 &kstars;.
 191 </para>
 192 <para>
 193 Now to the explanation of the script.  The top line identifies the file
 194 as a <command>BASH</command> shell script.  The following two lines
 195 are <firstterm>comments</firstterm> (any line beginning with
 196 <quote>#</quote> is a comment, and is ignored by the shell).  The next
 197 three lines define some convenience variables that will be used later.
 198 The <varname>KSTARS</varname> variable identifies the currently-running
 199 &kstars; process, using the <command>dcopfind</command> command.
 200 <varname>MAIN</varname> and <varname>CLOCK</varname> identify the
 201 two <abbrev>DCOP</abbrev> interfaces associated with &kstars;.
 202 </para>
 203 <para>
 204 The remainder of the script is the actual list of <abbrev>DCOP</abbrev>
 205 calls.  The first command sets the display to use Equatorial
 206 coordinates by setting the <quote>UseAltAz</quote> option to
 207 <quote>false</quote> (again, you can see a list of all options that
 208 <quote>changeViewOption</quote> can use by examining your
 209 <filename>kstarsrc</filename> configuration file).  The next command
 210 centers the display on the Moon, and automatically engages tracking.
 211 We then set the default zoom level, and then zoom in five times.
 212 Next, the clock's timescale is set to 1 hour per second (3600 seconds
 213 is one hour), and the clock is started (in case it was not already
 214 running).  The next line pauses the script for 20 seconds while we
 215 track the Moon as it moves across the sky.  Finally, we stop the clock
 216 and reset the zoom level to its default setting.
 217 </para>
 218 <para>
 219 We hope you enjoy the scripting abilities of KStars.  If you create an
 220 interesting script, please email it to
 221 <email>kstars@30doradus.org</email>; we would like to see what you have done,
 222 and may post some scripts on our webpage.  Also, if you have any
 223 ideas for how to improve scripting (or any part of &kstars;), let us
 224 know at <email>kstars-devel@lists.sourceforge.net</email> or submit a
 225 wishlist item to bugzilla.
 226 </para>
 227 </sect1>
 228 </chapter>
 229