Struct JSContext

#[repr(C)]
pub struct JSContext { /* private fields */ }

Available on crate features JSContext and objc2 only.

A JSContext is a JavaScript execution environment. All JavaScript execution takes place within a context, and all JavaScript values are tied to a context.

See also Apple’s documentation

Implementations

impl JSContext

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

Create a JSContext.

Returns: The new context.

pub unsafe fn initWithVirtualMachine( this: Allocated<Self>, virtual_machine: Option<&JSVirtualMachine>, ) -> Option<Retained<Self>>

Available on crate feature JSVirtualMachine only.

Create a JSContext in the specified virtual machine.

Parameter virtualMachine: The JSVirtualMachine in which the context will be created.

Returns: The new context.

pub unsafe fn evaluateScript( &self, script: Option<&NSString>, ) -> Option<Retained<JSValue>>

Available on crate features JSValue and objc2-foundation only.

Evaluate a string of JavaScript code.

Parameter script: A string containing the JavaScript code to evaluate.

Returns: The last value generated by the script.

pub unsafe fn evaluateScript_withSourceURL( &self, script: Option<&NSString>, source_url: Option<&NSURL>, ) -> Option<Retained<JSValue>>

Available on crate features JSValue and objc2-foundation only.

Evaluate a string of JavaScript code, with a URL for the script’s source file.

Parameter script: A string containing the JavaScript code to evaluate.

Parameter sourceURL: A URL for the script’s source file. Used by debuggers and when reporting exceptions. This parameter is informative only: it does not change the behavior of the script.

Returns: The last value generated by the script.

pub unsafe fn currentContext() -> Option<Retained<JSContext>>

Get the JSContext that is currently executing.

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback’s context. Outside of a callback from JavaScript this method will return nil.

Returns: The currently executing JSContext or nil if there isn’t one.

pub unsafe fn currentCallee() -> Option<Retained<JSValue>>

Available on crate feature JSValue only.

Get the JavaScript function that is currently executing.

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback’s context. Outside of a callback from JavaScript this method will return nil.

Returns: The currently executing JavaScript function or nil if there isn’t one.

pub unsafe fn currentThis() -> Option<Retained<JSValue>>

Available on crate feature JSValue only.

Get the this value of the currently executing method.

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback’s this value. Outside of a callback from JavaScript this method will return nil.

Returns: The current this value or nil if there isn’t one.

pub unsafe fn currentArguments() -> Option<Retained<NSArray>>

Available on crate feature objc2-foundation only.

Get the arguments to the current callback.

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback’s arguments, objects in the returned array are instances of JSValue. Outside of a callback from JavaScript this method will return nil.

Returns: An NSArray of the arguments nil if there is no current callback.

pub unsafe fn globalObject(&self) -> Option<Retained<JSValue>>

Available on crate feature JSValue only.

Get the global object of the context.

This method retrieves the global object of the JavaScript execution context. Instances of JSContext originating from WebKit will return a reference to the WindowProxy object.

Returns: The global object.

pub unsafe fn exception(&self) -> Option<Retained<JSValue>>

Available on crate feature JSValue only.

The exception property may be used to throw an exception to JavaScript.

Before a callback is made from JavaScript to an Objective-C block or method, the prior value of the exception property will be preserved and the property will be set to nil. After the callback has completed the new value of the exception property will be read, and prior value restored. If the new value of exception is not nil, the callback will result in that value being thrown.

This property may also be used to check for uncaught exceptions arising from API function calls (since the default behaviour of exceptionHandler is to assign an uncaught exception to this property).

pub unsafe fn setException(&self, exception: Option<&JSValue>)

Available on crate feature JSValue only.

Setter for exception.

pub unsafe fn exceptionHandler( &self, ) -> NonNull<DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>

Available on crate features JSValue and block2 only.

If a call to an API function results in an uncaught JavaScript exception, the exceptionHandler block will be invoked. The default implementation for the exception handler will store the exception to the exception property on context. As a consequence the default behaviour is for uncaught exceptions occurring within a callback from JavaScript to be rethrown upon return. Setting this value to nil will cause all exceptions occurring within a callback from JavaScript to be silently caught.

pub unsafe fn setExceptionHandler( &self, exception_handler: Option<&DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>, )

Available on crate features JSValue and block2 only.

Setter for exceptionHandler.

pub unsafe fn virtualMachine(&self) -> Option<Retained<JSVirtualMachine>>

Available on crate feature JSVirtualMachine only.

All instances of JSContext are associated with a JSVirtualMachine.

