JavaScript execution environment for a page.
Every call into a page's JavaScript environment goes through its Context. It represents the execution state of a loaded document, providing access to the global object where page functions and variables live.
Construct a Context from a View inside LoadListener::OnDOMReady() to call functions and read global variables on the page:
void MyApp::OnDOMReady(
View* caller, uint64_t frame_id,
bool is_main_frame,
if (!is_main_frame)
return;
ctx["ShowMessage"]("Howdy!");
double score =
js::Or(ctx[
"score"], 0.0);
double doubled =
js::Or(ctx.Evaluate<
double>(
"score * 2"), 0.0);
}
Unicode string container with conversions for UTF-8, UTF-16, and UTF-32.
Definition String.h:31
Web-page container rendered to an offscreen surface.
Definition View.h:483
JavaScript execution environment for a page.
Definition Context.h:151
T Or(const Value &value, T fallback)
Convert a value to a C++ type with a fallback (the free-function form of Value::Or()).
Definition Value.h:1220
Getting a Context
Constructing a Context with a View wraps the main frame's JavaScript environment. To access the Context of a subframe or a specific document, pass that document to dom::GetJSContext().
You'll typically construct a Context inside a LoadListener callback:
Each page gets its own Context. When a View navigates to a new page, the old Context's page is gone, along with every Value created from it (see js::Value for what that means), so you'll need to obtain a new Context for the new page. Operations on a Context whose page is gone fail safely instead of crashing.
Creating Values
Call Make() to convert a native C++ value into a JavaScript Value. The method converts any type that js::TypeTraits supports, including numbers, strings, standard containers, reflected structs, and enums.
Convert a reflected struct to a JavaScript object and pass it to a page function:
struct HudSettings {
std::string theme;
double volume;
};
js::Value settings = ctx.Make(HudSettings {
"dark", 0.8 });
ctx["applySettings"](settings);
A handle to a live JavaScript value.
Definition Value.h:210
- Note
- Context operations must run on the Renderer's thread. To dispatch work from another thread, call PostTask() to schedule a callback that runs during a later Renderer::Update().
- Note
- js::Context and dom::data::Context are unrelated types (dom::data::Context manages declarative data bindings).
- See also
- js::Value, js::CallInfo::context(), dom::GetJSContext(), LoadListener::OnDOMReady()
|
| | Context ()=default |
| | Create an empty Context.
|
| | Context (View *view) |
| | Get the context of a View's main frame.
|
| | Context (const Value &value) |
| | Get the context a value belongs to.
|
| | Context (const Context &other) |
| | Copy constructor (refers to the same context).
|
| | Context (Context &&other) noexcept |
| | Move constructor (other becomes empty).
|
| Context & | operator= (Context other) noexcept |
| | Assignment (copies or moves other into this Context).
|
| | ~Context () |
| | Destructor (releases this handle).
|
| | operator bool () const |
| | Whether or not this Context is valid (it isn't empty and its page is still alive).
|
| bool | IsEmpty () const |
| | Whether or not this Context holds nothing.
|
| bool | IsAlive () const |
| | Whether or not this Context's page is still alive (the same test as operator bool).
|
| Result< Value > | Evaluate (std::string_view script, const char *source_url=nullptr) const |
| | Run a script and get its completion value.
|
template<typename T>
requires Marshalable<T> |
| Result< T > | Evaluate (std::string_view script, const char *source_url=nullptr) const |
| | Run a script and convert its completion value to a C++ type (see Value::To()).
|
| Value | GlobalObject () const |
| | Get the global object.
|
| Value::Ref | operator[] (const char *name) const |
| | Access a property of the global object (ctx["fn"](args) is the same as ctx.GlobalObject()["fn"](args)):
|
| template<typename T> |
| Value | Make (T &&value) const |
| | Convert a C++ value to a JavaScript value through js::TypeTraits.
|
| Value | MakeObject () const |
| | Create a new empty JavaScript object.
|
| Value | MakeArray (const Value *elements, size_t count) const |
| | Create a new JavaScript Array.
|
| Value | MakeArray (std::initializer_list< Value > elements) const |
| | Create a new JavaScript Array from a brace list (eg, ctx.MakeArray({ a, b })).
|
| Value | MakeArray (std::span< const Value > elements) const |
| | Create a new JavaScript Array from a range (eg, a std::vector<js::Value>).
|
| Result< Value > | MakeFromJSON (std::string_view json) const |
| | Create a value from JSON text (the reverse of Value::ToJSON()):
|
| template<typename F> |
| void | PostTask (F &&task) const |
| | Run a function with this context during a later Renderer::Update().
|
| PendingPromise | MakePromise () const |
| | Create a pending Promise and the Resolver that settles it, to hand a Promise to the page outside a bound function:
|
| ArrayBuffer | MakeArrayBuffer (const RefPtr< ultralight::Buffer > &buffer) const |
| | Create an ArrayBuffer that shares a Buffer's bytes with JavaScript without copying.
|
| ArrayBuffer | MakeArrayBuffer (const void *bytes, size_t length) const |
| | Create an ArrayBuffer holding a copy of the given bytes.
|
| template<typename T> |
| TypedArray< T > | MakeTypedArray (size_t length) const |
| | Create a typed array of zero-filled elements of type T (eg, MakeTypedArray<float>(4) creates a Float32Array; see js::TypedArray for the element types).
|
| template<typename T> |
| TypedArray< T > | MakeTypedArray (const RefPtr< ultralight::Buffer > &buffer) const |
| | Create a typed array of elements of type T that shares a Buffer's bytes with JavaScript without copying.
|
| template<typename Fn> |
| Value | MakeFunction (const char *name, Fn &&fn) const |
| | Create a JavaScript function backed by a C++ callable, to hand to the page (eg, as a callback).
|
| HandleStats | GetHandleStats () const |
| | Count the live handles on this context, for finding leaks.
|
| ULJSContext | raw () const |
| | Get the C API handle without transferring ownership.
|
| ULJSContext | LeakRef () |
| | Give up ownership of the C API handle and return it.
|