3
* Copyright (C) 2007 Fabien Chereau
5
* This program is free software; you can redistribute it and/or
6
* modify it under the terms of the GNU General Public License
7
* as published by the Free Software Foundation; either version 2
8
* of the License, or (at your option) any later version.
10
* This program is distributed in the hope that it will be useful,
11
* but WITHOUT ANY WARRANTY; without even the implied warranty of
12
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
* GNU General Public License for more details.
15
* You should have received a copy of the GNU General Public License
16
* along with this program; if not, write to the Free Software
17
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
20
#ifndef _QTSCRIPTMGR_HPP_
21
#define _QTSCRIPTMGR_HPP_
25
#include <QStringList>
27
#include "VecMath.hpp"
29
//! Provide script API for Stellarium global functions. Public slots in this class
30
//! may be used in Stellarium scripts, and are accessed as member function to the
31
//! "core" scripting object. Module-specific functions, such as setting and clearing
32
//! of display flags (e.g. LandscapeMgr::setFlagAtmosphere) can be accessed directly
33
//! via the scripting object with the class name, e.g. by using the scripting command:
34
//! LandscapeMgr.setFlagAtmosphere(true);
35
class StelMainScriptAPI : public QObject
38
Q_PROPERTY(double JDay READ getJDay WRITE setJDay)
39
Q_PROPERTY(double timeSpeed READ getTimeRate WRITE setTimeRate)
42
StelMainScriptAPI(QObject *parent = 0);
45
// These functions will be available in scripts
47
//! Set the current date in Julian Day
48
//! @param JD the Julian Date
49
void setJDay(double JD);
50
//! Get the current date in Julian Day
51
//! @return the Julian Date
52
double getJDay(void) const;
54
//! set the date in ISO format, e.g. "2008-03-24T13:21:01"
55
//! @param dt the date string to use. Formats:
56
//! - ISO, e.g. "2008-03-24T13:21:01"
57
//! - "now" (set sim time to real time)
58
//! - relative, e.g. "+ 4 days", "-2 weeks". can use these
59
//! units: seconds, minutes, hours, days, weeks, months, years.
60
//! You may also append " sidereal" to use sidereal days and so on.
61
//! You can also use "now" at the start. For example:
62
//! "now + 3 hours sidereal"
63
//! Note: you must use the plural all the time, even when the number
64
//! of the unit is 1. i.e. use "+ 1 days" not "+1 day".
65
//! Note: when sidereal time is used, the length of time for
66
//! each unit is dependent on the current planet. By contrast
67
//! when sidereal timeis not specified (i.e. solar time is used)
68
//! the value is conventional - i.e. 1 day means 1 Earth Solar day.
69
//! @param spec "local" or "utc" - only has an effect when
70
//! the ISO date type is used.
71
void setDate(const QString& dt, const QString& spec="utc");
73
//! Set time speed in JDay/sec
74
//! @param ts the new rate of passage of time as a multiple of real time.
75
//! For example if ts is 1, time will pass at the normal rate. If ts == 10
76
//! then simulation time will pass at 10 times the normal rate.
77
//! If ts is negative, simulation time will go backwards.
78
void setTimeRate(double ts);
79
//! Get simulation time rate.
80
//! @return time speed as a multiple of real time.
81
double getTimeRate(void) const;
83
//! Pauses the script for t seconds
84
//! @param t the number of seconds to wait
87
//! Waits until a specified simulation date/time. This function
88
//! will take into account the rate (and direction) in which simulation
89
//! time is passing. e.g. if a future date is specified and the
90
//! time is moving backwards, the function will return immediately.
91
//! If the time rate is 0, the function will not wait. This is to
92
//! prevent infinite wait time.
93
//! @param dt the date string to use
94
//! @param spec "local" or "utc"
95
void waitFor(const QString& dt, const QString& spec="utc");
97
//! Select an object by name
98
//! @param name the name of the object to select (english)
99
//! If the name is "", any currently selected objects will be
101
//! @param pointer whether or not to have the selection pointer enabled
102
void selectObjectByName(const QString& name, bool pointer=false);
104
//! Clear the display options, setting a "standard" view.
106
//! - natural : azimuthal mount, atmosphere, landscape,
107
//! no lines, labels or markers
108
//! - starchart : equatorial mount, constellation lines,
109
//! no landscape, atmoshere etc. labels & markers on.
110
//! @param state the name of a preset state.
111
void clear(const QString& state="natural");
113
//! move the current viewing direction to some specified altitude and azimuth
114
//! angles may be specified in a format recognised by StelUtils::getDecAngle()
115
//! @param alt the altitude angle
116
//! @param azi the azimuth angle
117
//! @param duration the duration of the movement in seconds
118
void moveToAltAzi(const QString& alt, const QString& azi, float duration=1.);
120
//! move the current viewing direction to some specified right ascension and declination
121
//! angles may be specified in a format recognised by StelUtils::getDecAngle()
122
//! @param ra the right ascension angle
123
//! @param dec the declination angle
124
//! @param duration the duration of the movement in seconds
125
void moveToRaDec(const QString& ra, const QString& dec, float duration=1.);
127
//! Set the observer location
128
//! @param longitude the longitude in degrees. E is +ve.
129
//! values out of the range -180 .. 180 mean that
130
//! the longitude will not be set
131
//! @param latitude the longitude in degrees. N is +ve.
132
//! values out of the range -180 .. 180 mean that
133
//! the latitude will not be set
134
//! @param altitude the new altitude in meters.
135
//! values less than -1000 mean the altitude will not
137
//! @param duration the time for the transition from the
138
//! old to the new location.
139
//! @param name A name for the location (which will appear
140
//! in the status bar.
141
//! @param planet the English name of the new planet.
142
//! If the planet name is not known (e.g. ""), the
143
//! planet will not be set.
144
void setObserverLocation(double longitude, double latitude, double altitude, double duration=1., const QString& name="", const QString& planet="");
146
//! Set the location by the name of the location.
147
//! @param id the location ID as it would be found in the database
148
//! of locations - do a search in the Location window to see what
149
//! where is. e.g. "York, UnitedKingdom".
150
//! @param duration the number of seconds to take to move location.
151
void setObserverLocation(const QString id, double duration=1.);
153
//! Save a screenshot.
154
//! @param prefix the prefix for the file name to use
155
//! @param dir the path of the directory to save the screenshot in. If
156
//! none is specified, the default screenshot directory will be used.
157
//! @param invert whether colors have to be inverted in the output image
158
void screenshot(const QString& prefix, bool invert=false, const QString& dir="");
160
//! Hide or show the GUI (toolbars)
161
//! @param b the new hidden status of the toolbars, i.e. if b==true, the
162
//! toolbars will be hidden, else they will be made visible.
163
void setHideGui(bool b);
165
//! Set the minimum frames per second. Usually this minimum will
166
//! be switched to after there are no user events for some seconds
167
//! to save power. However, if can be useful to set this to a high
168
//! value to improve playing smoothness in scripts.
169
//! @param m the new minimum fps setting.
170
void setMinFps(float m);
172
//! Get the current minimum frames per second.
175
//! Set the maximum frames per second.
176
//! @param m the new maximum fps setting.
177
void setMaxFps(float m);
179
//! Get the current maximum frames per second.
182
//! Load an image which will have sky coordinates.
183
//! @param id a string ID to be used when referring to this
184
//! image (e.g. when changing the displayed status or deleting
186
//! @param filename the file name of the image. If a relative
187
//! path is specified, "scripts/" will be prefixed before the
188
//! image is searched for using StelFileMgr.
189
//! @param ra0 The right ascension of the first corner of the image in degrees
190
//! @param dec0 The declenation of the first corner of the image in degrees
191
//! @param ra1 The right ascension of the second corner of the image in degrees
192
//! @param dec1 The declenation of the second corner of the image in degrees
193
//! @param ra2 The right ascension of the third corner of the image in degrees
194
//! @param dec2 The declenation of the third corner of the image in degrees
195
//! @param ra3 The right ascension of the fourth corner of the image in degrees
196
//! @param dec3 The declenation of the fourth corner of the image in degrees
197
//! @param minRes The minimum resolution setting for the image
198
//! @param maxBright The maximum brightness setting for the image
199
//! @param visible The initial visibility of the image
200
void loadSkyImage(const QString& id, const QString& filename,
201
double ra0, double dec0,
202
double ra1, double dec1,
203
double ra2, double dec2,
204
double ra3, double dec3,
205
double minRes=2.5, double maxBright=14, bool visible=true);
207
//! Convenience function which allows the user to provide RA and DEC angles
208
//! as strings (e.g. "12d 14m 8s" or "5h 26m 8s" - formats accepted by
209
//! StelUtils::getDecAngle()).
210
void loadSkyImage(const QString& id, const QString& filename,
211
const QString& ra0, const QString& dec0,
212
const QString& ra1, const QString& dec1,
213
const QString& ra2, const QString& dec2,
214
const QString& ra3, const QString& dec3,
215
double minRes=2.5, double maxBright=14, bool visible=true);
217
//! Convenience function which allows loading of a sky image based on a
218
//! central coordinate, angular size and rotation.
219
void loadSkyImage(const QString& id, const QString& filename,
220
double ra, double dec, double angSize, double rotation,
221
double minRes=2.5, double maxBright=14, bool visible=true);
223
//! Convenience function which allows loading of a sky image based on a
224
//! central coordinate, angular size and rotation.
225
void loadSkyImage(const QString& id, const QString& filename,
226
const QString& ra, const QString& dec, double angSize, double rotation,
227
double minRes=2.5, double maxBright=14, bool visible=true);
229
//! Remove a SkyImage.
230
//! @param id the ID of the image to remove.
231
void removeSkyImage(const QString& id);
233
//! Load a sound from a file.
234
//! @param filename the name of the file to load.
235
//! @param id the identifier which will be used to refer to the sound
236
//! when calling playSound, pauseSound, stopSound and dropSound.
237
void loadSound(const QString& filename, const QString& id);
239
//! Play a sound which has previously been loaded with loadSound
240
//! @param id the identifier used when loadSound was called
241
void playSound(const QString& id);
243
//! Pause a sound which is playing. Subsequent playSound calls will
244
//! resume playing from the position in the file when it was paused.
245
//! @param id the identifier used when loadSound was called
246
void pauseSound(const QString& id);
248
//! Stop a sound from playing. This resets the position in the
249
//! sound to the start so that subsequent playSound calls will
250
//! start from the beginning.
251
//! @param id the identifier used when loadSound was called
252
void stopSound(const QString& id);
254
//! Drop a sound from memory. You should do this before the end
256
//! @param id the identifier used when loadSound was called
257
void dropSound(const QString& id);
259
//! print a debugging message to the console
260
//! @param s the message to be displayed on the console.
261
void debug(const QString& s);
264
void requestLoadSkyImage(const QString& id, const QString& filename,
265
double c1, double c2,
266
double c3, double c4,
267
double c5, double c6,
268
double c7, double c8,
269
double minRes, double maxBright, bool visible);
271
void requestRemoveSkyImage(const QString& id);
273
void requestLoadSound(const QString& filename, const QString& id);
274
void requestPlaySound(const QString& id);
275
void requestPauseSound(const QString& id);
276
void requestStopSound(const QString& id);
277
void requestDropSound(const QString& id);
280
//! For use in setDate and waitFor
281
//! For parameter descriptions see setDate().
282
//! @returns Julian day.
283
double jdFromDateString(const QString& dt, const QString& spec);
287
//! Manage scripting in Stellarium
288
class StelScriptMgr : public QObject
293
StelScriptMgr(QObject *parent=0);
296
QStringList getScriptList(void);
298
//! Find out if a script is running
299
//! @return true if a script is running, else false
300
bool scriptIsRunning(void);
301
//! Get the ID (filename) of the currently running script
302
//! @return Empty string if no script is running, else the
303
//! ID of the script which is running.
304
QString runningScriptId(void);
307
//! Gets a single line name of the script.
308
//! @param s the file name of the script whose name is to be returned.
309
//! @return text following a comment with Name: at the start. If no
310
//! such comment is found, the file name will be returned. If the file
311
//! is not found or cannot be opened for some reason, an Empty string
312
//! will be returned.
313
const QString getName(const QString& s);
315
//! Gets the name of the script Author
316
//! @param s the file name of the script whose name is to be returned.
317
//! @return text following a comment with Author: at the start. If no
318
//! such comment is found, "" is returned. If the file
319
//! is not found or cannot be opened for some reason, an Empty string
320
//! will be returned.
321
const QString getAuthor(const QString& s);
323
//! Gets the licensing terms for the script
324
//! @param s the file name of the script whose name is to be returned.
325
//! @return text following a comment with License: at the start. If no
326
//! such comment is found, "" is returned. If the file
327
//! is not found or cannot be opened for some reason, an Empty string
328
//! will be returned.
329
const QString getLicense(const QString& s);
331
//! Gets a description of the script.
332
//! @param s the file name of the script whose name is to be returned.
333
//! @return text following a comment with Description: at the start.
334
//! The description is considered to be over when a line with no comment
335
//! is found. If no such comment is found, QString("") is returned.
336
//! If the file is not found or cannot be opened for some reason, an
337
//! Empty string will be returned.
338
const QString getDescription(const QString& s);
340
//! Run the script located at the given location
341
//! @param fileName the location of the file containing the script.
342
//! @return false if the named script could not be run, true otherwise
343
bool runScript(const QString& fileName);
345
//! Stops any running script.
346
//! @return false if no script was running, true otherwise.
347
bool stopScript(void);
350
//! Called at the end of the running thread
354
//! Notification when a script starts running
355
void scriptRunning();
356
//! Notification when a script has stopped running
357
void scriptStopped();
360
// Utility functions for preprocessor
361
QMap<QString, QString> mappify(const QStringList& args, bool lowerKey=false);
362
bool strToBool(const QString& str);
363
// Pre-processor functions
364
bool preprocessScript(QFile& input, QFile& output, const QString& scriptDir);
366
#ifdef ENABLE_STRATOSCRIPT_COMPAT
367
bool preprocessStratoScript(QFile& input, QFile& output, const QString& scriptDir);
370
//! This function is for use with getName, getAuthor and getLicense.
371
//! @param s the script id
372
//! @param id the command line id, e.g. "Name"
373
//! @param notFoundText the text to be returned if the key is not found
374
//! @return the text following the id and : on a comment line near the top of
375
//! the script file (i.e. before there is a non-comment line).
376
const QString getHeaderSingleLineCommentText(const QString& s, const QString& id, const QString& notFoundText="");
377
QScriptEngine engine;
379
//! The thread in which scripts are run
380
class StelScriptThread* thread;
383
#endif // _QTSCRIPTMGR_HPP_
added
removed
src/scripting/StelScriptMgr.hpp
