The primary QML API to the Zuble plugin library. Zuble applications access this object through the javascript global name "Zbl". More...

#include <ZblApp.h>

Inheritance diagram for Zbl::ZblApp:

[legend]

Collaboration diagram for Zbl::ZblApp:

[legend]

Classes
class	AppPtr
	A mechanism for safely holding a ZblApp object pointer in thread local storage. More...

class	TimerMethodCall
	This inner class allows ZblApp to store javascript function pointers that are used to provide timer support to Zuble background threads. More...

Public Slots
void	throwAnException ()
	test method to throw a ZblException More...

void	throwDeeperException ()
	test method to throw a ZblException More...

void	catchDeeperException ()
	test method to throw and then catch a ZblException More...

QVariant	returnAnException ()
	test method to return a javascript Error object More...

void	throwException ()
	test method to throw an exception More...

QJSValue	error ()
	returns the internal Error object for this thread saved in thread local storage. More...

void	setError (QJSValue theObject)
	Sets the internal Javascript Error object. More...

bool	isError ()
	Determines if an error state exists for this thread. More...

void	clearError ()
	Clears an existing error condition for this thread. More...

QJSValue	convertEvaluateError (const QJSValue &evaluateError)
	Javascript syntax errors appear to be passing back a string object with the QJSValue error bit set, not an Error object per se. This method converts that object into an Error object with name and message properties, thus allowing consistent error processing logic. More...

QVariant	include (const QString &fileUrl)
	Loads the specified javascript file and executes it in the current javascript context. More...

int	startTimerInterval (QJSValue timerFunction, QJSValue timerArgument, int milliseconds)
	Calls the specified javascript function periodically at the specified interval. More...

void	stopTimerInterval (int timerID)
	Stops the specified timer. More...

void	stopAllTimers ()
	Stops all existing timers that were started with ZblApp::startTimerInterval() and destroys them. More...

void	collectGarbage ()
	Instructs the javascript engine to garbage collect memory as soon as possible. More...

void	alert (const QString signalID, QVariant payload, bool wait=false)
	Call this method to send an alert signal to the owning ZScriptThread object. More...

void	quit ()
	Calls quit() on the owning ZScriptThread object. More...

QString	readLine ()
	Reads a line of text from stdin. More...

void	print (const QString &text, bool newLine=true)
	Writes text to stdout. More...

void	printErr (const QString &text, bool newLine=true)
	Writes text to stderr. More...

void	onDestroyed (QObject *obj)
	Experimental, may be deprecated. More...

Signals
void	statusAvailable (const QString &text)
	Sent when text for the main applicaiton status is available. Connect to this signal to display status text to the user. More...

void	appPathsChanged ()
	Sent when Zuble application paths change. TBD: this should be never - just trying to satisfy QML binding engine by providing this here. More...

void	settingsBundleAvailable (QString bundleId)
	This signal is sent by the settings bundle manager when an application settings bundle is added to the settings bundle map. More...

void	exit (int returnCode)
	Exits the thread. When called by the main thread exits the application. More...

Public Member Functions
	ZblApp (QJSEngine scriptEngine, ZScriptThread container=nullptr, QObject *parent=nullptr)

virtual	~ZblApp ()

QJSEngine &	engine ()
	Returns the QJSEngine object associated with this object. More...

QString	errorMessage ()
	Returns a formatted error message from this thread's ZblThreadErr object. More...

QVariant	getAppTags ()
	Obtains a javascript dictionary object that maps application data item names to integer values, for use with ZApplication::getAppData method. More...

QString	getRootPath ()
	Obtains the canonical path to the Zuble application's root directory. More...

QString	getMainQmlPath ()
	Obtains the canonical path to the Zuble application's main QML file. More...

Q_INVOKABLE bool	isResourcePath (const QString &path)
	Determine if the specified path refers to a an object inside a Qt binary resource. More...

Q_INVOKABLE void	addLibraryPath (const QString &path)
	Add the specified path to the beginning of the library search path. More...

Q_INVOKABLE QString	resolveAppPath (const QString &path, bool includeUrlScheme=true)
	Converts Zuble application paths into canonical file paths. Zuble applicaiton paths are prefixed with "zbl://" and are relative to the current Zuble applicaton's home directory. More...

Q_INVOKABLE QString	resolveHomePath (const QString &path, bool includeUrlScheme=true)
	Converts Zuble home paths into canonical file paths. Zuble home paths are prefixed with "home://" and are relative to the current user's home directory. More...

Q_INVOKABLE QString	resolvePath (const QString &path, bool includeUrlScheme=true)
	Converts Zuble paths into canonical file paths. Zuble home paths are prefixed with "home://" and are relative to the current user's home directory, application paths are prefixed with "zbl://" and data paths are prefixed with "data://". More...

Q_INVOKABLE bool	isInMainThread ()
	Determine if the caller is currently executing in the Qt's main GUI thread. More...

Q_INVOKABLE void	sleep (unsigned long milliseconds)
	Blocks the current thread for the specified number of milliseconds. More...

Q_INVOKABLE void	sleepEvents (unsigned long milliseconds)
	Blocks the current thread for the specified number of milliseconds while processing events. More...

Q_INVOKABLE QVariant	getAppData (int dataKey)
	Allows background threads to obtain application object data. More...

Q_INVOKABLE QVariant	getAppName ()
	Obtains Zuble application name. More...

Q_INVOKABLE void	status (const QString &text)
	Sends status information to Zuble's main status text feed. More...

Q_INVOKABLE QObject *	newAppSettings (int scope, const QString &application, const QString &organization)
	Returns a new ZSettings object representing a JSON file in the platform-specific configuration file location. More...

Q_INVOKABLE QObject *	newByteArray ()
	Returns a new ZByteArray object for reading and writing byte arrays. More...

Q_INVOKABLE QObject *	newDataStream (QObject *byteArray)
	Returns a new ZDataStream object for reading and writing data in byte arrays. More...

