Stellarium  1.2
Public Slots | Signals | Public Member Functions | Static Public Member Functions | Properties
StelScriptMgr Class Reference

Manage scripting in Stellarium Notes on migration from QtScript to QJSEngine. More...

#include <StelScriptMgr.hpp>

Public Slots

QString getHtmlDescription (const QString &s, bool generateDocumentTags=true)
 Returns a HTML description of the specified script. More...
 
QString getName (const QString &s)
 Gets a single line name of the script. More...
 
QString getAuthor (const QString &s)
 Gets the name of the script Author. More...
 
QString getLicense (const QString &s)
 Gets the licensing terms for the script. More...
 
QString getVersion (const QString &s)
 Gets the version of the script. More...
 
QString getDescription (const QString &s)
 Gets a description of the script. More...
 
QString getShortcut (const QString &s)
 Gets the default shortcut of the script. More...
 
bool runScript (const QString &fileName, const QString &includePath="")
 Run the script located in the given file. More...
 
bool runScriptDirect (const QString scriptId, const QString &scriptCode, int &errLoc, const QString &includePath=QString())
 Runs the script code given. More...
 
bool runScriptDirect (const QString &scriptCode, const QString &includePath=QString())
 Convenience method similar to runScriptDirect(const QString scriptId, const QString& scriptCode, int &errLoc, const QString &includePath = QString()); when scriptId and errLoc are not relevant. More...
 
bool runPreprocessedScript (const QString &preprocessedScript, const QString &scriptId)
 Runs preprocessed script code which has been generated using runPreprocessedScript(). More...
 
bool prepareScript (QString &script, const QString &fileName, const QString &includePath="")
 Loads a script file and does all preparatory steps except for actually executing the script in the engine. More...
 
void stopScript ()
 Stops any running script. More...
 
void setScriptRate (double r)
 Changes the rate at which the script executes as a multiple of real time. More...
 
double getScriptRate ()
 Get the rate at which the script is running as a multiple of the normal execution rate.
 
void debug (const QString &msg)
 cause the emission of the scriptDebug signal. More...
 
void output (const QString &msg)
 cause the emission of the scriptOutput signal. More...
 
void resetOutput (void)
 Reset output file and cause the emission of an (empty) scriptOutput signal.
 
void saveOutputAs (const QString &filename)
 Save output file to new file. More...
 
void pauseScript ()
 Pause a running script. More...
 
void resumeScript ()
 Resume a paused script. More...
 

Signals

void runningScriptIdChanged (const QString &id)
 Emitted when the running script id changes (also on start/stop)
 
void scriptRunning ()
 Notification when a script starts running.
 
void scriptPaused ()
 Notification when a script has paused running.
 
void scriptStopped ()
 Notification when a script has stopped running.
 
void scriptDebug (const QString &)
 Notification of a script event - warnings, current execution line etc.
 
void scriptOutput (const QString &)
 Notification of a script event - output line.
 

Public Member Functions

 StelScriptMgr (QObject *parent=Q_NULLPTR)
 
QStringList getScriptList () const
 
bool scriptIsRunning () const
 Find out if a script is running. More...
 
QString runningScriptId () const
 Get the ID (usually filename) of the currently running script. More...
 
bool preprocessScript (const QString fileName, const QString &input, QString &output, const QString &scriptDir, int &errLoc)
 Preprocess script, esp. More...
 
bool preprocessFile (const QString fileName, QFile &input, QString &output, const QString &scriptDir)
 
void addModules ()
 Add all the StelModules into the script engine.
 
void addObject (QObject *obj)
 Add a single QObject as scripting object The object must have set a name by QObject::setObjectName(). More...
 
const QMetaObject * getMetaOfStelMainScriptAPI ()
 Permit access to StelScriptMainAPI's methods.
 
QEventLoop * getWaitEventLoop ()
 Accessor to QEventLoop.
 

Static Public Member Functions

static void defVecClasses (QScriptEngine *engine)
 Define JS classes Vec3f, Vec3d.
 

Properties

QString runningScriptId
 

Detailed Description

Member Function Documentation

◆ addObject()

void StelScriptMgr::addObject ( QObject *  obj)
Note
use this sparingly and with caution, and only add one object per class!

◆ debug

void StelScriptMgr::debug ( const QString &  msg)
slot

This is so that functions in StelMainScriptAPI can explicitly send information to the ScriptConsole

◆ getAuthor

QString StelScriptMgr::getAuthor ( const QString &  s)
slot
Parameters
sthe file name of the script whose name is to be returned.
Returns
text following a comment with Author: at the start. If no such comment is found, "" is returned. If the file is not found or cannot be opened for some reason, an Empty string will be returned.

◆ getDescription

QString StelScriptMgr::getDescription ( const QString &  s)
slot
Parameters
sthe file name of the script whose name is to be returned.
Returns
text following a comment with Description: at the start. The description is considered to be over when a line with no comment is found. If no such comment is found, QString("") is returned. If the file is not found or cannot be opened for some reason, an Empty string will be returned.

◆ getHtmlDescription

QString StelScriptMgr::getHtmlDescription ( const QString &  s,
bool  generateDocumentTags = true 
)
slot

Includes name, author, description...

Parameters
sthe file name of the script whose HTML description is to be returned.
generateDocumentTagsif true, the main wrapping document tags (<html><body>...</body></html>) are also generated

◆ getLicense

QString StelScriptMgr::getLicense ( const QString &  s)
slot
Parameters
sthe file name of the script whose name is to be returned.
Returns
text following a comment with License: at the start. If no such comment is found, "" is returned. If the file is not found or cannot be opened for some reason, an Empty string will be returned.

