QJSEngine Class▲
-
Header: QJSEngine
-
CMake:
find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
-
qmake: QT += qml
-
Inherits: QObject
-
Inherited By: QQmlEngine
-
Group: QJSEngine is part of qtjavascript
Detailed Description▲
Evaluating Scripts▲
Use evaluate() to evaluate script code.
QJSEngine myEngine;
QJSValue three =
myEngine.evaluate("1 + 2"
);
evaluate() returns a QJSValue that holds the result of the evaluation. The QJSValue class provides functions for converting the result to various C++ types (e.g. QJSValue::toString() and QJSValue::toNumber()).
The following code snippet shows how a script function can be defined and then invoked from C++ using QJSValue::call():
QJSValue fun =
myEngine.evaluate("(function(a, b) { return a + b; })"
);
QJSValueList args;
args &
lt;&
lt; 1
&
lt;&
lt; 2
;
QJSValue threeAgain =
fun.call(args);
As can be seen from the above snippets, a script is provided to the engine in the form of a string. One common way of loading scripts is by reading the contents of a file and passing it to evaluate():
QString fileName =
"helloworld.qs"
;
QFile scriptFile(fileName);
if
(!
scriptFile.open(QIODevice::
ReadOnly))
// handle error
QTextStream stream(&
amp;scriptFile);
QString contents =
stream.readAll();
scriptFile.close();
myEngine.evaluate(contents, fileName);
Here we pass the name of the file as the second argument to evaluate(). This does not affect evaluation in any way; the second argument is a general-purpose string that is stored in the Error object for debugging purposes.
For larger pieces of functionality, you may want to encapsulate your code and data into modules. A module is a file that contains script code, variables, etc., and uses export statements to describe its interface towards the rest of the application. With the help of import statements, a module can refer to functionality from other modules. This allows building a scripted application from smaller connected building blocks in a safe way. In contrast, the approach of using evaluate() carries the risk that internal variables or functions from one evaluate() call accidentally pollute the global object and affect subsequent evaluations.
The following example provides a module that can add numbers:
export
function sum(left, right)
{
return
left +
right
}
This module can be loaded with QJSEngine::import() if it is saved under the name math.mjs:
QJSvalue module
=
myEngine.import
Module("./math.mjs"
);
QJSValue sumFunction =
module
.property("sum"
);
QJSValue result =
sumFunction.call(args);
Modules can also use functionality from other modules using import statements:
import
{ sum } from "./math.mjs"
;
export
function addTwice(left, right)
{
return
sum(left, right) *
2
;
}
Modules don't have to be files. They can be values registered with QJSEngine::registerModule():
import
version from "version"
;
export
function getVersion()
{
return
version;
}
QJSValue version(610
);
myEngine.registerModule("version"
, version);
QJSValue module
=
myEngine.import
Module("./myprint.mjs"
);
QJSValue getVersion =
module
.property("getVersion"
);
QJSValue result =
getVersion.call();
Named exports are supported, but because they are treated as members of an object, the default export must be an ECMAScript object. Most of the newXYZ functions in QJSValue will return an object.
QJSValue name("Qt6"
);
QJSValue obj =
myEngine.newObject();
obj.setProperty("name"
, name);
myEngine.registerModule("info"
, obj);
import
{ name } from "info"
;
export
function getName()
{
return
name;
}
Engine Configuration▲
The globalObject() function returns the Global Object associated with the script engine. Properties of the Global Object are accessible from any script code (i.e. they are global variables). Typically, before evaluating "user" scripts, you will want to configure a script engine by adding one or more properties to the Global Object:
myEngine.globalObject().setProperty("myNumber"
, 123
);
...
QJSValue myNumberPlusOne =
myEngine.evaluate("myNumber + 1"
);
Adding custom properties to the scripting environment is one of the standard means of providing a scripting API that is specific to your application. Usually these custom properties are objects created by the newQObject() or newObject() functions.