Q_INVOKABLE QObject *	newDir ()
	Returns a new ZDir object for reading and manipulating file directories. More...

Q_INVOKABLE QObject *	newFile ()
	Returns a new ZFile object for reading, writing and manipulating files. More...

Q_INVOKABLE QObject *	newFileSystemWatcher ()
	Returns a new ZFileSystemWatcher object for detecting changes in files and directories. More...

Q_INVOKABLE QObject *	newTableModel ()
	Returns a new ZTableModel object for passing variant data to QML views. More...

Q_INVOKABLE QObject *	newTextStream (const QString &text)
	Returns a new ZTextStream object for reading and writing text in strings. More...

Q_INVOKABLE QObject *	newLogReader ()
	Returns a new ZLogReader object for reading Zuble log files. More...

Q_INVOKABLE QObject *	newObject (const QString &sprocketUri, const QString &objectName)
	Returns a new Zuble sprocket object from the specified sprocket extension plugin. More...

Q_INVOKABLE QObject *	newProcess ()
	Returns a new ZProcess object for creating an operating system process. More...

Q_INVOKABLE QObject *	newMailbox ()
	Returns a new ZMailbox object for passing messages between components. More...

Q_INVOKABLE QObject *	newMailslot ()
	Returns a new ZMailslot object for passing messages between components. More...

Q_INVOKABLE QObject *	newMap ()
	Returns a new ZMap object for mapping arbitrary strings to javascript values. More...

Q_INVOKABLE QObject *	newMessageQueue ()
	Returns a new ZMessageQueue object for passing messages between components. More...

Q_INVOKABLE QObject *	newSchemaValidator ()
	Returns a new ZSchemaValidator object for validating XML documents against XML schemas. More...

Q_INVOKABLE QObject *	newScopedMap ()
	Returns a new ZScopedMap object for mapping arbitrary strings to javascript values. More...

Q_INVOKABLE QObject *	newSettingsFile (const QString &filePath)
	Returns a new ZSettings object representing a JSON file in the specified file location. More...

Q_INVOKABLE QObject *	newThread ()
	Returns a new ZScriptThread object. More...

Q_INVOKABLE QObject *	newXmlQuery ()
	Returns a new ZxQuery object. More...

Q_INVOKABLE QObject *	bundleSettings (const QString &bundleID)
	Returns a new ZSettings object representing a JSON file in the location specified by the settings bundle ID. More...

Q_INVOKABLE QString	bundleMetapath (const QString &bundleID)
	Returns the path to the Zuble settings metadata file for the specified settings bundle ID. More...

Q_INVOKABLE QString	bundleMetadata (const QString &bundleID)
	Returns the Zuble settings metadata text for the specified settings bundle ID. More...

Q_INVOKABLE bool	import (const QString &sprocketUri, int versionMajor, int versionMinor)
	Makes a Zuble sprocket extension plugin available to background javascript threads. More...

Q_INVOKABLE bool	mapResource (const QString &uri, int versionMajor, int versionMinor, const QString &fileName)
	Called by Javascript programs to make binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor). More...

Q_INVOKABLE bool	registerResource (const QString &uri, int versionMajor, int versionMinor)
	Makes a Zuble resource file known to QML and background javascript programs. More...

Q_INVOKABLE bool	mapPluginResources (const QString &fileName, bool qmlregister=false)
	Make a plugin's binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor). More...

Q_INVOKABLE bool	loadPlugin (const char *fileName, bool load=false)
	Make a plugin's binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor). More...

Q_INVOKABLE QStringList	getApplicationArguments ()
	obtain a string array containing arguments passed on the command line More...

Q_INVOKABLE QStringList	getSystemEnvironment ()
	obtain a string array containing the process system environment More...

Q_INVOKABLE bool	isInterruptRequested ()
	Calls QThread::isInterruptRequested() on the current thread. Does nothing and returns false if current thread is the foreground thread. More...

Q_INVOKABLE QString	getCurrentThreadAddress ()
	Returns the human-readable memory address of the current thread. More...

Q_INVOKABLE QString	getObjectThreadAddress (QObject *object)
	Returns the human-readable memory address of the specified object's thread. More...

Q_INVOKABLE QObject *	getLogBuffer ()
	Obtain Zuble's log buffer data model. More...

Q_INVOKABLE QObject *	getLogRules ()
	Obtain Zuble's log category rules data model. More...

Static Public Member Functions
static ZblApp &	zInstance ()
	Obtains a reference to the ZblApp object for the current thread. More...

static QObject *	getSingletonType (QQmlEngine engine, QJSEngine scriptEngine)
	Obtains an new instance of this class. This is called by the QML engine to create the ZblApp object for the foreground (QML) thread. More...

static int	registerSingletonType ()
	Registers this object with QML as a singleton type. More...

Protected Member Functions
virtual ZBL_DECLARE_LOGGED_OBJECT void	timerEvent (QTimerEvent *event)
	Overloaded timer function to implement startTimerInterval. This method calls the specified timer's javascript callback function when it's timer event goes off. More...

void	createTags ()
	Create the m_tag object that presents a Javascript interface to ZApplication enumeration values. More...

Protected Attributes
QJSEngine *	m_engine
	The QJSEngine that owns the javascript context for this ZblApp object. More...

ZScriptThread *	m_container
	The ZScriptThread object that represents the thread in which ZblApp is running. More...

timerHash	m_scriptTimers
	A hash of javascript function/argument pairs keyed by timer ID. More...

factoryMap	m_factories
	Maps sprocket plugin uri's to ZblFactory objects. More...

Static Protected Attributes
static QThreadStorage< AppPtr * >	m_zApp
	ZblApp is a thread singleton - ie one ZblApp object exists per Zuble thread. This variable holds a pointer to each ZblApp object in thread local storage. More...

static QReadWriteLock	m_lock
	A lock for multi-threaded data access. More...

