scripting.doxygen   scripting.doxygen 
/* /*
* Stellarium * Stellarium
* Copyright (C) 2009 Matthew Gates * Copyright (C) 2009 Matthew Gates
* Copyright (C) 2010 Bogdan Marinov
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2 * as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version. * of the License, or (at your option) any later version.
* *
* This program is distributed in the hope that it will be useful, * This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details. * GNU General Public License for more details.
skipping to change at line 27 skipping to change at line 28
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, U SA. * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, U SA.
*/ */
/*! /*!
@page scripting Scripting Engine @page scripting Scripting Engine
@section intro_scripts Introduction @section intro_scripts Introduction
Since version 0.10.1, Stellarium includes a scripting feature based on the Since version 0.10.1, Stellarium includes a scripting feature based on the
<a href="http://doc.trolltech.com/4.6/qtscript.html">QT Scripting Engine</a >. <a href="http://doc.trolltech.com/4.7/qtscript.html">QT Scripting Engine</a >.
This makes it possible to write small programs within Stellarium to produce This makes it possible to write small programs within Stellarium to produce
presentations, set up custom configurations, and to automate repetitive presentations, set up custom configurations, and to automate repetitive
tasks. Prior to version 0.10.0, Stellarium used a different scripting engi ne tasks. Prior to version 0.10.0, Stellarium used a different scripting engi ne
called @ref StratoScript. called @ref StratoScript.
The core scripting language is The core scripting language is
<a href="http://en.wikipedia.org/wiki/ECMAScript">ECMAScript</a>, giving us ers <a href="http://en.wikipedia.org/wiki/ECMAScript">ECMAScript</a>, giving us ers
access to all basic ECMAScript language features such as flow control, vari ables access to all basic ECMAScript language features such as flow control, vari ables
string manipulation and so on. Interaction with Stellarium-specific feature s string manipulation and so on. Interaction with Stellarium-specific feature s
is done via a collection of objects which represent components of Stellariu m is done via a collection of objects which represent components of Stellariu m
itself. See @ref scripting_api for more details. itself. See @ref scripting_api for more details.
@section scratoscript Stratoscript @section scratoscript Stratoscript
Prior to version 0.10.0, Stellarium had a simple scripting engine, known as Prior to version 0.10.0, Stellarium had a simple scripting engine, known as
<i>StratoScript</i>. Using StratoScript it was possible to record and play back \e StratoScript. Using \e StratoScript it was possible to record and play back
sequences of Stellarium commands, load and display custom images, and play sounds. sequences of Stellarium commands, load and display custom images, and play sounds.
In this way it was possible to make planetarium presentations - a feature u sed In this way it was possible to make planetarium presentations - a feature u sed
quite widely in the small planetarium community. quite widely in the small planetarium community.
However StratoScript lacked many features of a real programming language - However \e StratoScript lacked many features of a real programming language
there -
were no variables, no flow control and no way to introspect the state of St there were no variables, no flow control and no way to introspect the state
ellarium. of
Stellarium.
The replacement scripting engine implemented in the 0.10.x series addresses these The replacement scripting engine implemented in the 0.10.x series addresses these
shortcomings, at the expense of a little complexity and a new language synt ax. shortcomings, at the expense of a little complexity and a new language synt ax.
A compatibility mode which converts StratoScript into new scripting engine on A compatibility mode which converts \e StratoScript into new scripting engi ne on
the fly is in progress. the fly is in progress.
Note: StratoScript compatibility is a build-time option. To enable this f eature, Note: StratoScript compatibility is a build-time option. To enable this fea ture,
Stellarium must be built using the ENABLE_STRATOSCRIPT_COMPAT=1 option to c make. Stellarium must be built using the ENABLE_STRATOSCRIPT_COMPAT=1 option to c make.
@section scripting_api Scripting API @section scripting_api Scripting API
Interation with Stellarium-specific functionality is done by calling the <b Interation with Stellarium-specific functionality is done by calling the
>public slots</b> <b>public slots</b> of instances of a group of Stellarium's core classes.
of instances of a group of Stellarium's core classes.
- The public slots in the class StelMainScriptAPI are available via an obje - The public slots in the class StelMainScriptAPI are available via an obje
ct named ct
<b>core</b>. For example, to access StelMainScriptAPI::wait() from a scr named \b core. For example, to access StelMainScriptAPI::wait() from a sc
ipt, use the ript,
scripting command: core.wait(...); use the scripting command:
\code
- The public slots for each StelModule are available in the scripting engin core.wait(...);
e via an \endcode
object with the same name as the corresponding StelModule. For example,
to access - The public slots for each of the following classes are available in the
LandscapeMgr::setFlagAtmosphere(), use the scripting command: scripting engine via an object with the same name as the corresponding cl
LandscapeMgr.setFlagAtmosphere(...); ass:
- ConstellationMgr
- Additional core classes have self-named objects available from the script - GridLinesMgr
ing engine: - LabelMgr
- StelSkyDrawer - LandscapeMgr
- StelSkyLayerMgr - MeteorMgr
- NebulaMgr
- ScreenImageMgr
- SolarSystem
- StarMgr
- StelAudioMgr
- StelMovementMgr
- StelSkyDrawer
- StelSkyLayerMgr
.
For example, to access LandscapeMgr::setFlagAtmosphere(), use the scripti
ng
command:
\code
LandscapeMgr.setFlagAtmosphere(true);
\endcode
Note: All of these except for StelSkyDrawer are StelModule classes.
@section script_console Script Console @section script_console Script Console
Note: The Script Console has been enabled by default since version 0.10.5.
It is a build-time option. To enable or disable this feature, use the
ENABLE_SCRIPT_CONSOLE=1 or =0 option to cmake.
It is possible to open, edit run and save scripts using the script console window. 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 To toggle the script console, press F12. The script console also provides
an output an output window in which script debugging output is visible.
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 @section example_scripts Examples
The best source of examples is the <b>scripts</b> sub-directory of the main The best source of examples is the \b scripts sub-directory of the main Ste
Stellarium llarium
source tree. This directory contains a sub-directory called tests which ar source tree. This directory contains a sub-directory called \b tests which
e not installed are not
with Stellarium, but are nontheless useful sources of example code for vari installed with Stellarium, but are nontheless useful sources of example cod
ous scripting e for
features. various scripting features. (The directory can be <a href="http://bazaar.la
unchpad.net/~stellarium/stellarium/trunk/files/head:/scripts/">browsed onli
ne</a>. Script files end in <tt>.ssc</tt> and <tt>.inc</tt>. Download links
are to the right.)
@subsection minimal_script Minimal Script @subsection minimal_script Minimal Script
This script prints "Hello Universe" in the @ref script_console output windo w. This script prints "Hello Universe" in the @ref script_console output windo w.
<pre>core.debug("Hello Universe");</pre> \code
core.debug("Hello Universe");
\endcode
@subsection using_module Using a StelModule @subsection using_module Using a StelModule
This script uses the LabelMgr module to display "Hello Universe" the screen This script uses the LabelMgr module to display "Hello Universe" in white o
for n
3 seconds. the screen for 3 seconds.
<pre>LabelMgr.labelScreen("Hello Universe", 200, 200, true, 20, "#ff0000"); \code
LabelMgr.labelScreen("Hello Universe", 200, 200, true, 20, "#ff0000");
core.wait(3); core.wait(3);
LabelMgr.deleteAllLabels();</pre> LabelMgr.deleteAllLabels();
\endcode
*/ */
 End of changes. 15 change blocks. 
48 lines changed or deleted 71 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/