Differences

This shows you the differences between two versions of the page.

--- en:documentation:script_example [2014/06/15 15:49] – created pch
+++ en:documentation:script_example [2016/01/20 15:55] (current) – [Script example] pch
@@ Line 1: / Line 1: @@
 ====== Script example ======
-This page contain example of scripting functions.
+This page give tips and example of scripting functions.\\
+You can also look at the three [[toolbox|standard tool box]] code from within the program.\\
+For more details about a specific function see the [[script_reference|script reference]] page.
+===== Generality =====
+We first look in detail at the code of the Goto button of the Observer tools standard tool box.\\
+This cover many programming basis.
+The full script code look as following:
+<code>
+// Slew telescope
+  var ra,de: double;
+      a,b,r: string;
+      c: Tstringlist;
+  begin
+  memo_1.clear;
+  if MenuTelescopeConnect.checked then begin
+    if not StrToAR(Edit_1.text,ra) then begin memo_1.lines.add(rserror+' RA!');exit;end;
+    if not StrToDE(Edit_2.text,de) then begin memo_1.lines.add(rserror+' DE!');exit;end;
+    a:=floattostr(ra);
+    b:=floattostr(de);
+    GetSL('STRL1',c);
+    c.clear;
+    c.add('SLEW');
+    c.add(a);
+    c.add(b);
+    r:=cmd('',c);
+    c.clear;
+    memo_1.lines.add(r);
+  end
+  else memo_1.lines.add(rsTelescopeNot);
+  end.
+</code>
+Take a look at each part in detail:
+<code>
+// Slew telescope
+</code>
+Is a comment, you can use <nowiki>// {..} (*..*)</nowiki> to enclose your comments.
+----
+<code>
+  var ra,de: double;
+      a,b,r: string;
+      c: Tstringlist;
+</code>
+Define the variable we use later in the script.\\
+Important variable type are: integer, double, string.\\
+The Tstringlist type is use here to send a command to Skychart.
+----
+<code>
+  begin
+</code>
+The start of our program.
+----
+<code>
+memo_1.clear;
+</code>
+Clear the text box we use to show the messages. This ensure the text box is not filled by previous messages.
+----
+<code>
+  if MenuTelescopeConnect.checked then begin
+</code>
+We test the Checked property of the menu item MenuTelescopeConnect. This indicate we have connected the telescope to the program.\\
+If the result is true we execute the code block starting at "begin" up to the corresponding "end"
+----
+<code>
+    if not StrToAR(Edit_1.text,ra) then begin memo_1.lines.add(rserror+' RA!');exit;end;
+</code>
+We try to convert the RA in HMS format from the text in Edit_1 text box to a numeric value. If the conversion fail (because we type some junk in the text box) we show an error message and exit.
+----
+<code>
+   a:=floattostr(ra);
+</code>
+Convert the RA back to string representation but with the decimal format required by the command.
+----
+<code>
+GetSL('STRL1',c);
+c.clear;
+</code>
+Request a TStringList object identified by STRL1. We clear any data that may stay in the object.
+----
+<code>
+    c.add('SLEW');
+    c.add(a);
+    c.add(b);
+</code>
+Add the command and the required parameters (in this case RA and DEC) to the stringlist.
+----
+<code>
+   r:=cmd('',c);
+</code>
+Execute the command and store the result in the variable r.
+----
+<code>
+memo_1.lines.add(r);
+</code>
+Show the result of the command to the text box.
+----
+<code>
+else memo_1.lines.add(rsTelescopeNot);
+</code>
+The case the test MenuTelescopeConnect.checked is false we execute this line.\\
+It show in the text box a translation in the local language of 'Telescope not connected'.
+----
+<code>
+ end.
+</code>
+The end of the program.
+===== Call an external library ====
+You can define a function in an external library for use within your script as another local function.
+This example implement a simple chronometer by using the GetTickCount function of the Windows API.\\
+There is two button Start and Stop and two text box. A global integer variable is used to store the start time.
+Script for the Start button:
+<code>
+ function GetTickCount: Longint; external 'GetTickCount@kernel32.dll stdcall';
+ var
+   tick: Longint;
+ begin
+   tick:=GetTickCount;
+   setI('Int1',tick);
+   edit_1.text:='Started';
+ end.
+</code>
+Script for the Stop button:
+<code>
+function GetTickCount: Longint; external 'GetTickCount@kernel32.dll stdcall';
+var
+  t: double;
+  t1,tick: Longint;
+begin
+  tick:=GetTickCount;
+  getI('Int1',t1);
+  t:=double(tick-t1)/1000;
+  edit_1.text:='';
+  edit_2.text:=formatdatetime('HH:MM:SS.ZZZ',t/24/3600);
+end.
+</code>
+You can call any library function this way but beware this is system dependent, the kernel32.dll library is not available on Mac or Linux.
+Another limitation is that many library function expect a pointer to a parameter structure. As the script language use byte code internally (as Java) it cannot use a pointer to give the parameters. A solution is to write a C library wrapper that export the function with a flat parameter list.
+===== Using ASCOM directly ====
+This describe how to use an ASCOM device directly from your script without any use of the Skychart internal ASCOM telescope.
+This can be use to access another class of device, the example here connect to a dome, or to access additional properties for your telescope.\\
+In the later case you must be careful that your script work as a concurrent to Skychart main program for the device access.
+==== Use the ASCOM chooser ===
+The following code assigned to a button allow to select the ASCOM Dome driver we want to use. The driver name is saved in the text field Edit_1.
+<code>
+ var
+   V: variant;
+   w,s: widestring;
+ begin
+   V := CreateOleObject('ASCOM.Utilities.Chooser');
+   w:='Dome';
+   V.DeviceType:=w;
+   s:=edit_1.text;
+   s:=V.Choose(s);
+   edit_1.text:=s;
+   V:=Unassigned;
+ end.
+</code>
+Replace w:='Dome'; by Telescope, Focuser, Rotator, Camera, Filter to select another driver class.
+==== Connect to the ASCOM driver ===
+The following code is for the "Connect" button. It connect to the ASCOM Dome driver we select previously. We use the global variable Dome1 to store the ASCOM object.
+<code>
+var
+  D: variant;
+  s: widestring;
+begin
+  s:=edit_1.text;
+  getV('Dome1',D);
+  if VarIsEmpty(D) then
+    D := CreateOleObject(s);
+  D.connected:=true;
+  setV('Dome1',D);
+end.
+</code>
+==== Use the ASCOM driver ===
+Now we want to add a button to open the dome shutter. This is just an example, at this point any ASCOM property can be use.\\
+The first test protect again a program crash if we try to use an initialized variant.\\
+The second test protect again an ASCOM error if the dome is not connected.
+<code>
+var
+  D: variant;
+begin
+  getV('Dome1',D);
+  if (not VarIsEmpty(D)) then
+    if D.Connected then
+       D.OpenShutter;
+end.
+</code>
+==== Disconnect the ASCOM driver ===
+Add a button to disconnect the driver and release the resources.
+<code>
+var
+  D: variant;
+begin
+  getV('Dome1',D);
+  if (not VarIsEmpty(D)) then
+    if D.Connected then
+       D.connected:=false;
+  D:=Unassigned;
+  setV('Dome1',D);
+end.
+</code>
+===== Open a document =====
+The following code open the Skychart documentation page in the default web browser.\\
+You can use any document type with this function, the document open with the default application the same way as if you double click the document in the file explorer.
+<code>
+begin
+  OpenFile('doc\wiki_doc\en\documentation\start.html');
+end.
+</code>
+===== Run a command =====
+There is two different way to run an external command or program, depending if you want to wait for a result or not.
+==== Wait for a result ====
+The following command run the DIR command in the current directory. The result is stored in a stringlist and later show in a text memo. It contain the list of files in the directory.
+<code>
+var r:TstringList;
+begin
+  GetSL('STRL1',r);
+  r.clear;
+  RunOutput('dir',r);
+  Memo_1.lines.assign(r);
+end.
+</code>
+==== No wait ====
+If the command can run for an undetermined time or do not produce an output you need to use the following form.\\
+This example run the Variable star observer program and exit immediately.
+<code>
+begin
+  Run('varobs');
+end.
+</code>