static QVariant	m_tags
	A QVariantMap used to pass ZApplication enumeration values to Javascript programs. More...

Properties
QVariant	tags
	Obtains a javascript dictionary object that maps application data item names to integer values. More...

QString	errorMessage
	Returns a formatted error message from this thread's ZblThreadErr object. More...

QString	rootPath
	Returns the canonical path to the Zuble application's root directory. More...

QString	mainQmlPath
	Returns the canonical path to the Zuble application's main QML file. More...

Private Types
typedef QHash< int, TimerMethodCall >	timerHash

typedef QList< int >	timerKeys

Private Slots
void	exitApp (int returnCode=0)
	Calls exit() on ??? the owning ZScriptThread object. More...

Detailed Description

The primary QML API to the Zuble plugin library. Zuble applications access this object through the javascript global name "Zbl".

The QML engine's foreground GUI thread and all ZScriptThread background threads each have their own instance of ZblApp. QML documents access ZblApp by importing the Zuble plugin library with the following line of code:

import org.zuble.qml 1.0

This makes the "Zbl" global object available to QML code. Foreground QML code creates QML extension objects by naming them. Example to create a ZFile object:

ZFile { id: myFile }

Background ZScriptThread objects create QML extension objects by calling the Zbl.newXXX methods on ZblApp. Example to create a ZFile object:

var myfile = Zbl.newFile();

This is important for ZScriptThread because background scripts run on QJSEngine instances and thus can't create objects directly through QML. Since the Qt object isn't available to background threads ZblApp emulates some of the Qt object's methods. Background threads don't use import statements. The "Zbl" global object is avaialble to background scripts immediately. It need not be imported.

Definition at line 81 of file ZblApp.h.

Member Typedef Documentation

◆ timerHash

typedef QHash<int, TimerMethodCall> Zbl::ZblApp::timerHash

private

Definition at line 105 of file ZblApp.h.

◆ timerKeys

typedef QList<int> Zbl::ZblApp::timerKeys

private

Definition at line 106 of file ZblApp.h.

Constructor & Destructor Documentation

◆ ZblApp()

Zbl::ZblApp::ZblApp	(	QJSEngine *	scriptEngine,
		ZScriptThread *	container = `nullptr`,
		QObject *	parent = `nullptr`
	)

explicit

Definition at line 65 of file ZblApp.cpp.

Referenced by getSingletonType().

◆ ~ZblApp()

Zbl::ZblApp::~ZblApp ( )

virtual

Definition at line 89 of file ZblApp.cpp.

Member Function Documentation

◆ addLibraryPath()

void ZblApp::addLibraryPath ( const QString & path )

Add the specified path to the beginning of the library search path.

Calls QCoreApplication::addLibraryPath() internally

Parameters

path	directory to add to the library path search path

Definition at line 782 of file ZblApp.cpp.

◆ alert

void ZblApp::alert	(	const QString	signalID,
		QVariant	payload,
		bool	wait = `false`
	)

slot

Call this method to send an alert signal to the owning ZScriptThread object.

Background script threads can call this method to send blocking or non-blocking signals to ZScriptThread::onAlert handlers.

When called from the foreground GUI thread this method does nothing and returns without error.

Parameters

signalID	user-defined signal identifier
payload	user-defined data. Note that this object is passed between threads as a JSON string.
wait	false (default) sends a queued signal and returns immediately, true sends a blocking queued signal and waits until all connections have processed the signal

Definition at line 986 of file ZblApp.cpp.

◆ appPathsChanged

void Zbl::ZblApp::appPathsChanged ( )

signal

Sent when Zuble application paths change. TBD: this should be never - just trying to satisfy QML binding engine by providing this here.

◆ bundleMetadata()

QString ZblApp::bundleMetadata ( const QString & bundleID )

Returns the Zuble settings metadata text for the specified settings bundle ID.

The bundle must have been previously registered with the ZSettings object as an atomic settings bundle.

Parameters

bundleID the settings bundle ID for which to return the metadata text

Returns: text of the metadata if this is an atomic settings bundle, an empty string otherwise

See also: Zbl::ZblApp::newAppSettings

Definition at line 851 of file ZblApp.cpp.

◆ bundleMetapath()

QString ZblApp::bundleMetapath ( const QString & bundleID )

Returns the path to the Zuble settings metadata file for the specified settings bundle ID.

The bundle must have been previously registered with the ZSettings object. This is normally done through mappings in the Zuble application's zblconfig.xml file.

Parameters

bundleID the settings bundle ID for which to return a metadata file path

Returns: path to the metadata file for the specified bundle

See also: Zbl::ZblApp::newAppSettings

Definition at line 843 of file ZblApp.cpp.

◆ bundleSettings()

QObject * ZblApp::bundleSettings ( const QString & bundleID )

Returns a new ZSettings object representing a JSON file in the location specified by the settings bundle ID.

The ZSettings object synchronizes reads and writes to JSON configuration files so that multiple processes and threads can safely access configuration files concurrently. This method creates the configuration files in the location specified by the settings bundle registered with the specified bundle ID value. The bundle must have been previously registered with the ZSettings object. This is normally done through mappings in the Zuble application's zblconfig.xml file.

Parameters

bundleID the settings bundle ID for which to return a ZSettings object

Returns: a ZSettings object

See also: Zbl::ZblApp::newAppSettings

Definition at line 651 of file ZblApp.cpp.

◆ catchDeeperException

void Zbl::ZblApp::catchDeeperException ( )

slot

test method to throw and then catch a ZblException

Definition at line 224 of file ZblApp.cpp.

◆ clearError

void Zbl::ZblApp::clearError ( )

slot

Clears an existing error condition for this thread.

Modifies the Zbl::ZblError object saved in thread local storage.

Definition at line 298 of file ZblApp.cpp.

◆ collectGarbage

void ZblApp::collectGarbage ( )

slot

Instructs the javascript engine to garbage collect memory as soon as possible.

