Warning, /education/kstars/doc/scriptbuilder.docbook is written in an unsupported language. File is not indexed.

0001 <sect1 id="tool-scriptbuilder">
0002 <title>The Script Builder Tool</title>
0003 <indexterm><primary>Tools</primary>
0004 <secondary>Script Builder</secondary>
0005 </indexterm>
0007 <para>
0008 &kde; applications can be controlled externally from another program,
0009 from a console prompt, or from a shell script using the Inter-process communication protocol (&DBus;).  &kstars; takes
0010 advantage of this feature to allow rather complex behaviors to be
0011 scripted and played back at any time.  This can be used, for example,
0012 to create a classroom demo to illustrate an astronomical concept.
0013 </para>
0014 <para>
0015 The problem with &DBus; scripts is, writing them is a bit like
0016 programming, and can seem a daunting task to those who do not have
0017 programming experience.  The Script Builder Tool provides a
0018 <abbrev>GUI</abbrev> point-and-click interface for constructing
0019 &kstars; &DBus; scripts, making it very easy to create complex scripts.
0020 </para>
0022 <sect2 id="sb-intro">
0023 <title>Introduction to the Script Builder</title>
0025 <para>
0026 Before explaining how to use the Script Builder, I provide a very
0027 brief introduction to all of the <abbrev>GUI</abbrev> components;
0028 for more infomation, use the "What's This?" function.
0029 </para>
0031 <screenshot>
0032 <screeninfo>
0033 The Script Builder Tool
0034 </screeninfo>
0035 <mediaobject>
0036   <imageobject>
0037     <imagedata fileref="scriptbuilder.png" format="PNG"/>
0038   </imageobject>
0039   <textobject>
0040     <phrase>Script Builder Tool</phrase>
0041   </textobject>
0042 </mediaobject>
0043 </screenshot>
0045 <para>
0046 The Script Builder is shown in the above screenshot.  The box on the
0047 left is the <firstterm>Current Script box</firstterm>; it shows the
0048 list of commands that comprise the current working script.  The box
0049 on the right is the <firstterm>Function Browser</firstterm>; it
0050 displays the list of all available script functions.  Below the
0051 Function Browser, there is a small panel which will display short
0052 documentation about the script function highlighted in the Function
0053 Browser.  The panel below the Current Script box is the
0054 <firstterm>Function Arguments panel</firstterm>; when a function is
0055 highlighted in the Current Script box, this panel will contain items
0056 for specifying values for any arguments that the highlighted function
0057 requires.
0058 </para><para>
0059 Along the top of the window, there is a row of buttons which operate
0060 on the script as a whole.  From left to right, they are:
0061 <guibutton>New Script</guibutton>, <guibutton>Open Script...</guibutton>,
0062 <guibutton>Save Script</guibutton>, <guibutton>Save Script
0063 As...</guibutton>, and <guibutton>Test Script</guibutton>.  The
0064 function of these buttons should be obvious, except perhaps the last
0065 button.  Pressing <guibutton>Test Script</guibutton> will attempt to
0066 run the current script in the main &kstars; window.  You should move
0067 the Script Builder window out of the way before pressing this, so you
0068 can see the results.
0069 </para><para>
0070 In the center of the window, there is a column of buttons which operate
0071 on individual script functions.  From top to bottom, they are:
0072 <guibutton>Add Function</guibutton>, <guibutton>Remove
0073 Function</guibutton>, <guibutton>Copy Function</guibutton>,
0074 <guibutton>Move Up</guibutton>, and <guibutton>Move Down</guibutton>.
0075 <guibutton>Add Function</guibutton> adds the currently-highlighted
0076 function in the Function Browser to the Current Script box (you can
0077 also add a function by double-clicking on it).  The rest of the
0078 buttons operate on the function highlighted in the Current Script box,
0079 either removing it, duplicating it, or changing its position in the
0080 current script.
0081 </para>
0082 </sect2>
0084 <sect2 id="sb-using">
0085 <title>Using the Script Builder</title>
0086 <para>
0087 In order to illustrate using the Script Builder, we present a small
0088 tutorial example where we make a script that tracks the Moon while
0089 the clock runs at an accelerated rate.
0090 </para><para>
0091 If we are going to track the Moon, we will need to point the display
0092 at it first.  The <firstterm>lookToward</firstterm> function
0093 is used to do this.  Highlight this function in the Function Browser,
0094 and note the documentation displayed in the panel below the Browser.
0095 Press the <guibutton>Add Function</guibutton> button to add this
0096 function to the Current Script box.  The Function Arguments panel
0097 will now contain a combobox labeled <quote>Dir</quote>, short for
0098 direction.  This is the direction in which the display should
0099 be pointed.  The combobox contains only the cardinal compass points,
0100 not the Moon or any other objects.  You can either enter
0101 <quote>Moon</quote> in the box manually, or press the <guibutton>Object...</guibutton>
0102 button to use the <guilabel>Find Object...</guilabel>
0103 window to select the Moon from the list of named
0104 objects.  Note that, as usual, centering on an object automatically
0105 engages object-tracking mode, so there is no need to add the
0106 <firstterm>setTracking</firstterm> function after lookToward.
0107 </para><para>
0108 Now that we have taken care of pointing at the Moon, we next want to
0109 make time pass at an accelerated rate.  Use the
0110 <firstterm>setClockScale</firstterm> function for this.  Add it to
0111 the script by double-clicking on it in the Function Browser.  The
0112 Function Arguments panel contains a timestep spinbox for setting the
0113 desired time step for the simulation clock.  Change the timestep to
0114 3 hours.
0115 </para><para>
0116 OK, we have pointed at the Moon and accelerated the clock.  Now we just
0117 want the script to wait for several seconds while the display tracks
0118 on the Moon.  Add the <firstterm>waitFor</firstterm> function to the
0119 script, and use the Function Arguments panel to specify that it should
0120 wait for 20 seconds before continuing.
0121 </para><para>
0122 To finish up, let us reset the clock's timestep to the normal value
0123 of 1 second.  Add another instance of setClockScale, and set its value
0124 to 1 sec.
0125 </para><para>
0126 Actually, we are not quite done yet.  We should probably make sure that
0127 the display is using Equatorial coordinates before the script tracks
0128 the Moon with an accelerated time step.  Otherwise, if the display is
0129 using Horizontal coordinates, it will rotate very quickly through
0130 large angles as the Moon rises and sets.  This can be very confusing,
0131 and is avoided by setting the View Option
0132 <firstterm>UseAltAz</firstterm> to <quote>false</quote>.  To change
0133 any View Option, use the <firstterm>changeViewOption</firstterm>
0134 function.  Add this function to the script, and examine the Function
0135 Arguments panel.  There is a combobox which contains the list of all
0136 options which can be adjusted by changeViewOption.  Since we know
0137 we want the UseAltAz option, we could simply select it from the
0138 combobox.  However, the list is quite long, and there is no
0139 explanation of what each item is for.  It therefore may be easier to
0140 press the <guibutton>Browse Tree...</guibutton> button, which will open
0141 a window containing a tree view of the available options, organized by
0142 topic.  In addition, each item has a short explanation of what the
0143 option does, and the data type of the option's value.  We find
0144 UseAltAz under the <guilabel>Skymap Options</guilabel> category.
0145 Just highlight this item and press <guibutton>OK</guibutton>, and it
0146 will be selected in the combobox of the Function Arguments panel.
0147 Finally, make its value <quote>false</quote> or <quote>0</quote>.
0148 </para><para>
0149 One more step:  changing UseAltAz at the end of the script does us no
0150 good; we need this to be changed before anything else happens.  So,
0151 make sure this function is highlighted in the Current Script box,
0152 and press the <guibutton>Move Up</guibutton> button until it is the
0153 first function.
0154 </para><para>
0155 Now that we have finished the script, we should save it to disk.
0156 Press the <guibutton>Save Script</guibutton> button.  This will first
0157 open a window in which you can provide a name for the script, and fill
0158 in your name as the author.  Enter <quote>Tracking the Moon</quote>
0159 for a name, and your name as the author, and press
0160 <guibutton>OK</guibutton>.  Next, you will see the standard &kde; Save
0161 File dialog.  Specify a filename for the script and press
0162 <guibutton>OK</guibutton> to save the script.  Note that if your
0163 filename does not end with <quote>.kstars</quote>, this suffix
0164 will be automatically attached.  If you are curious, you can examine the
0165 script file with any text editor.
0166 </para><para>
0167 Now that we have a completed script, we can run it in a couple of ways.
0168 From a console prompt, you can simply execute the script as long as an
0169 instance of &kstars; is currently running.  Alternatively, you can execute
0170 the script from within &kstars; using the <menuchoice><guimenu>File</guimenu>
0171 <guimenuitem>Run Script...</guimenuitem></menuchoice> menu item.
0172 </para>
0173 </sect2>
0174 </sect1>