new SimIFrameClient(frame)
This SimIFrameClient communicates to one and only one iframe. Dispose it when you are done with it. There is not
any support for having two SimIFrameClients connect to the same sim iframe. Available in the main PhET-iO js import.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
Object | an HTML element representing the iframe with the simulation. |
Members
(static, constant) CAMEL_CASE_SIMULATION_NAME :string
The name of the simulation in lowercase camelCasing
Type:
- string
(static, constant) PHET_IO_LIB_ABSOLUTE_PATH :string
The path where the lib file has been deployed
Type:
- string
(static, constant) SIMULATION_NAME :string
The hyphenated name of the simulation
Type:
- string
(static, constant) SIMULATION_VERSION :string
The version of the simulation
Type:
- string
Methods
(static) appendQueryString(url, queryParameters) → {string}
Appends a query string to a given url.
Parameters:
| Name | Type | Description |
|---|---|---|
url |
may or may not already have other query parameters | |
queryParameters |
may start with '', '?' or '&' |
Returns:
- Type
- string
(static) appendQueryStringArray(url, queryStringArray) → {string}
Helper function for multiple query strings
Parameters:
| Name | Type | Description |
|---|---|---|
url |
string | may or may not already have other query parameters |
queryStringArray |
Array.<string> | each item may start with '', '?', or '&' |
Returns:
- Type
- string
(static) getSimPhetioID(suffix) → {string}
Most PhET-iO IDs are prefixed by the simulation name. This method automatically prepends the simulation
name to the phetioID.
Parameters:
| Name | Type | Description |
|---|---|---|
suffix |
string | the tail of the phetioID |
Returns:
- Type
- string
(static) getSimURL(config) → {string}
Gets the URL for launching the PhET-iO simulation HTML.
Parameters:
| Name | Type | Description |
|---|---|---|
config |
Object | {boolean} debug, {string} relativePathToRoot |
Returns:
- Type
- string
addOnErrorListener(callback) → {function}
Adds a callback when any invocation causes an error
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function | with a single {Error} argument. |
Returns:
wrapped function that can be removed with SimIFrameClient.removeMessageListener()
- Type
- function
dispose()
Release resources when the SimIFrameClient instance will no longer be used.
invoke(phetioID, method, argsopt, callbackopt)
Primary way to call a method on the simulation frame from the wrapper frame. Given an instance id, method name, and
arguments, invoke the method async and return values then errors (in that order) in the callback.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
phetioID |
InvocationData.phetioID | The id of the instance | |
method |
InvocationData.method | The name of the phet-io method | |
args |
InvocationData.args |
<optional> |
optional args |
callback |
function |
<optional> |
optional callback, parameters depend on method being invoked. |
invokeSequence(sequence, callbackopt)
If you need to send multiple messages or if the order of messages matters, then use invokeSequence.
callback is called when the entire sequence is complete.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
sequence |
Array.<InvocationData> | Each "Invocation" entry in the array will be run async. | |
callback |
function |
<optional> |
The arguments will depend on the return values of the methods invoked. The args will be all return values followed by all errors. i.e. if there are five invocations in a sequence call, each returning a single value, then there will be ten arguments in the callback. Further more if all are successful but the last, which returns an error, then there are still ten args, but (one indexed) args 5-9 will be null, and the tenth will hold an Error. |
launchSim(optionsopt)
Main launch point for the simulation, send a message into the simulation to begin. Some options can be very helpful
in customizing the simulation run before the launch command has been sent to the sim, see LaunchSimOptions object
for more.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
options |
LaunchSimOptions |
<optional> |
optional parameters to pass to the launch sequence |
onPhETiOInitialized(callback)
Adds a callback when the sim frame is ready for intercommunication. This happens even before the sim is ready to
launch.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function |
onSimInitialized(callback)
Adds a callback which is called when the sim has been initialized, when all screens have been constructed and the
sim is ready to be displayed.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function |
setValues(map, callback)
Convenience function for setting several values. Note the order of application is not guaranteed.
Parameters:
| Name | Type | Description |
|---|---|---|
map |
Object | |
callback |
function |