QJSEngine Class

Fonction membre Documentation

QJSEngine::QJSEngine()

Construit un objet QJSEngine.

L'objet globalObject() est initialisé pour avoir les propriétés décrites dans la section 15.1 de l 'ECMA-262.

[explicit] QJSEngine::QJSEngine(QObject *parent)

Construit un objet QJSEngine avec l'adresse parent.

L'objet globalObject() est initialisé pour avoir les propriétés décrites dans la section 15.1 de l 'ECMA-262.

[override virtual noexcept] QJSEngine::~QJSEngine()

Détruit ce QJSEngine.

Les déchets ne sont pas collectés dans le tas persistant de JS pendant la destruction de QJSEngine. Si vous avez besoin de libérer toute la mémoire, appelez collectGarbage() manuellement juste avant de détruire QJSEngine.

[since Qt 6.1] QJSValue QJSEngine::catchError()

Si une exception est en cours, il l'attrape et la renvoie sous forme de QJSValue. Sinon, il renvoie une valeur non définie sous forme de QJSValue. Après avoir appelé cette méthode, hasError() renvoie false.

Cette fonction a été introduite dans Qt 6.1.

template <typename From, typename To> To QJSEngine::coerceValue(const From &from)

Renvoie l'adresse from convertie au type de modèle To. La conversion est effectuée dans la sémantique JavaScript. Cette sémantique diffère de celle de qvariant_cast. Il existe un certain nombre de conversions implicites entre les types équivalents à JavaScript qui ne sont pas effectuées par défaut par qvariant_cast. Cette méthode est une généralisation de toutes les autres méthodes de conversion de cette classe.

Voir aussi fromVariant(), qvariant_cast(), fromScriptValue() et toScriptValue().

void QJSEngine::collectGarbage()

Exécute le ramasse-miettes.

Le ramasse-miettes tentera de récupérer de la mémoire en localisant et en éliminant les objets qui ne sont plus accessibles dans l'environnement du script.

Normalement, vous n'avez pas besoin d'appeler cette fonction ; le ramasse-miettes est automatiquement appelé lorsque QJSEngine décide qu'il est judicieux de le faire (c'est-à-dire lorsqu'un certain nombre de nouveaux objets ont été créés). Toutefois, vous pouvez appeler cette fonction pour demander explicitement que le ramasse-miettes soit exécuté dès que possible.

Voir aussi Garbage Collection et gc().

QJSValue QJSEngine::evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1, QStringList *exceptionStackTrace = nullptr)

Évalue program, en utilisant lineNumber comme numéro de ligne de base, et renvoie le résultat de l'évaluation.

Le code du script sera évalué dans le contexte de l'objet global.

L'évaluation de program peut provoquer une exception dans le moteur ; dans ce cas, la valeur de retour sera l'exception qui a été levée (typiquement un objet Error; voir QJSValue::isError()).

lineNumber est utilisé pour spécifier un numéro de ligne de départ pour program; les informations relatives au numéro de ligne communiquées par le moteur pour cette évaluation seront basées sur cet argument. Par exemple, si program se compose de deux lignes de code et que l'instruction de la deuxième ligne provoque une exception de script, le numéro de la ligne d'exception sera lineNumber plus un. Si aucun numéro de ligne de départ n'est spécifié, les numéros de ligne seront basés sur 1.

fileName est utilisé pour les rapports d'erreur. Par exemple, dans les objets d'erreur, le nom du fichier est accessible via la propriété "fileName" si elle est fournie avec cette fonction.

exceptionStackTrace est utilisé pour signaler si une exception non capturée a été levée. Si vous lui passez un pointeur non nul vers une adresse QStringList, elle lui attribuera la valeur "stackframe messages" si le script a déclenché une exception non gérée, ou une liste vide dans le cas contraire. Un message de pile a le format suivant : nom de la fonction, numéro de ligne, colonne, nom du fichier.

Voir également QQmlExpression::evaluate.

