class QJSManagedValue

QJSManagedValue represents a value on the JavaScript heap belonging to a QJSEngine . More…

Synopsis

Methods

• def __init__()

• def call()

• def callAsConstructor()

• def callWithInstance()

• def deleteProperty()

• def engine()

• def equals()

• def hasOwnProperty()

• def hasProperty()

• def isArray()

• def isBoolean()

• def isDate()

• def isError()

• def isFunction()

• def isInteger()

• def isJsMetaType()

• def isNull()

• def isNumber()

• def isObject()

• def isQMetaObject()

• def isQObject()

• def isRegularExpression()

• def isString()

• def isSymbol()

• def isUndefined()

• def isUrl()

• def isVariant()

• def jsMetaInstantiate()

• def jsMetaMembers()

• def jsMetaType()

• def property()

• def prototype()

• def setProperty()

• def setPrototype()

• def strictlyEquals()

• def toBoolean()

• def toDateTime()

• def toInteger()

• def toJSValue()

• def toNumber()

• def toPrimitive()

• def toQMetaObject()

• def toQObject()

• def toRegularExpression()

• def toString()

• def toUrl()

• def toVariant()

• def type()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

The QJSManagedValue class allows interaction with JavaScript values in most ways you can interact with them from JavaScript itself. You can get and set properties and prototypes, and you can access arrays. Additionally, you can transform the value into the Qt counterparts of JavaScript objects. For example, a Url object may be transformed into a QUrl.

A QJSManagedValue is always bound to a particular QJSEngine . You cannot use it independently. This means that you cannot have a QJSManagedValue from one engine be a property or a proptotype of a QJSManagedValue from a different engine.

In contrast to QJSValue , almost all values held by QJSManagedValue live on the JavaScript heap. There is no inline or unmanaged storage. Therefore, you can get the prototype of a primitive value, and you can get the length property of a string.

Only default-constructed or moved-from QJSManagedValues do not hold a value on the JavaScript heap. They represent undefined, which doesn’t have any properties or prototypes.

Also in contrast to QJSValue , QJSManagedValue does not catch any JavaScript exceptions. If an operation on a QJSManagedValue causes an error, it will generally return an undefined value and hasError() will return true afterwards. You can then catch the exception using catchError() , or pass it up the stack, at your own discretion.

Note

As the reference to the value on the JavaScript heap has to be freed on destruction, you cannot move a QJSManagedValue to a different thread. The destruction would take place in the new thread, which would create a race condition with the garbage collector on the original thread. This also means that you cannot hold a QJSManagedValue beyond the lifespan of its engine.

The recommended way of working with a QJSManagedValue is creating it on the stack, possibly by moving a QJSValue and adding an engine, then performing the necessary operations on it, and finally moving it back into a QJSValue for storage. Moving between QJSManagedValue and QJSValue is fast.

class Type

This enum represents the JavaScript native types, as specified by ECMA-262 .

Constant	Description
QJSManagedValue.Undefined	The undefined type
QJSManagedValue.Boolean	The boolean type
QJSManagedValue.Number	The number type
QJSManagedValue.String	The string type
QJSManagedValue.Object	The object type
QJSManagedValue.Symbol	The symbol type
QJSManagedValue.Function	The function type

Note that the null value is not a type of itself but rather a special kind of object. You can query a QJSManagedValue for this condition using the isNull() method. Furthermore, JavaScript has no integer type, but it knows a special treatment of numbers in preparation for integer only operations. You can query a QJSManagedValue to find out whether it holds the result of such a treatment by using the isInteger() method.

__init__()

Creates a QJSManagedValue that represents the JavaScript undefined value. This is the only value not stored on the JavaScript heap. Calling engine() on a default-constructed QJSManagedValue will return nullptr.

__init__(value, engine)

Parameters:

• value – QJSValue

• engine – QJSEngine

Creates a QJSManagedValue from value, using the heap of engine. If value is itself managed and the engine it belongs to is not engine, the result is an undefined value, and a warning is generated.

__init__(value, engine)

Parameters:

• value – QJSPrimitiveValue

• engine – QJSEngine

Creates a QJSManagedValue from value using the heap of engine.

__init__(string, engine)

Parameters:

• string – str

• engine – QJSEngine

Creates a QJSManagedValue from string using the heap of engine.

__init__(variant, engine)

Parameters:

• variant – object

• engine – QJSEngine

Creates a QJSManagedValue from variant using the heap of engine.

call([arguments={}])

Parameters:

arguments – .list of QJSValue

Return type:

QJSValue

If this QJSManagedValue represents a JavaScript FunctionObject, calls it with the given arguments, and returns the result. Otherwise returns a JavaScript undefined value.

The arguments have to be either primitive values or belong to the same QJSEngine as this QJSManagedValue . Otherwise the call is not carried out and a JavaScript undefined value is returned.

