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 () const
	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...

bool	getFlagAllowExternalScreenshotDir () const
	Ensure that users must actively enable storing screenshots to directories configured in scripts. More...

void	setFlagAllowExternalScreenshotDir (bool flag)

bool	getFlagAllowWriteAbsolutePaths () const
	Ensure that users must actively enable writing to absolute paths configured in scripts. More...

void	setFlagAllowWriteAbsolutePaths (bool flag)

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.

void	flagAllowExternalScreenshotDirChanged (bool flag)
	Notification that screenshots to script-defined directories are allowed.

void	flagAllowWriteAbsolutePathsChanged (bool flag)
	Notification that flag to allow scripts to write to absolute paths changed.

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 () const
	Permit access to StelScriptMainAPI's methods.

QEventLoop *	getWaitEventLoop () const
	Accessor to QEventLoop.

Static Public Member Functions
static void	defVecClasses (QScriptEngine *engine)
	Define JS classes Vec3f, Vec3d.

Properties
QString	runningScriptId

bool	flagAllowExternalScreenshotDir
	Ensure that users must actively allow storing screenshots to directories configured in scripts. More...

bool	flagAllowWriteAbsolutePaths
	Ensure that users must actively allow storing output data to absolute paths. More...

Detailed Description

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

The old engine had isEvaluating(). We must use a mutex for the same idea.
There is no script.pause() function. We can only stop a running script.

Member Function Documentation

◆ addObject()

void StelScriptMgr::addObject ( QObject * obj )

Add a single QObject as scripting object The object must have set a name by QObject::setObjectName().

Note: use this sparingly and with caution, and only add one object per class!

◆ debug

void StelScriptMgr::debug ( const QString & msg )

slot

cause the emission of the scriptDebug signal.

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

◆ getAuthor

QString StelScriptMgr::getAuthor ( const QString & s )

slot

Gets the name of the script Author.

Parameters

s	the 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

Gets a description of the script.

Parameters

s	the 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.

◆ getFlagAllowExternalScreenshotDir

bool StelScriptMgr::getFlagAllowExternalScreenshotDir ( ) const

inlineslot

Ensure that users must actively enable storing screenshots to directories configured in scripts.

If this is false, a directory dir given in StelMainScriptAPI::screenshot(prefix, invert, dir, ...) is ignored.

◆ getFlagAllowWriteAbsolutePaths

bool StelScriptMgr::getFlagAllowWriteAbsolutePaths ( ) const

inlineslot

Ensure that users must actively enable writing to absolute paths configured in scripts.

If this is false, the output file is just stored to the user data directory

◆ getHtmlDescription

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

slot

Returns a HTML description of the specified script.

Includes name, author, description...

Parameters

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

◆ getLicense

QString StelScriptMgr::getLicense ( const QString & s )

slot

Gets the licensing terms for the script.

Parameters

s	the 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

Gets a single line name of the script.

Parameters

s	the 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

Gets the default shortcut of the script.

Parameters

s	the 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

Gets the version of the script.

Parameters

s	the 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

cause the emission of the scriptOutput signal.

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

◆ pauseScript

void StelScriptMgr::pauseScript ( )

slot

Pause a running script.

Note: This method only works with the Qt5-based scripting engine.

◆ prepareScript

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

slot

Loads a script file and does all preparatory steps except for actually executing the script in the engine.

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

Parameters

script	returns the preprocessed script text
fileName	the location of the file containing the script.
includePath	the 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
	)

Preprocess script, esp.

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

Resume a paused script.

Note: This method only works with the Qt5-based scripting engine.

◆ runningScriptId()

QString StelScriptMgr::runningScriptId ( ) const

Get the ID (usually filename) of the currently running script.

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

Runs preprocessed script code which has been generated using runPreprocessedScript().

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

preprocessedScript	the string containing the preprocessed script.
scriptId	The 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

Run the script located in the given file.

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

fileName	the location of the file containing the script.
includePath	the 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

Convenience method similar to runScriptDirect(const QString scriptId, const QString& scriptCode, int &errLoc, const QString &includePath = QString()); when scriptId and errLoc are not relevant.

(Required e.g. in RemoteControl)

◆ runScriptDirect [2/2]

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

slot

Runs the script code given.

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

scriptId	path name, if available, or something helpful
scriptCode	The script to execute
errLoc	offset of erroneous include line, or -1
includePath	If 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

Save output file to new file.

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

Parameters

filename new 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

Find out if a script is running.

Returns: true if a script is running, else false

◆ setScriptRate

void StelScriptMgr::setScriptRate ( double r )

slot

Changes the rate at which the script executes as a multiple of real time.

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

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

◆ stopScript

void StelScriptMgr::stopScript ( )

slot

Stops any running script.

Returns: false if no script was running, true otherwise.

Property Documentation

◆ flagAllowExternalScreenshotDir

bool StelScriptMgr::flagAllowExternalScreenshotDir

readwrite

Ensure that users must actively allow storing screenshots to directories configured in scripts.

If this is false, a directory dir given in StelMainScriptAPI::screenshot(prefix, invert, dir, ...) is ignored.

◆ flagAllowWriteAbsolutePaths

bool StelScriptMgr::flagAllowWriteAbsolutePaths

readwrite

Ensure that users must actively allow storing output data to absolute paths.

If this is false, the output file is stored to the user data directory.

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ addObject()

◆ debug

◆ getAuthor

◆ getDescription

◆ getFlagAllowExternalScreenshotDir

◆ getFlagAllowWriteAbsolutePaths

◆ getHtmlDescription

◆ getLicense

◆ getName

◆ getShortcut

◆ getVersion

◆ output

◆ pauseScript

◆ prepareScript

◆ preprocessScript()

◆ resumeScript

◆ runningScriptId()

◆ runPreprocessedScript

◆ runScript

◆ runScriptDirect [1/2]

◆ runScriptDirect [2/2]

◆ saveOutputAs

◆ scriptIsRunning()

◆ setScriptRate

◆ stopScript

Property Documentation

◆ flagAllowExternalScreenshotDir

◆ flagAllowWriteAbsolutePaths