template <typename T> T QJSEngine::fromManagedValue(const QJSManagedValue &value)

Renvoie l'adresse value donnée convertie au type de modèle T.

Voir aussi toManagedValue() et coerceValue().

template <typename T> T QJSEngine::fromPrimitiveValue(const QJSPrimitiveValue &value)

Renvoie la valeur value convertie dans le type de modèle T.

Comme QJSPrimitiveValue ne peut contenir que int, bool, double, QString, et les équivalents de JavaScript null et undefined, la valeur sera contrainte agressivement si vous demandez un autre type.

Voir aussi toPrimitiveValue() et coerceValue().

template <typename T> T QJSEngine::fromScriptValue(const QJSValue &value)

Renvoie l'adresse value donnée convertie au type de modèle T.

Voir aussi toScriptValue() et coerceValue().

template <typename T> T QJSEngine::fromVariant(const QVariant &value)

Renvoie l'adresse value convertie au type de modèle T. La conversion est effectuée dans la sémantique JavaScript. Cette sémantique diffère de celle de qvariant_cast. Il existe un certain nombre de conversions implicites entre des types équivalents à JavaScript qui ne sont pas effectuées par défaut par qvariant_cast.

Voir aussi coerceValue(), fromScriptValue(), et qvariant_cast().

QJSValue QJSEngine::globalObject() const

Renvoie l'objet global de ce moteur.

Par défaut, l'objet global contient les objets intégrés qui font partie de l'ECMA-262, tels que Math, Date et String. En outre, vous pouvez définir les propriétés de l'objet global afin que vos propres extensions soient accessibles à l'ensemble du code de script. Les variables non locales du code de script seront créées en tant que propriétés de l'objet global, de même que les variables locales du code global.

[since Qt 6.1] bool QJSEngine::hasError() const

Renvoie true si la dernière exécution JavaScript a donné lieu à une exception ou si throwError() a été appelé. Sinon, il renvoie false. Notez que evaluate() attrape toutes les exceptions lancées dans le code évalué.

Cette fonction a été introduite dans Qt 6.1.

QJSValue QJSEngine::importModule(const QString &fileName)

Importe le module situé à l'adresse fileName et renvoie un objet d'espace de noms de module qui contient toutes les variables, constantes et fonctions exportées en tant que propriétés.

Si c'est la première fois que le module est importé dans le moteur, le fichier est chargé à partir de l'emplacement spécifié dans le système de fichiers local ou dans le système de ressources Qt et évalué comme un module ECMAScript. Le fichier est censé être encodé en texte UTF-8.

Les importations ultérieures du même module renverront l'instance précédemment importée. Les modules sont des singletons et restent présents jusqu'à ce que le moteur soit détruit.

L'adresse fileName spécifiée sera normalisée en interne à l'aide de QFileInfo::canonicalFilePath(). Cela signifie que plusieurs importations du même fichier sur le disque en utilisant des chemins relatifs différents ne chargeront le fichier qu'une seule fois.

Voir aussi registerModule().

void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue())

Installe JavaScript extensions pour ajouter des fonctionnalités qui ne sont pas disponibles dans une implémentation ECMAScript standard.

Les extensions sont installées sur le site object ou sur le site Global Object si aucun objet n'est spécifié.

Plusieurs extensions peuvent être installées en même temps en OR-ing les valeurs de l'énumération :

installExtensions(QJSEngine::TranslationExtension | QJSEngine::ConsoleExtension);

Voir également Extension.

bool QJSEngine::isInterrupted() const

Indique si l'exécution de JavaScript est actuellement interrompue.

Voir également setInterrupted().

QJSValue QJSEngine::newArray(uint length = 0)

Crée un objet JavaScript de la classe Array avec l'adresse length.

Voir aussi newObject().

QJSValue QJSEngine::newErrorObject(QJSValue::ErrorType errorType, const QString &message = QString())

Crée un objet JavaScript de la classe Error, avec message comme message d'erreur.

