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

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>
+