callAsConstructor([arguments={}])

Parameters:

arguments – .list of QJSValue

Return type:

QJSValue

If this QJSManagedValue represents a JavaScript FunctionObject, calls it as constructor with the given arguments, and returns the result. Otherwise returns a JavaScript undefined value.

The arguments have to be either primitive values or belong to the same QJSEngine as this QJSManagedValue . Otherwise the call is not carried out and a JavaScript undefined value is returned.

callWithInstance(instance[, arguments={}])

Parameters:

• instance – QJSValue

• arguments – .list of QJSValue

Return type:

QJSValue

If this QJSManagedValue represents a JavaScript FunctionObject, calls it on instance with the given arguments, and returns the result. Otherwise returns a JavaScript undefined value.

The arguments and the instance have to be either primitive values or belong to the same QJSEngine as this QJSManagedValue . Otherwise the call is not carried out and a JavaScript undefined value is returned.

deleteProperty(name)

Parameters:

name – str

Return type:

bool

Deletes the property name from this QJSManagedValue . Returns true if the deletion succeeded, or false otherwise.

deleteProperty(arrayIndex)

Parameters:

arrayIndex – int

Return type:

bool

Deletes the value stored at arrayIndex from this QJSManagedValue . Returns true if the deletion succeeded, or false otherwise.

engine()

Return type:

QJSEngine

Returns the QJSEngine this QJSManagedValue belongs to. Mind that the engine is always valid, unless the QJSManagedValue is default-constructed or moved from. In the latter case a nullptr is returned.

equals(other)

Parameters:

other – QJSManagedValue

Return type:

bool

Invokes the JavaScript ‘==’ operator on this QJSManagedValue and other, and returns the result.

See also

strictlyEquals

hasOwnProperty(name)

Parameters:

name – str

Return type:

bool

Returns true if this QJSManagedValue has a property name, otherwise returns false. The properties of the prototype chain are not considered.

hasOwnProperty(arrayIndex)

Parameters:

arrayIndex – int

Return type:

bool

Returns true if this QJSManagedValue has an array index arrayIndex, otherwise returns false. The properties of the prototype chain are not considered.

hasProperty(name)

Parameters:

name – str

Return type:

bool

Returns true if this QJSManagedValue has a property name, otherwise returns false. The properties of the prototype chain are considered.

hasProperty(arrayIndex)

Parameters:

arrayIndex – int

Return type:

bool

Returns true if this QJSManagedValue has an array index arrayIndex, otherwise returns false. The properties of the prototype chain are considered.

isArray()

Return type:

bool

Returns true if this value represents a JavaScript Array object, or false otherwise.

isBoolean()

Return type:

bool

Returns true if the type of this QJSManagedValue is boolean, or false otherwise.

isDate()

Return type:

bool

Returns true if this value represents a JavaScript Date object, or false otherwise.

isError()

Return type:

bool

Returns true if this value represents a JavaScript Error object, or false otherwise.

isFunction()

Return type:

bool

Returns true if the type of this QJSManagedValue is function, false otherwise.

isInteger()

Return type:

bool

Returns true if this QJSManagedValue holds an integer value, or false otherwise. The storage format of a number does not affect the result of any operations performed on it, but if an integer is stored, many operations are faster.

isJsMetaType()

Return type:

bool

isNull()

Return type:

bool

Returns true if this QJSManagedValue holds the JavaScript null value, or false otherwise.

isNumber()

Return type:

bool

Returns true if the type of this QJSManagedValue is number, or false otherwise.

isObject()

Return type:

bool

Returns true if the type of this QJSManagedValue is object, or false otherwise.

isQMetaObject()

Return type:

bool

Returns true if this value represents a QMetaObject pointer managed on the JavaScript heap, or false otherwise.

isQObject()

Return type:

bool

Returns true if this value represents a QObject pointer managed on the JavaScript heap, or false otherwise.

isRegularExpression()

Return type:

bool

Returns true if this value represents a JavaScript regular expression object, or false otherwise.

isString()

Return type:

bool

Returns true if the type of this QJSManagedValue is string, or false otherwise.

isSymbol()

Return type:

bool

Returns true if the type of this QJSManagedValue is symbol, or false otherwise.

isUndefined()

Return type:

bool

Returns true if the type of this QJSManagedValue is undefined, or false otherwise.

isUrl()

Return type:

bool

Returns true if this value represents a JavaScript Url object, or false otherwise.

isVariant()

Return type:

bool

Returns true if this value represents a QVariant managed on the JavaScript heap, or false otherwise.

jsMetaInstantiate([values={}])

Parameters:

values – .list of QJSValue

Return type:

QJSManagedValue

jsMetaMembers()

Return type:

list of strings

jsMetaType()

Return type:

QJSManagedValue

property(name)

Parameters:

name – str

Return type:

QJSValue

Returns the property name of this QJSManagedValue . The prototype chain is searched if the property is not found on the actual object.

See also

setProperty()

property(arrayIndex)

Parameters:

arrayIndex – int

Return type:

QJSValue

Returns the property stored at arrayIndex of this QJSManagedValue . The prototype chain is searched if the property is not found on the actual object.

prototype()

Return type:

QJSManagedValue

Returns the prototype for this QJSManagedValue . This works on any value. You can, for example retrieve the JavaScript boolean prototype from a boolean value.

See also

setPrototype()

setProperty(name, value)

Parameters:

• name – str

• value – QJSValue

Sets the property name to value on this QJSManagedValue . This can only be done on JavaScript values of type object. Furhermore, value has to be either a primitive or belong to the same engine as this value.

See also

property()

setProperty(arrayIndex, value)

Parameters:

• arrayIndex – int

• value – QJSValue

Stores the value at arrayIndex in this QJSManagedValue . This can only be done on JavaScript values of type object, and it’s not recommended if the value is not an array. Furhermore, value has to be either a primitive or belong to the same engine as this value.

setPrototype(prototype)

Parameters:

prototype – QJSManagedValue

Sets the prototype of this QJSManagedValue to prototype. A precondition is that prototype belongs to the same QJSEngine as this QJSManagedValue and is an object (including null). Furthermore, this QJSManagedValue has to be an object (excluding null), too, and you cannot create prototype cycles.

See also

prototype()

strictlyEquals(other)

Parameters:

other – QJSManagedValue

Return type:

bool

Invokes the JavaScript ‘===’ operator on this QJSManagedValue and other, and returns the result.

See also

equals

toBoolean()

Return type:

bool

Converts the manged value to a boolean. If the managed value holds a boolean, that one is returned. Otherwise a boolean coercion by JavaScript rules is performed.

toDateTime()

Return type:

QDateTime

If this QJSManagedValue holds a JavaScript Date object, returns an equivalent QDateTime. Otherwise returns an invalid one.

toInteger()

Return type:

int

Converts the manged value to an integer. This first converts the value to a number by the rules of toNumber() , and then clamps it into the integer range by the rules given for coercing the arguments to JavaScript bit shift operators into 32bit integers.

Internally, the value may already be stored as an integer, in which case a fast path is taken.

Note

Conversion of a managed value to a number can throw an exception. In particular, symbols cannot be coerced into numbers, or a custom valueOf() method may throw. In this case the result is 0 and the engine carries an error after the conversion.

Note

The JavaScript rules for coercing numbers into 32bit integers are unintuitive.

toJSValue()

Return type:

QJSValue

Copies this QJSManagedValue into a new QJSValue . This is less efficient than move-constructing a QJSValue from a QJSManagedValue , but retains the QJSManagedValue .

toNumber()

Return type:

float

Converts the manged value to a number. If the managed value holds a number, that one is returned. Otherwise a number coercion by JavaScript rules is performed.

Note

Conversion of a managed value to a number can throw an exception. In particular, symbols cannot be coerced into numbers, or a custom valueOf() method may throw. In this case the result is 0 and the engine carries an error after the conversion.

toPrimitive()

Return type:

QJSPrimitiveValue

Converts the manged value to a QJSPrimitiveValue . If the managed value holds a type supported by QJSPrimitiveValue , the value is copied. Otherwise the value is converted to a string, and the string is stored in QJSPrimitiveValue .

Note

Conversion of a managed value to a string can throw an exception. In particular, symbols cannot be coerced into strings, or a custom toString() method may throw. In this case the result is the undefined value and the engine carries an error after the conversion.

toQMetaObject()

Return type:

QMetaObject

If this QJSManagedValue holds a QMetaObject pointer, returns it. Otherwise returns nullptr.

toQObject()

Return type:

QObject

If this QJSManagedValue holds a QObject pointer, returns it. Otherwise returns nullptr.

toRegularExpression()

Return type:

QRegularExpression

If this QJSManagedValue holds a JavaScript regular expression object, returns an equivalent QRegularExpression. Otherwise returns an invalid one.

toString()

Return type:

str

Converts the manged value to a string. If the managed value holds a string, that one is returned. Otherwise a string coercion by JavaScript rules is performed.

Note

Conversion of a managed value to a string can throw an exception. In particular, symbols cannot be coerced into strings, or a custom toString() method may throw. In this case the result is an empty string and the engine carries an error after the conversion.

toUrl()

Return type:

QUrl

If this QJSManagedValue holds a JavaScript Url object, returns an equivalent QUrl. Otherwise returns an invalid one.

toVariant()

Return type:

object

Copies this QJSManagedValue into a new QVariant. This also creates a useful QVariant if isVariant() returns false. QVariant can hold all types supported by QJSManagedValue .

type()

Return type:

Type

Returns the JavaScript type of this QJSManagedValue .