Definition at line 978 of file ZblApp.cpp.

Referenced by sleepEvents().

◆ convertEvaluateError

QJSValue Zbl::ZblApp::convertEvaluateError ( const QJSValue & evaluateError )

slot

Javascript syntax errors appear to be passing back a string object with the QJSValue error bit set, not an Error object per se. This method converts that object into an Error object with name and message properties, thus allowing consistent error processing logic.

Returns: a Javascript Error object with name and message properties

Definition at line 317 of file ZblApp.cpp.

Referenced by Zbl::ZScriptWorker::execScript(), and include().

◆ createTags()

void Zbl::ZblApp::createTags ( )

protected

Create the m_tag object that presents a Javascript interface to ZApplication enumeration values.

Definition at line 105 of file ZblApp.cpp.

Referenced by ZblApp().

◆ engine()

QJSEngine & Zbl::ZblApp::engine ( )

inline

Returns the QJSEngine object associated with this object.

Returns: A QJSEngine object

Definition at line 1312 of file ZblApp.h.

◆ error

QJSValue Zbl::ZblApp::error ( )

slot

returns the internal Error object for this thread saved in thread local storage.

Returns: A Javascript Error object

Definition at line 306 of file ZblApp.cpp.

Referenced by Zbl::catch(), Zbl::ZScriptWorker::execScript(), include(), and returnAnException().

◆ errorMessage()

QString Zbl::ZblApp::errorMessage ( )

Returns a formatted error message from this thread's ZblThreadErr object.

Returns

Referenced by getLogRules().

◆ exit

void Zbl::ZblApp::exit ( int returnCode )

signal

Exits the thread. When called by the main thread exits the application.

This signal is connected to QCoreApplication::exit(int) with a queued connection.

Parameters

returnCode code that will be returned by QCoreApplication::exec()

Referenced by ZblApp().

◆ exitApp

void ZblApp::exitApp ( int returnCode = 0 )

privateslot

Calls exit() on ??? the owning ZScriptThread object.

When called from the foreground GUI thread this method does ??? nothing and returns without error.

Parameters

code	value that will be returned from exec()

See also: ZScriptThread::quit()

Definition at line 1129 of file ZblApp.cpp.

Referenced by ZblApp().

◆ getAppData()

QVariant ZblApp::getAppData ( int dataKey )

Allows background threads to obtain application object data.

Parameters

dataKey An integer key determines what data is returned.

Returns: A variant object containing the requested data.

Definition at line 399 of file ZblApp.cpp.

◆ getApplicationArguments()

QStringList ZblApp::getApplicationArguments ( )

obtain a string array containing arguments passed on the command line

Definition at line 738 of file ZblApp.cpp.

Referenced by getSystemEnvironment().

◆ getAppName()

QVariant ZblApp::getAppName ( )

Obtains Zuble application name.

Returns: A variant object containing the application name.

Definition at line 428 of file ZblApp.cpp.

◆ getAppTags()

QVariant Zbl::ZblApp::getAppTags ( )

Obtains a javascript dictionary object that maps application data item names to integer values, for use with ZApplication::getAppData method.

Returns: a javascript dictionary

Definition at line 156 of file ZblApp.cpp.

◆ getCurrentThreadAddress()

QString ZblApp::getCurrentThreadAddress ( )

Returns the human-readable memory address of the current thread.

Definition at line 765 of file ZblApp.cpp.

Referenced by Zbl::ZSettings::onFileChanged(), and quit().

◆ getLogBuffer()

QObject * Zbl::ZblApp::getLogBuffer ( )

Obtain Zuble's log buffer data model.

Returns: The ZTableModel object containing Zuble's log event histogram

Definition at line 195 of file ZblApp.cpp.

◆ getLogRules()

QObject * Zbl::ZblApp::getLogRules ( )

Obtain Zuble's log category rules data model.

Changes to this model will result in live updates to Qt/QML logging rules.

Returns: The ZTableModel object containing Zuble's log category rules.

Definition at line 200 of file ZblApp.cpp.

◆ getMainQmlPath()

QString ZblApp::getMainQmlPath ( )

Obtains the canonical path to the Zuble application's main QML file.

Returns

Definition at line 828 of file ZblApp.cpp.

◆ getObjectThreadAddress()

QString ZblApp::getObjectThreadAddress ( QObject * object )

Returns the human-readable memory address of the specified object's thread.

Parameters

object The object whose thread address will be returned.

Definition at line 774 of file ZblApp.cpp.

◆ getRootPath()

QString ZblApp::getRootPath ( )

Obtains the canonical path to the Zuble application's root directory.

Returns

Definition at line 823 of file ZblApp.cpp.

◆ getSingletonType()

QObject * Zbl::ZblApp::getSingletonType	(	QQmlEngine *	engine,
		QJSEngine *	scriptEngine
	)

static

Obtains an new instance of this class. This is called by the QML engine to create the ZblApp object for the foreground (QML) thread.

Parameters

engine
scriptEngine

Returns: A new ZblApp object for the foreground thread.

Definition at line 161 of file ZblApp.cpp.

Referenced by registerSingletonType().

◆ getSystemEnvironment()

QStringList ZblApp::getSystemEnvironment ( )

obtain a string array containing the process system environment

Definition at line 745 of file ZblApp.cpp.

◆ import()

bool ZblApp::import	(	const QString &	sprocketUri,
		int	versionMajor,
		int	versionMinor
	)

Makes a Zuble sprocket extension plugin available to background javascript threads.

This function should be called once for each Zuble sprocket plugin a javascript background thread will use. After calling this function use ZblApp::newObject to create objects defined by the sprocket.

WARNING: The uri of the plugin's QML module must have previously been imported with a QML import statement. TBD: or? config file?

Parameters

sprocketUri	uri of the sprocket
versionMajor	major version of the sprocket
versionMinor	minor version of the sprocket

See also: ZblApp::newObject

Definition at line 682 of file ZblApp.cpp.