pub unsafe fn name(&self) -> Retained<NSString>

Available on crate feature objc2-foundation only.

Name of the JSContext. Exposed when inspecting the context.

pub unsafe fn setName(&self, name: Option<&NSString>)

Available on crate feature objc2-foundation only.

Setter for name.

pub unsafe fn isInspectable(&self) -> bool

Controls whether this

 JSContext

is inspectable in Web Inspector. The default value is NO.

pub unsafe fn setInspectable(&self, inspectable: bool)

Setter for isInspectable.

impl JSContext

Methods declared on superclass NSObject.

pub unsafe fn new() -> Retained<Self>

impl JSContext

SubscriptSupport. Instances of JSContext implement the following methods in order to enable support for subscript access by key and index, for example:

    JSContext *context;
    JSValue *v = context[@"X"]; // Get value for "X" from the global object.
    context[@"Y"] = v;          // Assign 'v' to "Y" on the global object.

An object key passed as a subscript will be converted to a JavaScript value, and then the value converted to a string used to resolve a property of the global object.

pub unsafe fn objectForKeyedSubscript( &self, key: Option<&AnyObject>, ) -> Option<Retained<JSValue>>

Available on crate feature JSValue only.

Get a particular property on the global object.

Returns: The JSValue for the global object’s property.

pub unsafe fn setObject_forKeyedSubscript( &self, object: Option<&AnyObject>, key: Option<&NSObject>, )

Available on crate feature objc2-foundation only.

Set a particular property on the global object.

impl JSContext

JSContextRefSupport. These functions are for bridging between the C API and the Objective-C API.

pub unsafe fn contextWithJSGlobalContextRef( js_global_context_ref: JSGlobalContextRef, ) -> Option<Retained<JSContext>>

Available on crate feature JSBase only.

Create a JSContext, wrapping its C API counterpart.

Returns: The JSContext equivalent of the provided JSGlobalContextRef.

pub unsafe fn JSGlobalContextRef(&self) -> JSGlobalContextRef

Available on crate feature JSBase only.

Get the C API counterpart wrapped by a JSContext.

Returns: The C API equivalent of this JSContext.

impl JSContext

pub unsafe fn group_create() -> JSContextGroupRef

Available on crate features JSContextRef and JSBase only.

Creates a JavaScript context group.

A JSContextGroup associates JavaScript contexts with one another. Contexts in the same group may share and exchange JavaScript objects. Sharing and/or exchanging JavaScript objects between contexts in different groups will produce undefined behavior. When objects from the same context group are used in multiple threads, explicit synchronization is required.

A JSContextGroup may need to run deferred tasks on a run loop, such as garbage collection or resolving WebAssembly compilations. By default, calling JSContextGroupCreate will use the run loop of the thread it was called on. Currently, there is no API to change a JSContextGroup’s run loop once it has been created.

Returns: The created JSContextGroup.

pub unsafe fn group_retain(group: JSContextGroupRef) -> JSContextGroupRef

Available on crate features JSContextRef and JSBase only.

Retains a JavaScript context group.

Parameter group: The JSContextGroup to retain.

Returns: A JSContextGroup that is the same as group.

pub unsafe fn group_release(group: JSContextGroupRef)

Available on crate features JSContextRef and JSBase only.

Releases a JavaScript context group.

Parameter group: The JSContextGroup to release.

impl JSContext

pub unsafe fn global_object(ctx: JSContextRef) -> JSObjectRef

Available on crate features JSContextRef and JSBase only.

Gets the global object of a JavaScript execution context.

Parameter ctx: The JSContext whose global object you want to get.

Returns: ctx’s global object.

pub unsafe fn group(ctx: JSContextRef) -> JSContextGroupRef

Available on crate features JSContextRef and JSBase only.

Gets the context group to which a JavaScript execution context belongs.

Parameter ctx: The JSContext whose group you want to get.

Returns: ctx’s group.

pub unsafe fn global_context(ctx: JSContextRef) -> JSGlobalContextRef

Available on crate features JSContextRef and JSBase only.

Gets the global context of a JavaScript execution context.

Parameter ctx: The JSContext whose global context you want to get.

Returns: ctx’s global context.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for JSContext

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<JSContext> for JSContext

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for JSContext

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for JSContext

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for JSContext

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for JSContext

const NAME: &'static str = "JSContext"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<JSContext as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for JSContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for JSContext

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for JSContext

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for JSContext

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for JSContext

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for JSContext

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for JSContext

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for JSContext

impl Eq for JSContext