Le prototype de l'objet créé sera errorType.

Voir aussi newObject(), throwError() et QJSValue::isError().

QJSValue QJSEngine::newObject()

Crée un objet JavaScript de la classe Object.

Le prototype de l'objet créé sera l'objet prototype Object.

Voir aussi newArray() et QJSValue::setProperty().

template <typename T> QJSValue QJSEngine::newQMetaObject()

Crée un objet JavaScript qui englobe la statique QMetaObject associée à la classe T.

Voir également newQObject() et QObject Integration.

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

Crée un objet JavaScript qui englobe l'objet QMetaObject. L'objet metaObject doit survivre au moteur de script. Il est recommandé de n'utiliser cette méthode qu'avec des métaobjets statiques.

Lorsqu'elle est appelée en tant que constructeur, une nouvelle instance de la classe est créée. Seuls les constructeurs exposés par Q_INVOKABLE seront visibles par le moteur de script.

Voir également newQObject() et QObject Integration.

QJSValue QJSEngine::newQObject(QObject *object)

Crée un objet JavaScript qui englobe l'objet QObject object , en utilisant JavaScriptOwnership.

Les signaux et les emplacements, les propriétés et les enfants de object sont disponibles en tant que propriétés de l'objet créé QJSValue.

Si object est un pointeur nul, cette fonction renvoie une valeur nulle.

Si un prototype par défaut a été enregistré pour la classe de object(ou sa superclasse, récursivement), le prototype du nouvel objet script sera défini comme étant ce prototype par défaut.

Si l'objet object est supprimé en dehors du contrôle du moteur, toute tentative d'accès aux membres de l'objet QObject supprimé par l'intermédiaire de l'objet enveloppant JavaScript (que ce soit par le code du script ou par C++) entraînera une erreur script exception.

Voir également QJSValue::toQObject().

[since 6.2] QJSValue QJSEngine::newSymbol(const QString &name)

Crée un objet JavaScript de la classe Symbol, avec la valeur name.

Le prototype de l'objet créé sera l'objet prototype Symbol.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi newObject().

[static] QJSEngine::ObjectOwnership QJSEngine::objectOwnership(QObject *object)

Retourne la propriété de object.

Voir aussi setObjectOwnership() et QJSEngine::ObjectOwnership.

bool QJSEngine::registerModule(const QString &moduleName, const QJSValue &value)

Enregistre un QJSValue pour qu'il serve de module. Après l'appel de cette fonction, tous les modules qui importent moduleName importeront la valeur de value au lieu de charger moduleName depuis le système de fichiers.