◆ include

QVariant Zbl::ZblApp::include ( const QString & fileUrl )

slot

Loads the specified javascript file and executes it in the current javascript context.

Parameters

a	file path or url

Returns: result of javascript file execution

Definition at line 331 of file ZblApp.cpp.

◆ isError

bool Zbl::ZblApp::isError ( )

slot

Determines if an error state exists for this thread.

This action is performed by checking the state of the Zbl::ZblError object saved in thread local storage. Zbl::ZblException objects modify the error state when they are thrown.

Returns: true if an error state exists for this thread, false otherwise

Definition at line 291 of file ZblApp.cpp.

Referenced by Zbl::ZScriptWorker::execScript(), and include().

◆ isInMainThread()

bool ZblApp::isInMainThread ( )

Determine if the caller is currently executing in the Qt's main GUI thread.

Returns: true if the caller is executing in Qt's main thread, false if the caller is executing in a background thread;

Definition at line 450 of file ZblApp.cpp.

Referenced by addLibraryPath(), alert(), exitApp(), getAppData(), getAppName(), and quit().

◆ isInterruptRequested()

bool ZblApp::isInterruptRequested ( )

Calls QThread::isInterruptRequested() on the current thread. Does nothing and returns false if current thread is the foreground thread.

Background script threads should call this method periodically during long operations to determine if the operation should be cancelled and abort the operation if true is returned.

Avoid calling this method too frequently because to do so will negatively impact application performance.

Returns: return true if thread should shut down

Definition at line 754 of file ZblApp.cpp.

◆ isResourcePath()

bool ZblApp::isResourcePath ( const QString & path )

Determine if the specified path refers to a an object inside a Qt binary resource.

A resource path is prefixed with "qrc:/" or ":/"

Parameters

path	Path to test

Returns: true if specified path is a resource path, false otherwise

Definition at line 833 of file ZblApp.cpp.

◆ loadPlugin()

Q_INVOKABLE bool Zbl::ZblApp::loadPlugin	(	const char *	fileName,
		bool	load = `false`
	)

Make a plugin's binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor).

Zuble searches the plugin path to locate plugin files, and the library path to locate their binary resource files. (TBD: should we look in current dir of plugin first?)

Sprocket plugins may map zero or more binary resource files by uri. Zuble QML programs may also map resource files by calling Zbl.mapPluginResource().

See also: ZblApp::loadResource(); ZblApp::mapPluginResource(); ZblCog::registerSprocket()

Parameters

fileName	plugin file name with no extension (platform-specific extension will be determined by Qt)
load	true = load plugin binary after mapping resource bundle, false = map resource bundle but don't load plugin binary

Returns: true if plugin resources mapped/loaded successfully, false if failed

◆ mapPluginResources()

bool ZblApp::mapPluginResources	(	const QString &	fileName,
		bool	qmlregister = `false`
	)

Make a plugin's binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor).

Zuble searches the plugin path to locate plugin files. The plugin file's metadata is assumed to contain an array of resource file mappings that bind a resource uri and version number to resource file names. This array is known as the plugin's "resource bundle". Zuble serches the library path to locate binary resource files listed in the resource bundle. (TBD: should we look in current dir of plugin first?)

Sprocket plugins may map zero or more binary resource files by uri. Zuble QML programs may also map their own resource files directly in Javascript by calling Zbl.mapPluginResource().

See also: ZblApp::loadResource(); ZblApp::mapPluginResource(); ZblCog::registerSprocket()

Parameters

fileName	plugin file name with no extension (platform-specific extension will be determined by Qt)
qmlregister	true = register resource files with QML after mapping resource bundle; false = map resource bundle but don't register resource files

Returns: true if plugin resources mapped/loaded successfully, false if failed

Definition at line 729 of file ZblApp.cpp.

◆ mapResource()

bool ZblApp::mapResource	(	const QString &	uri,
		int	versionMajor,
		int	versionMinor,
		const QString &	fileName
	)

Called by Javascript programs to make binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor).

Note that versionMajor and versionMinor should be the same as those passed in the sprocket's ZblCog::registerSprocket() function call to ensure the resource bundle/plugin binary pair are compatible.

Sprocket plugins may map zero or more binary resource files by uri. Zuble Javascript programs may also map resource files by calling Zbl.mapResource.

Zuble searches the library path to locate binary resource files.

See also: ZblApp::loadResource(); ZblCog::registerSprocket()

Parameters

uri	Resource's uri
versionMajor	Resource's major version number
versionMinor	Resource's minor version number
fileName	path to the binary resource file

Returns: true if object registered successfully, false if registration failed

Definition at line 706 of file ZblApp.cpp.

◆ newAppSettings()

QObject * ZblApp::newAppSettings	(	int	scope,
		const QString &	application,
		const QString &	organization
	)

Returns a new ZSettings object representing a JSON file in the platform-specific configuration file location.

The ZSettings object synchronizes reads and writes to JSON configuration files so that multiple processes and threads can safely access configuration files concurrently. This method creates the configuration files in the appropriate file directories for the platform on which the Zuble applicaiton is running.

The file name to open is determined using either the specified application and organization names, or the Zuble default values if those names aren't specified.

Scope determines whether the settings affected are user or system scope. User scope settings affect only the current user, system scope settings affect all users of the application on the current system. See the Qt 5 QSettings class documentation for more information.

Parameters

scope	QML: Zbl.tags.SettingsSystemScope or Zbl.tags.SettingsUserScope; C++: QSettings::SystemScope or of QSettings::UserScope;
application	the application name to use for the settings file. The default is the name of the zbl application.
organization	The organization to use for the settings file. The default is either "zuble" or "zuble.org" (MacOS-X).

Returns: a ZSettings object

See also: Zbl::ZblApp::newSettingsFile

Definition at line 598 of file ZblApp.cpp.

◆ newByteArray()

QObject * ZblApp::newByteArray ( )

