diff options
Diffstat (limited to 'doc/kstars/dcop.docbook')
| -rw-r--r-- | doc/kstars/dcop.docbook | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/kstars/dcop.docbook b/doc/kstars/dcop.docbook new file mode 100644 index 00000000..b17539bf --- /dev/null +++ b/doc/kstars/dcop.docbook @@ -0,0 +1,229 @@ +<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 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 +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> + |