◆ getName

QString StelScriptMgr::getName ( const QString &  s)
slot
Parameters
sthe file name of the script whose name is to be returned.
Returns
text following a comment with Name: at the start. If no such comment is found, the file name will be returned. If the file is not found or cannot be opened for some reason, an Empty string will be returned.

◆ getShortcut

QString StelScriptMgr::getShortcut ( const QString &  s)
slot
Parameters
sthe file name of the script whose name is to be returned.
Returns
text following a comment with Shortcut: at the start. If no such comment is found, QString("") is returned. If the file is not found or cannot be opened for some reason, an Empty string will be returned.

◆ getVersion

QString StelScriptMgr::getVersion ( const QString &  s)
slot
Parameters
sthe file name of the script whose name is to be returned.
Returns
text following a comment with Version: at the start. If no such comment is found, "" is returned. If the file is not found or cannot be opened for some reason, an Empty string will be returned.

◆ output

void StelScriptMgr::output ( const QString &  msg)
slot

This is so that functions in StelMainScriptAPI can explicitly send information to the ScriptConsole

◆ pauseScript

void StelScriptMgr::pauseScript ( )
slot
Note
This method only works with the Qt5-based scripting engine.

◆ prepareScript

bool StelScriptMgr::prepareScript ( QString &  script,
const QString &  fileName,
const QString &  includePath = "" 
)
slot

Use runPreprocessedScript to execute the script. It should be safe to call this method from another thread.

Parameters
scriptreturns the preprocessed script text
fileNamethe location of the file containing the script.
includePaththe directory to use when searching for include files in the SSC preprocessor. Usually this will be the same as the script file itself, but if you're running a generated script from a temp directory, but want to include a file from elsewhere, it can be usetul to set it to something else (e.g. in ScriptConsole).
Returns
false if the named script could not be prepared, true otherwise

◆ preprocessScript()

bool StelScriptMgr::preprocessScript ( const QString  fileName,
const QString &  input,
QString &  output,
const QString &  scriptDir,
int &  errLoc 
)

process include instructions. if the command line option –verbose has been given, this dumps the preprocessed script with line numbers attached to log. This helps to understand the line number given by the usual error message.

◆ resumeScript

void StelScriptMgr::resumeScript ( )
slot
Note
This method only works with the Qt5-based scripting engine.

◆ runningScriptId()

QString StelScriptMgr::runningScriptId ( ) const
Returns
Empty string if no script is running, else the ID of the script which is running.

◆ runPreprocessedScript

bool StelScriptMgr::runPreprocessedScript ( const QString &  preprocessedScript,
const QString &  scriptId 
)
slot

In general, you do not want to use this method, use runScript() or runScriptDirect() instead.

Note
This is a blocking call! The event queue is held up by calls of QCoreApplication::processEvents().
Parameters
preprocessedScriptthe string containing the preprocessed script.
scriptIdThe name of the script. Usually should correspond to the file name.
Returns
false if the given script code could not be run, true otherwise

◆ runScript

bool StelScriptMgr::runScript ( const QString &  fileName,
const QString &  includePath = "" 
)
slot

In essence, this calls prepareScript and runPreprocessedScript.

Note
This is a blocking call! The event queue is held up by calls of QCoreApplication::processEvents().
Parameters
fileNamethe location of the file containing the script.
includePaththe directory to use when searching for include files in the SSC preprocessor. If empty, this will be the same as the directory where the script file resides. If you're running a generated script from a temp directory, but want to include a file from elsewhere, it can be usetul to set it to something else (e.g. in ScriptConsole).
Returns
false if the named script could not be prepared or run, true otherwise

◆ runScriptDirect [1/2]

bool StelScriptMgr::runScriptDirect ( const QString &  scriptCode,
const QString &  includePath = QString() 
)
slot

(Required e.g. in RemoteControl)

◆ runScriptDirect [2/2]

bool StelScriptMgr::runScriptDirect ( const QString  scriptId,
const QString &  scriptCode,
int &  errLoc,
const QString &  includePath = QString() 
)
slot

This can be used for quick script executions, without having to create a temporary file first.

Note
This is a blocking call! The event queue is held up by calls of QCoreApplication::processEvents().
Parameters
scriptIdpath name, if available, or something helpful
scriptCodeThe script to execute
errLocoffset of erroneous include line, or -1
includePathIf a null string (the default), no pre-processing is done. If an empty string, the default script directories are used (script/ in both user and install directory). Otherwise, the given directory is used.
Returns
false if the named script code could not be prepared or run, true otherwise

◆ saveOutputAs

void StelScriptMgr::saveOutputAs ( const QString &  filename)
slot

This is required to allow reading with other program on Windows while output.txt is still open.

Parameters
filenamenew filename. If this is not an absolute path, it will be created in the same directory as output.txt
Note
For storing to absolute path names, set [scripts]/flag_script_allow_write_absolute_path=true.

◆ scriptIsRunning()

bool StelScriptMgr::scriptIsRunning ( ) const
Returns
true if a script is running, else false

◆ setScriptRate

void StelScriptMgr::setScriptRate ( double  r)
slot

Note that this is not the same as the rate at which simulation time passes because the script running at normal rate might set the simulation time rate to be non-real time.

Parameters
rrate, e.g. 2.0 = script runs at twice the normal rate

◆ stopScript

void StelScriptMgr::stopScript ( )
slot
Returns
false if no script was running, true otherwise.