Returns a new ZByteArray object for reading and writing byte arrays.

Definition at line 469 of file ZblApp.cpp.

◆ newDataStream()

QObject * ZblApp::newDataStream ( QObject * byteArray )

Returns a new ZDataStream object for reading and writing data in byte arrays.

Definition at line 515 of file ZblApp.cpp.

◆ newDir()

QObject * ZblApp::newDir ( )

Returns a new ZDir object for reading and manipulating file directories.

Definition at line 455 of file ZblApp.cpp.

◆ newFile()

QObject * ZblApp::newFile ( )

Returns a new ZFile object for reading, writing and manipulating files.

Definition at line 462 of file ZblApp.cpp.

◆ newFileSystemWatcher()

QObject * ZblApp::newFileSystemWatcher ( )

Returns a new ZFileSystemWatcher object for detecting changes in files and directories.

Definition at line 526 of file ZblApp.cpp.

◆ newLogReader()

QObject * ZblApp::newLogReader ( )

Returns a new ZLogReader object for reading Zuble log files.

See also: ZSMap

Definition at line 583 of file ZblApp.cpp.

◆ newMailbox()

QObject * ZblApp::newMailbox ( )

Returns a new ZMailbox object for passing messages between components.

Definition at line 562 of file ZblApp.cpp.

◆ newMailslot()

QObject * ZblApp::newMailslot ( )

Returns a new ZMailslot object for passing messages between components.

Definition at line 548 of file ZblApp.cpp.

◆ newMap()

QObject * ZblApp::newMap ( )

Returns a new ZMap object for mapping arbitrary strings to javascript values.

See also: ZScopedMap

Definition at line 569 of file ZblApp.cpp.

◆ newMessageQueue()

QObject * ZblApp::newMessageQueue ( )

Returns a new ZMessageQueue object for passing messages between components.

Definition at line 541 of file ZblApp.cpp.

◆ newObject()

QObject * ZblApp::newObject	(	const QString &	sprocketUri,
		const QString &	objectName
	)

Returns a new Zuble sprocket object from the specified sprocket extension plugin.

Call ZblApp.import() once with the specified sprocketUri before you call this function to create objects from that sprocket.

Parameters

sprocketUri	uri of the sprocket
objectName	name of the object to create

Returns: the object created by the sprocket, or NULL if no object was created

Definition at line 660 of file ZblApp.cpp.

◆ newProcess()

QObject * ZblApp::newProcess ( )

Returns a new ZProcess object for creating an operating system process.

Definition at line 555 of file ZblApp.cpp.

◆ newSchemaValidator()

QObject * ZblApp::newSchemaValidator ( )

Returns a new ZSchemaValidator object for validating XML documents against XML schemas.

Definition at line 591 of file ZblApp.cpp.

◆ newScopedMap()

QObject * ZblApp::newScopedMap ( )

Returns a new ZScopedMap object for mapping arbitrary strings to javascript values.

Only string, number and boolean types are supported.

Definition at line 576 of file ZblApp.cpp.

◆ newSettingsFile()

QObject * ZblApp::newSettingsFile ( const QString & filePath )

Returns a new ZSettings object representing a JSON file in the specified file location.

The ZSettings object synchronizes reads and writes to JSON configuration files so that multiple processes and threads can safely access configuration files concurrently. This method creates the configuration files in the location specified by the filePath parameter.

Parameters

filePath the path of the JSON configuration file to open

Returns: a ZSettings object

See also: Zbl::ZblApp::newAppSettings

Definition at line 619 of file ZblApp.cpp.

◆ newTableModel()

QObject * ZblApp::newTableModel ( )

Returns a new ZTableModel object for passing variant data to QML views.

Definition at line 534 of file ZblApp.cpp.

◆ newTextStream()

QObject * ZblApp::newTextStream ( const QString & text )

Returns a new ZTextStream object for reading and writing text in strings.

Definition at line 476 of file ZblApp.cpp.

◆ newThread()

QObject * ZblApp::newThread ( )

Returns a new ZScriptThread object.

ZScriptThread allows Javascript code to be run in a background thread.

Returns: a ZScriptThread object

Definition at line 644 of file ZblApp.cpp.

◆ newXmlQuery()

QObject * ZblApp::newXmlQuery ( )

Returns a new ZxQuery object.

The ZxQuery object encapsulates a QXmlQuery object that can be used to read data from XML data sources.

Returns: a ZxQuery object

See also: Zbl::ZxQuery, Zbl::ZxResultItems, Zbl::ZxItem

Definition at line 637 of file ZblApp.cpp.

◆ onDestroyed

void ZblApp::onDestroyed ( QObject * obj )

slot

Experimental, may be deprecated.

Parameters

obj

Definition at line 1150 of file ZblApp.cpp.

Referenced by ZblApp().

◆ print

void ZblApp::print	(	const QString &	text,
		bool	newLine = `true`
	)

slot

Writes text to stdout.

Parameters

text	string to write
newLine	false writes text as is, true automatically appends a newline character to text (default=true)

Definition at line 494 of file ZblApp.cpp.

◆ printErr

void ZblApp::printErr	(	const QString &	text,
		bool	newLine = `true`
	)

slot

Writes text to stderr.

Parameters

text	string to write
newLine	false writes text as is, true automatically appends a newline character to text (default=true)

Definition at line 504 of file ZblApp.cpp.

◆ quit

void ZblApp::quit ( )

slot

Calls quit() on the owning ZScriptThread object.

When called from the foreground GUI thread this method does nothing ??? and returns without error.

See also: ZScriptThread::quit()

Definition at line 1096 of file ZblApp.cpp.

◆ readLine

QString ZblApp::readLine ( )

slot

Reads a line of text from stdin.

This method will block the current thread until input is available.

Returns: The string that was read.

Definition at line 485 of file ZblApp.cpp.

◆ registerResource()

bool ZblApp::registerResource	(	const QString &	uri,
		int	versionMajor,
		int	versionMinor
	)

Makes a Zuble resource file known to QML and background javascript programs.

This function should be called once for each Zuble binary resource file a Zuble program will use. After calling this function use QML import statements or ZFile to load objects from the resource file's objects.

TBD: this warning below may be false! needs review... WARNING: When using sprocket plugin resource files the uri of the plugin's QML module must have previously been imported with a QML import statement. Otherwise the uri of the resource file must be registered with Zbl.registerResource or ZblCog::registerResource.

Parameters

uri	uri of the sprocket
versionMajor	major version of the sprocket
versionMinor	minor version of the sprocket

See also: ZblApp::mapResource; ZblCog::loadResource

Definition at line 719 of file ZblApp.cpp.

◆ registerSingletonType()

int Zbl::ZblApp::registerSingletonType ( )

static

Registers this object with QML as a singleton type.

ZblApp is a THREAD-based singleton: One instance of ZblApp exists in the foreground thread for QML documents.

Each instance of ZScriptThread creates a separate ZblApp instance for its background thread.

Returns: The QML type id

Definition at line 174 of file ZblApp.cpp.

Referenced by Zbl::Zblcore::registerTypes().

◆ resolveAppPath()

QString ZblApp::resolveAppPath	(	const QString &	path,
		bool	includeUrlScheme = `true`
	)

Converts Zuble application paths into canonical file paths. Zuble applicaiton paths are prefixed with "zbl://" and are relative to the current Zuble applicaton's home directory.

example: zbl://myfile.js for Zuble application "myapp" is converted to /zuble/apps/myapp/myfile.js

Parameters

path	File path to be converted
includeUrlScheme	returned path will be prefixed with "file://" if true, default value is true

Definition at line 805 of file ZblApp.cpp.

Referenced by include().

◆ resolveHomePath()

QString ZblApp::resolveHomePath	(	const QString &	path,
		bool	includeUrlScheme = `true`
	)

Converts Zuble home paths into canonical file paths. Zuble home paths are prefixed with "home://" and are relative to the current user's home directory.

example: home://myfile.js for user "Fred" is converted to /home/Fred/myfile.js

Parameters

path	File path to be converted
includeUrlScheme	returned path will be prefixed with "file://" if true, default value is true

Definition at line 811 of file ZblApp.cpp.

◆ resolvePath()

QString ZblApp::resolvePath	(	const QString &	path,
		bool	includeUrlScheme = `true`
	)

Converts Zuble paths into canonical file paths. Zuble home paths are prefixed with "home://" and are relative to the current user's home directory, application paths are prefixed with "zbl://" and data paths are prefixed with "data://".

example: home://myfile.js for user "Fred" is converted to /home/Fred/myfile.js

Parameters

path	File path to be converted
includeUrlScheme	returned path will be prefixed with "file://" if true, default value is true

Definition at line 818 of file ZblApp.cpp.

◆ returnAnException

QVariant Zbl::ZblApp::returnAnException ( )

slot

test method to return a javascript Error object

Returns

Definition at line 258 of file ZblApp.cpp.

Referenced by throwException().

◆ setError

void Zbl::ZblApp::setError ( QJSValue theObject )

slot

Sets the internal Javascript Error object.

This action propagates the error to the Zbl::ZblThreadErr object in thread local storage

Parameters

theObject

Definition at line 269 of file ZblApp.cpp.

Referenced by returnAnException(), and throwException().

◆ settingsBundleAvailable

void Zbl::ZblApp::settingsBundleAvailable ( QString bundleId )

signal

This signal is sent by the settings bundle manager when an application settings bundle is added to the settings bundle map.

Parameters

bundleId

◆ sleep()

void ZblApp::sleep ( unsigned long milliseconds )

Blocks the current thread for the specified number of milliseconds.

This is used for testing thread synchronization.

Parameters

milliseconds Number of milliseconds to block current thread

Definition at line 938 of file ZblApp.cpp.

◆ sleepEvents()

void ZblApp::sleepEvents ( unsigned long milliseconds )

Blocks the current thread for the specified number of milliseconds while processing events.

This is used for testing thread synchronization.

Parameters

milliseconds Number of milliseconds to block current thread

Definition at line 947 of file ZblApp.cpp.

◆ startTimerInterval

int ZblApp::startTimerInterval	(	QJSValue	timerFunction,
		QJSValue	timerArgument,
		int	milliseconds
	)

slot

Calls the specified javascript function periodically at the specified interval.

This is intended for background scripts that can't use QML timers.

Parameters

timerFunction	A javascript function to call
milliseconds	Number of milliseconds between function calls

Returns: A timer ID that can be used to stop the timer

Definition at line 860 of file ZblApp.cpp.

◆ status()

void ZblApp::status ( const QString & text )

Sends status information to Zuble's main status text feed.

Parameters

text	The text to display in the status text stream.

Definition at line 385 of file ZblApp.cpp.

Referenced by include().

◆ statusAvailable

void Zbl::ZblApp::statusAvailable ( const QString & text )

signal

Sent when text for the main applicaiton status is available. Connect to this signal to display status text to the user.

Parameters

text	The status text

Referenced by ZblApp().

◆ stopAllTimers

void ZblApp::stopAllTimers ( )

slot

Stops all existing timers that were started with ZblApp::startTimerInterval() and destroys them.

Definition at line 917 of file ZblApp.cpp.

Referenced by ~ZblApp().

◆ stopTimerInterval

void ZblApp::stopTimerInterval ( int timerID )

slot

Stops the specified timer.

Parameters

timerID A timer ID value returned by a previous call to ZblApp::startTimerInterval()

Definition at line 887 of file ZblApp.cpp.

◆ throwAnException

void Zbl::ZblApp::throwAnException ( )

slot

test method to throw a ZblException

Definition at line 210 of file ZblApp.cpp.

◆ throwDeeperException

void Zbl::ZblApp::throwDeeperException ( )