Tout QJSValue valide peut être enregistré, mais les exportations nommées (c'est-à-dire import { name } from "info" ) sont traitées comme des membres d'un objet, de sorte que l'exportation par défaut doit être créée à l'aide de l'une des méthodes newXYZ de QJSEngine.

Comme cela permet d'importer des modules qui n'existent pas dans le système de fichiers, les applications de script peuvent l'utiliser pour fournir des modules intégrés, à l'instar de Node.js.

Retourne true en cas de succès, false dans le cas contraire.

Voir aussi importModule().

void QJSEngine::setInterrupted(bool interrupted)

Interrompt ou réactive l'exécution de JavaScript.

Si interrupted est true, tout JavaScript exécuté par ce moteur est immédiatement interrompu et renvoie un objet d'erreur jusqu'à ce que cette fonction soit appelée à nouveau avec une valeur de false pour interrupted.

Cette fonction est sans risque pour les threads. Vous pouvez l'appeler à partir d'un autre thread afin d'interrompre, par exemple, une boucle infinie en JavaScript.

Voir aussi isInterrupted().

[static] void QJSEngine::setObjectOwnership(QObject *object, QJSEngine::ObjectOwnership ownership)

Fixe la valeur de ownership pour object.

Un objet avec JavaScriptOwnership n'est pas ramassé tant qu'il a encore un parent, même s'il n'y a plus de références vers lui.

Voir aussi objectOwnership() et QJSEngine::ObjectOwnership.

[since Qt 5.12] void QJSEngine::throwError(const QString &message)

Lance une erreur d'exécution (exception) avec l'adresse message.

Cette méthode est la contrepartie C++ d'une expression throw() en JavaScript. Elle permet au code C++ de signaler les erreurs d'exécution à QJSEngine. Par conséquent, elle ne doit être appelée qu'à partir d'un code C++ qui a été invoqué par une fonction JavaScript via QJSEngine.

Lorsqu'il revient de C++, le moteur interrompt le flux normal de l'exécution et appelle le prochain gestionnaire d'exception préenregistré avec un objet d'erreur qui contient l'expression message. L'objet d'erreur pointera vers l'emplacement du contexte le plus élevé de la pile de l'appelant JavaScript ; plus précisément, il aura les propriétés lineNumber, fileName et stack. Ces propriétés sont décrites dans Script Exceptions.

Dans l'exemple suivant, une méthode C++ dans FileAccess.cpp provoque une erreur dans qmlFile.qml à l'endroit où readFileAsText() est appelé :

// qmlFile.qml
function someFunction() {
  ...
  var text = FileAccess.readFileAsText("/path/to/file.txt");
}

// FileAccess.cpp
// Assuming that FileAccess is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// readFileAsText()

QJSValue FileAccess::readFileAsText(const QString & filePath) {
  QFile file(filePath);

  if (!file.open(QIODevice::ReadOnly)) {
    jsEngine->throwError(file.errorString());
    return QString();
  }

  ...
  return content;
}

Il est également possible d'attraper l'erreur en JavaScript :

// qmlFile.qml
function someFunction() {
  ...
  var text;
  try {
    text = FileAccess.readFileAsText("/path/to/file.txt");
  } catch (error) {
    console.warn("In " + error.fileName + ":" + "error.lineNumber" +
                 ": " + error.message);
  }
}

Si vous avez besoin d'une erreur d'exécution plus spécifique pour décrire une exception, vous pouvez utiliser la surcharge throwError(QJSValue::ErrorType errorType, const QString &message).

Cette fonction a été introduite dans Qt 5.12.

Voir aussi Script Exceptions.

[since 6.1] void QJSEngine::throwError(const QJSValue &error)

Lance une exception ( error ) préconstruite au moment de l'exécution. Vous pouvez ainsi utiliser newErrorObject() pour créer l'erreur et la personnaliser si nécessaire.

Cette fonction a été introduite dans Qt 6.1.

Voir aussi Script Exceptions et newErrorObject().

[since Qt 5.12] void QJSEngine::throwError(QJSValue::ErrorType errorType, const QString &message = QString())

Lance une erreur d'exécution (exception) avec les données errorType et message.

// Assuming that DataEntry is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// setAge().

void DataEntry::setAge(int age) {
  if (age < 0 || age > 200) {
    jsEngine->throwError(QJSValue::RangeError,
                         "Age must be between 0 and 200");
  }
  ...
}

Cette fonction a été introduite dans Qt 5.12.

Voir aussi Script Exceptions et newErrorObject().

template <typename T> QJSManagedValue QJSEngine::toManagedValue(const T &value)

Crée un QJSManagedValue avec le value donné.

Voir aussi fromManagedValue() et coerceValue().

template <typename T> QJSPrimitiveValue QJSEngine::toPrimitiveValue(const T &value)

Crée un QJSPrimitiveValue avec le type donné value.

Comme QJSPrimitiveValue ne peut contenir que int, bool, double, QString, et les équivalents de JavaScript null et undefined, la valeur sera contrainte agressivement si vous passez un autre type.

Voir aussi fromPrimitiveValue() et coerceValue().

template <typename T> QJSValue QJSEngine::toScriptValue(const T &value)

Crée un QJSValue avec le value donné.

Voir aussi fromScriptValue() et coerceValue().