User Tools

Site Tools


Sidebar


News:

GAIA DR3 2024/02/25 10:59

Cartes du Ciel is free software released under the terms of the
GNU banner GNU General Public License


Hosted by SourceForge.net

Support This Project


en:documentation:toolbox_editor

Tool box editor

This window is show when you click the Script button at the bottom of a Tool box. It allow to configure and program the action for the tool box.

Create the tool layout

First set the title for your tool in the top text field.

Then you need to add at least one Group: click the Group button, set the group title and the number of column element you want on each row. Then click the Add button.

Then use the same principle to add the elements you want, for example a text Edit and a Button.
This elements can only be added to a group.
A name is automatically assigned to each element, for example Edit_1 . This is this name you need to use to access the element properties from your script.
For some elements you can select a title or a height in pixel.
To change the number of elements per row, create a new group with the required value but without title.

Special elements are the Events. This not add anything visible on the screen but allow you to write the require script to process an event.
Event are :

  • Initialization: Run once after you click the Apply button, or when the program start.
  • Activation: Run every time this tool box is show.
  • Timer: Run at periodic interval, enter the interval in second when you select this event.
  • Telescope move: Each time the telescope position change.
  • Chart refresh: Each time the chart redraw.
  • Object identification click: Each time and object is select by a click on the chart or as the result of a search.
  • Distance measurement: When you measure a distance on the chart.
  • Telescope connected: When the telescope is connected.
  • Telescope disconnected: When the telescope is disconnected.
  • Translation: Run after initialisation or when you change the program language.

The events are normally inactive when the tool is not show on the screen. One exception is the Timer event you can always activate by checking the corresponding box. But be careful with the performance issue this option can imply.
Use the Activation event to update your tool with the change that can occur on the map when the tool was inactive.

You can reorder the group or elements by using the vertical arrows or by drag and drop in the left tree.

If you select an element in the tree and change one of it's property the Update button appear to allow to apply the change.

A script can be attached to following elements: Button, Menu, Combo box, Event.
When you select one of this elements in the tree the “Edit script” button appear. See below for the details.
You can add a function to the right click menu of the chart. To do that create the function for a button and check “Menu”.

When you are ready click the Apply button to show your elements on the tool box and compile the scripts.
Don't forget to save your work to a file with the Save button (default file extension is .cdcps).
Also save the program configuration to have you tool box automatically loaded the next time you start the program.

Script editor

The editor allow to write the script itself that execute on a button click, a combobox selection, or an event.

The language to use is Pascal Script, based on Object Pascal.
Define first the global variables, then the procedure and function if any, then the private variable, and finally the main code start with begin and end with end.
Read the script example page for a quick start.

As the each script is specific to one event there is no possibility to have global variables across scripts. For example you cannot set a variable when a button is pressed and later use this variable in another button click.
To solve this issue a number of global variables are predefined in the main program and specific functions allow to write and read them.

This functions and other specific to the interface with Skychart, they are described in a separate script reference page.

Use the Save button to record your change and return to the main window.

The top button are related to the debugging function as describe below.

Script debugger

Simple debugging function are available to test your code.

To run the script in debug mode press the green arrow Run button. The program is first compiled.

In case of compilation error, the corresponding row is highlighted in yellow, and the error message is show in the bottom message area.

If the compilation finish without error the program start to run and stop on the first code line of the main procedure. The current execution position is highlighted in blue.

You can now use the Step over button to execute your program line by line.
The Step into button do the same, except if the current line is a call to one of your function. In this case Step into allow to run the function line by line, but Step over execute the function and stop at the main program next line.

You can also set a breakpoint on a specific line to jump directly at this position.

To set a breakpoint click on the leftmost column to show a red icon.
Use the Run button to jump to the next breakpoint. The current line is then highlighted in red.

You can remove a breakpoint by clicking on the red icon or all at at time with the Remove all breakpoint button.

You can display the value of variables when the program is in pause at a breakpoint or after a Step over click.
Just click on the variable name anywhere in the program source to display the value in the message area.
Note this work only for local variables, not for object properties.

You can use the Pause button to pause the program execution. This can be useful to examine the condition of an infinite loop for example.

The Stop button terminate the program execution immediately.

en/documentation/toolbox_editor.txt · Last modified: 2016/01/12 09:32 by admin