slot

test method to throw a ZblException

Definition at line 215 of file ZblApp.cpp.

◆ throwException

void Zbl::ZblApp::throwException ( )

slot

test method to throw an exception

Definition at line 241 of file ZblApp.cpp.

Referenced by catchDeeperException(), and throwDeeperException().

◆ timerEvent()

void ZblApp::timerEvent ( QTimerEvent * event )

protectedvirtual

Overloaded timer function to implement startTimerInterval. This method calls the specified timer's javascript callback function when it's timer event goes off.

Parameters

event Timer event object identifies which timer function to call

Definition at line 898 of file ZblApp.cpp.

◆ zInstance()

ZblApp & Zbl::ZblApp::zInstance ( )

static

Obtains a reference to the ZblApp object for the current thread.

Returns: A reference to the ZblApp object for the current thread.

Definition at line 96 of file ZblApp.cpp.

Referenced by Zbl::ZSettings::onFileChanged().

Member Data Documentation

◆ m_container

ZScriptThread* Zbl::ZblApp::m_container

protected

The ZScriptThread object that represents the thread in which ZblApp is running.

Null if the ZblApp object is running in the main GUI thread. Note that m_container is running in ZScriptThread's originating thread while ZblApp is running in ZScriptThread's background QThread.

Definition at line 1286 of file ZblApp.h.

Referenced by alert(), and quit().

◆ m_engine

QJSEngine* Zbl::ZblApp::m_engine

protected

The QJSEngine that owns the javascript context for this ZblApp object.

Definition at line 1275 of file ZblApp.h.

Referenced by collectGarbage(), convertEvaluateError(), error(), exitApp(), include(), quit(), and timerEvent().

◆ m_factories

factoryMap Zbl::ZblApp::m_factories

protected

Maps sprocket plugin uri's to ZblFactory objects.

Definition at line 1307 of file ZblApp.h.

Referenced by import(), and newObject().

◆ m_lock

QReadWriteLock Zbl::ZblApp::m_lock

staticprotected

A lock for multi-threaded data access.

Definition at line 1268 of file ZblApp.h.

Referenced by clearError(), isError(), and setError().

◆ m_scriptTimers

timerHash Zbl::ZblApp::m_scriptTimers

protected

A hash of javascript function/argument pairs keyed by timer ID.

Definition at line 1300 of file ZblApp.h.

Referenced by startTimerInterval(), stopAllTimers(), stopTimerInterval(), and timerEvent().

◆ m_tags

QVariant Zbl::ZblApp::m_tags

staticprotected

A QVariantMap used to pass ZApplication enumeration values to Javascript programs.

Definition at line 1293 of file ZblApp.h.

Referenced by createTags(), and getAppTags().

◆ m_zApp

QThreadStorage< ZblApp::AppPtr * > Zbl::ZblApp::m_zApp

staticprotected

ZblApp is a thread singleton - ie one ZblApp object exists per Zuble thread. This variable holds a pointer to each ZblApp object in thread local storage.

Definition at line 1263 of file ZblApp.h.

Referenced by ZblApp(), and zInstance().

Property Documentation

◆ errorMessage

QString Zbl::ZblApp::errorMessage

read

Returns a formatted error message from this thread's ZblThreadErr object.

Definition at line 182 of file ZblApp.h.

◆ mainQmlPath

QString Zbl::ZblApp::mainQmlPath

read

Returns the canonical path to the Zuble application's main QML file.

Definition at line 200 of file ZblApp.h.

◆ rootPath

QString Zbl::ZblApp::rootPath

read

Returns the canonical path to the Zuble application's root directory.

Zuble translates all paths beginning with "zbl://" to be rooted in this directory.

Definition at line 193 of file ZblApp.h.

◆ tags

QVariant Zbl::ZblApp::tags

read

Obtains a javascript dictionary object that maps application data item names to integer values.

These constant values pertain to

ZApplication::getAppData method
ZblLogManager data model fields
ZblLogManager logging rules
QML Settings

Returns: a javascript dictionary

Definition at line 175 of file ZblApp.h.

The documentation for this class was generated from the following files:

zblcore/ZblApp.h
zblcore/ZblApp.cpp

Classes

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Properties

Private Types

Private Slots

Detailed Description

Member Typedef Documentation

◆ timerHash

◆ timerKeys

Constructor & Destructor Documentation

◆ ZblApp()

◆ ~ZblApp()

Member Function Documentation

◆ addLibraryPath()

◆ alert

◆ appPathsChanged

◆ bundleMetadata()

◆ bundleMetapath()

◆ bundleSettings()

◆ catchDeeperException

◆ clearError

◆ collectGarbage

◆ convertEvaluateError

◆ createTags()

◆ engine()

◆ error

◆ errorMessage()

◆ exit

◆ exitApp

◆ getAppData()

◆ getApplicationArguments()

◆ getAppName()

◆ getAppTags()

◆ getCurrentThreadAddress()

◆ getLogBuffer()

◆ getLogRules()

◆ getMainQmlPath()

◆ getObjectThreadAddress()

◆ getRootPath()

◆ getSingletonType()

◆ getSystemEnvironment()

◆ import()

◆ include

◆ isError

◆ isInMainThread()

◆ isInterruptRequested()

◆ isResourcePath()

◆ loadPlugin()

◆ mapPluginResources()

◆ mapResource()

◆ newAppSettings()

◆ newByteArray()

◆ newDataStream()

◆ newDir()

◆ newFile()

◆ newFileSystemWatcher()

◆ newLogReader()

◆ newMailbox()

◆ newMailslot()

◆ newMap()

◆ newMessageQueue()

◆ newObject()

◆ newProcess()

◆ newSchemaValidator()

◆ newScopedMap()

◆ newSettingsFile()

◆ newTableModel()

◆ newTextStream()

◆ newThread()

◆ newXmlQuery()

◆ onDestroyed

◆ print

◆ printErr

◆ quit