From ce599e4f9f94b4eb00c1b5edb85bce5431ab3df2 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeedu@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/kstars/dcop.docbook | 229 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 doc/kstars/dcop.docbook (limited to 'doc/kstars/dcop.docbook') 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 @@ + +Scripting KStars: The DCOP Interface + +One of the goals of &kstars; is to provide the ability to playback +complicated behaviors from a script. This will allow you to +create virtual tours 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. + + +The &kde; architecture provides the necessary framework for scriptable +applications via the DCOP interface. +DCOP stands for Desktop Communication +Protocol; through DCOP, &kde; applications +can be controlled by other applications, from a terminal prompt, or +through a text script. + + + +DCOP Functions + +The &kstars; DCOP Interface includes the following +functions: + + + +lookTowards( const QString direction ): +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). + + + +setRaDec( double ra, double dec ): +Point the display focus at the specified equatorial coordinates. + + + +setAltAz(double alt, double az): +Point the display focus at the specified horizontal coordinates. + + + +zoomIn(): +Increase the display's Zoom level. + + + +zoomOut(): +Decrease the display's Zoom level. + + + +defaultZoom(): +Reset the display to Zoom level = 3 (the default). + + + +setLocalTime(int yr, int mth, int day, int hr, int min, int sec): +Set the simulation clock to the specified date and time. + + + +waitFor( double t ): +Pause for t seconds before continuing with subsequent script commands. + + + +waitForKey( const QString k ): +Halt the script execution until the user presses the specified key. +At this point, you cannot specify combination keystrokes (such as +&Ctrl;C); just use +simple keys. You can type space to indicate the +spacebar. + + + +setTracking( bool track ): +Toggle whether tracking mode is engaged. + + + +changeViewOption( const QString option, const QString value ): +Adjust a view option. There are dozens and dozens of options available; +basically everything you can change in the Configure &kstars; +Window can be changed here as well. The first argument is +the name of the option (the names are taken from the +kstarsrc 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. + + + +setGeoLocation( const QString city, const QString province, +const QString country ): +Change the observing location to the specified city. If no city matching +the argument strings is found, then nothing happens. + + + +stop() [clock]: +Halt the simulation clock. + + + +start() [clock]: +Start the simulation clock. + + + +setScale(float s) [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. + + + + + + +Testing the DCOP Functions + +You can try out the DCOP functions very easily using the +kdcop program. When you run +kdcop, you will see a tree-list of all +running programs; if &kstars; is running it will be listed. Most of +the DCOP functions are listed under the +KStarsInterface heading, but the clock functions are +listed under clock. Double-click on any function to +execute it. If the function requires arguments, a window will open +in which you can input the values. + + + + +Writing a DCOP Script + +DCOP 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. + + + +#!/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 +## + + + +Save this script to a file. The filename can be anything you like; I +suggest something descriptive like +trackmoon.kstars. Then type the following command +to make the script executable: +chmod +trackmoon.kstars +. The script can then be executed at any time by typing +./trackmoon.kstars 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 +dcopstart command in a script to launch a new instance +&kstars;. + + +Now to the explanation of the script. The top line identifies the file +as a BASH shell script. The following two lines +are comments (any line beginning with +# is a comment, and is ignored by the shell). The next +three lines define some convenience variables that will be used later. +The KSTARS variable identifies the currently-running +&kstars; process, using the dcopfind command. +MAIN and CLOCK identify the +two DCOP interfaces associated with &kstars;. + + +The remainder of the script is the actual list of DCOP +calls. The first command sets the display to use Equatorial +coordinates by setting the UseAltAz option to +false (again, you can see a list of all options that +changeViewOption can use by examining your +kstarsrc 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. + + +We hope you enjoy the scripting abilities of KStars. If you create an +interesting script, please email it to +kstars@30doradus.org; 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 kstars-devel@lists.sourceforge.net or submit a +wishlist item to bugzilla. + + + + -- cgit v1.2.1