1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
/*
* Stellarium
* Copyright (C) 2009 Matthew Gates
* Copyright (C) 2010 Bogdan Marinov
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
/*!
@page scripting Scripting Engine
@tableofcontents
@section intro_scripts Introduction
Since version 0.10.1, Stellarium includes a scripting feature based on the
<a href="http://doc.qt.io/qt-5/qtscript-index.html">Qt Scripting Engine</a>.
This makes it possible to write small programs within Stellarium to produce
presentations, set up custom configurations, and to automate repetitive
tasks. Prior to version 0.10.0, Stellarium used a different scripting engine
called StratoScript.
The core scripting language is
<a href="http://en.wikipedia.org/wiki/ECMAScript">ECMAScript</a>, giving users
access to all basic ECMAScript language features such as flow control, variables
string manipulation and so on. Interaction with Stellarium-specific features
is done via a collection of objects which represent components of Stellarium
itself. See @ref scripting_api for more details.
@section scripting_api Scripting API
Interaction with Stellarium-specific functionality is done by calling the
<b>public slots</b> of instances of a group of Stellarium's core classes.
- The public slots in the class StelMainScriptAPI are available via an object
named \b core. For example, to access StelMainScriptAPI::wait() from a script,
use the scripting command:
\code
core.wait(...);
\endcode
- The public slots for each of the following classes are available in the
scripting engine via an object with the same name as the corresponding class:
- AsterismMgr
- ConstellationMgr
- CustomObjectMgr
- HighlightMgr
- GridLinesMgr
- LabelMgr
- MarkerMgr
- LandscapeMgr
- SporadicMeteorMgr
- NebulaMgr
- ScreenImageMgr
- SolarSystem
- StarMgr
- StelActionMgr
- StelAudioMgr
- StelVideoMgr
- StelMovementMgr
- StelSkyDrawer
- StelSkyLayerMgr
- SpecialMarkersMgr
- MilkyWay
- ZodiacalLight
- HipsMgr
.
For example, to access LandscapeMgr::setFlagAtmosphere(), use the scripting
command:
\code
LandscapeMgr.setFlagAtmosphere(true);
\endcode
\note All of these except for StelSkyDrawer are StelModule classes.
- The public slots for each of the following classes of the plugins are available
in the scripting engine too:
- Oculars
- Satellites
- Quasars
- Pulsars
- Exoplanets
- Observability
- EquationOfTime
- NavStars
- MeteorShowersMgr (The public slots in this class are available via an object named \b MeteorShowers)
- ArchaeoLines
- Calendars
- TelescopeControl
.
@section include_scripts Includes
Stellarium provides mechanism for splitting scripts on different files. Typical functions or
list of variables can be stored in separate \b .inc file and used within script through \b include()
command:
\code
include("common_objects.inc");
\endcode
\note Detailed example can be found <a href="https://github.com/Stellarium/stellarium/blob/master/scripts/constellations_tour.ssc">in Constellations Tour script</a>.
@section script_console Script Console
It is possible to open, edit run and save scripts using the script console window.
To toggle the script console, press F12. The script console also provides
an output window in which script debugging output is visible.
\note The Script Console is a build-time option. It has been enabled by
default since version 0.10.5. To enable or disable this feature, use the
ENABLE_SCRIPT_CONSOLE=1 or =0 option to cmake.
@section example_scripts Examples
The best source of examples is the \b scripts sub-directory of the main Stellarium
source tree. This directory contains a sub-directory called \b tests which are not
installed with Stellarium, but are nonetheless useful sources of example code for
various scripting features. (The directory can be <a href="https://github.com/Stellarium/stellarium/tree/master/scripts">browsed online</a>. Script files end in <tt>.ssc</tt> and <tt>.inc</tt>. Download links
are to the right.)
@subsection minimal_script Minimal Script
This script prints "Hello Universe" in the @ref script_console output window.
\code
core.debug("Hello Universe");
\endcode
@subsection using_module Using a StelModule
This script uses the LabelMgr module to display "Hello Universe" in white on
the screen for 3 seconds.
\code
LabelMgr.labelScreen("Hello Universe", 200, 200, true, 20, "#ff0000");
core.wait(3);
LabelMgr.deleteAllLabels();
\endcode
*/
|
