Skychart

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Script example ======

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>