Loading...
Searching...
No Matches
juce::JSCursor Class Reference

## Detailed Description

A high-level wrapper around an owning root JSObject and a hierarchical path relative to it.

It can be used to query and manipulate the location relative to the root JSObject in the Javascript Object graph. A cursor only maintains ownership of the root Object. So as long as a cursor points at the root it will always remain in a valid state, and isValid will return true.

Using getChild you can add elements to the cursor's relative path. You need to ensure that the cursor is in a valid state when calling get or set in such cases. You can use the isValid function to determine if the cursor currently points to a reachable location.

The documentation for this class was generated from the following file:

- juce_javascript/javascript/juce_JSCursor.h

## Public Member Functions

| JSCursor (JSObject root)
| Creates a JSCursor that points to the provided root object and also participates in its ownership.
JSObject | getOrCreateObject () const
| Returns an owning reference to the Javascript Object at the cursor's location.
var | get () const
| Returns the value corresponding to the Object that the cursor points to.
void | set (const var &value) const
| Sets the Object under the cursor's location to the specified value.
var | invoke (Span< const var > args, Result *result=nullptr) const
| Invokes this node as though it were a method.
var | operator() (Span< const var > args, Result *result=nullptr) const
| Equivalent to invoke().
JSCursor | getChild (const Identifier &name) const
| Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.
JSCursor | operator[] (const Identifier &name) const
| Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.
JSCursor | getChild (int64 index) const
| Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.
JSCursor | operator[] (int64 index) const
| Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.
bool | isValid () const
| Returns true if the location of the cursor is reachable from the cursor's JSObject root.
bool | isArray () const
| Returns true if there is an Array under the cursor's location.

## Constructors and Destructors

## JSCursor()

juce::JSCursor::JSCursor | ( | JSObject | root | ) |

explicit

Creates a JSCursor that points to the provided root object and also participates in its ownership.

This guarantees that this root object will remain valid for the lifetime of this cursor.

Child JSCursors created by getChild() will contain this same root object and each will further ensure that this root remains valid through reference counting.

While the validity of the root is ensured through shared ownership, the JSCursor itself is not guaranteed to be valid, unless its also pointing directly at the root.

See also
  isValid

Referenced by getChild(), getChild(), operator[](), and operator[]().

## Member Functions

## getOrCreateObject()

JSObject juce::JSCursor::getOrCreateObject | ( |  | ) | const

Returns an owning reference to the Javascript Object at the cursor's location.

If there is no Object at the location but the cursor is valid, a new Object will be created.

You must only call this function on a valid JSCursor.

By creating an owning reference, you can create a new JSCursor object that owns the underlying object and is guaranteed to remain in a valid state e.g.

JSCursor rootCursor { engine.getRootObject() };
auto nonOwningCursor = rootCursor["path"]["to"]["object"];
jassert (nonOwningCursor.isValid());
JSCursor owningCursor { nonOwningCursor.getOrCreateObject(); };
engine.execute (arbitraryScript);
// owningCursor is guaranteed to remain valid even after subsequent script evaluations
jassert (owningCursor.isValid());
juce::JSCursor
A high-level wrapper around an owning root JSObject and a hierarchical path relative to it.
Definition juce_JSCursor.h:52
juce::JSCursor::isValid
bool isValid() const
Returns true if the location of the cursor is reachable from the cursor's JSObject root.
juce::JSCursor::JSCursor
JSCursor(JSObject root)
Creates a JSCursor that points to the provided root object and also participates in its ownership.
jassert
#define jassert(expression)
Platform-independent assertion macro.
Definition juce_PlatformDefs.h:178

See also
  isValid

## get()

var juce::JSCursor::get | ( |  | ) | const

Returns the value corresponding to the Object that the cursor points to.

If there is no Object at the cursor's location var::undefined() is returned.

This function is safe to call for invalid cursors.

See also
  isValid

## set()

void juce::JSCursor::set | ( | const var & | value | ) | const

Sets the Object under the cursor's location to the specified value.

You must only call this function for valid cursors.

See also
  isValid

## invoke()

var juce::JSCursor::invoke | ( | Span< const var > | args,
|  | Result * | result = nullptr ) const

Invokes this node as though it were a method.

If the optional Result pointer is provided it will contain Result::ok() in case of success, or an error message in case an exception was thrown during evaluation.

You must only call this function for valid cursors.

Referenced by operator()().

## operator()()

var juce::JSCursor::operator() | ( | Span< const var > | args,
|  | Result * | result = nullptr ) const

inline

Equivalent to invoke().

References invoke().

## getChild() [1/2]

JSCursor juce::JSCursor::getChild | ( | const Identifier & | name | ) | const

Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions.

References JSCursor(), and name.

## operator[]() [1/2]

JSCursor juce::JSCursor::operator[] | ( | const Identifier & | name | ) | const

Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions. Shorthand for getChild.

References JSCursor(), and name.

## getChild() [2/2]

JSCursor juce::JSCursor::getChild | ( | int64 | index | ) | const

Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.

This overload will create a path that indexes into an Array.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions.

References JSCursor().

## operator[]() [2/2]

JSCursor juce::JSCursor::operator[] | ( | int64 | index | ) | const

Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.

This overload will create a path that indexes into an Array.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions. Shorthand for getChild.

References JSCursor().

## isValid()

bool juce::JSCursor::isValid | ( |  | ) | const

Returns true if the location of the cursor is reachable from the cursor's JSObject root.

This means it is safe to call set on this JSCursor and the location will then point to an Object corresponding to the supplied value.

It isn't guaranteed that there is already an Object at this location, in which case calling get will return var::undefined().

## isArray()

bool juce::JSCursor::isArray | ( |  | ) | const

Returns true if there is an Array under the cursor's location.

It is safe to call this function on an invalid cursor.

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited