QScriptContext Class

Detailed Description

A QScriptContext provides access to the `this' object and arguments passed to a script function. You typically want to access this information when you're writing a native (C++) function (see QScriptEngine::newFunction()) that will be called from script code. For example, when the script code

 foo(20.5, "hello", new Object())

is evaluated, a QScriptContext will be created, and the context will carry the arguments as QScriptValues; in this particular case, the arguments will be one QScriptValue containing the number 20.5, a second QScriptValue containing the string "hello", and a third QScriptValue containing a Qt Script object.

Use argumentCount() to get the number of arguments passed to the function, and argument() to get an argument at a certain index. The argumentsObject() function returns a Qt Script array object containing all the arguments; you can use the QScriptValueIterator to iterate over its elements, or pass the array on as arguments to another script function using QScriptValue::call().

Use thisObject() to get the `this' object associated with the function call, and setThisObject() to set the `this' object. If you are implementing a native "instance method", you typically fetch the thisObject() and access one or more of its properties:

 QScriptValue Person_prototype_fullName(QScriptContext *context, QScriptEngine *engine)
 {
     QScriptValue self = context->thisObject();
     QString result;
     result += self.property("firstName").toString();
     result += QLatin1String(" ");
     result += self.property("lastName").toString();
     return result;
 }

Use isCalledAsConstructor() to determine if the function was called as a constructor (e.g. "new foo()" (as constructor) or just "foo()"). When a function is called as a constructor, the thisObject() contains the newly constructed object that the function is expected to initialize.

Use throwValue() or throwError() to throw an exception.

Use callee() to obtain the QScriptValue that represents the function being called. This can for example be used to call the function recursively.

Use parentContext() to get a pointer to the context that precedes this context in the activation stack. This is mostly useful for debugging purposes (e.g. when constructing some form of backtrace).

The activationObject() function returns the object that is used to hold the local variables associated with this function call. You can replace the activation object by calling setActivationObject(). A typical usage of these functions is when you want script code to be evaluated in the context of the parent context, e.g. to implement an include() function:

 QScriptValue myInclude(QScriptContext *ctx, QScriptEngine *eng)
 {
     QString fileName = ctx->argument(0).toString();
     QString contents = readTheFile(fileName);
     ctx->setActivationObject(ctx->parentContext()->activationObject());
     ctx->setThisObject(ctx->parentContext()->thisObject());
     return eng->evaluate(contents, fileName);
 }

Use backtrace() to get a human-readable backtrace associated with this context. This can be useful for debugging purposes when implementing native functions. The toString() function provides a string representation of the context. (QScriptContextInfo provides more detailed debugging-related information about the QScriptContext.)

Use engine() to obtain a pointer to the QScriptEngine that this context resides in.