execute

A method for executing SWF Studio commands from within a JScript module that is loaded into a SWF Studio application.


Availability:

First available in version 3.5.

Available only in ActionScript 3.


Usage:

returnObject = jsCore.execute(commandString[, parametersObject][, callbackParamsObject][, errorParamsObject])

returnObject - Object - Data is returned immediately to this object. The properties of this object correspond to the Output Parameters of the command specified in the commandString. Any properties on the parametersObject will be available on this object.


Parameters:

commandString - String - The command to execute. See the Plugins and ssCore sections for listings of available commands.

parametersObject - Object - [Optional] - An object containing properties that correspond to the Input Parameters of the command specified in the commandString.

callbackParamsObject - Object - [Optional] - The callback parameters object is used to specify the callback function for asynchronous commands, it can also be used to specify that a function should be called syncrhonously (see the sync property below).

errorParamsObject - Object - [Optional] - The error parameters object is used in asynchronous commands to specify the error callback function and its scope.


Notes:

The scope and errorScope properties are provided to be consistent with the ssCore API object. However, there is no "this" object in the main scope. In JavaScript specifying this in the main scope refers to the document object. In a SWF Studio JScript module there is no document object, and specifying "this" as part of an object reference will result in a runtime error.

When specifying a callback or errorCallback function that exists on the main scope specify the actual function reference instead of the function name as a string with a scope. Example 3 below demonstrates this.

If you call a JScript function from ActionScript synchronously, the JScript function can not call jsCore.execute or attempt to access ActionScript since the Flash Player is waiting for the JScript function to return. ActionScript in the Flash Player is single-threaded, and in this case, means the Flash Player will wait for the synchronous command to complete before running any further ActionScript. If your JScript function needs to access jsCore.execute or the Flash Player you should call the JScript function asynchronously.


Examples:

Example 1:
In this example we will minimize the window.

jsCore.execute("Win.minimize");

Example 2:
Here we will prompt the user with a message box and send a message to the SWF Studio trace window depending on the response chosen. This example assumes jsDefaults.synchronousCommands is set to true.

var return_obj = jsCore.execute("App.showMsgBox", {prompt:"Do you like green eggs and ham?", buttons:"YESNO"});

if (return_obj.result == "YES")
{
    trace("You like green eggs and ham!");
}
else if (return_obj.result == "NO")
{
    trace("You're probably with the majority!");
}

Example 3:
This is the same as the example above except that we specify a callback function that will be called when data is returned. The command is executed asynchronously.

jsCore.execute("App.showMsgBox", {prompt:"Do you like green eggs and ham?", buttons:"YESNO"}, {callback:onAnswer});

function onAnswer(return_obj, callback_obj, error_obj)
{
    if (return_obj.result == "YES")
    {
        trace("You like green eggs and ham!");
    }
    else if (return_obj.result == "NO")
    {
        trace("You're probably with the majority!");
    }
}

Example 4:
This example demonstrates a function that will encrypt and then compress a file. If the process fails at any point we return false, which stops further processing of the function and returns the value of false where the function call was made. In the case where this function is called from ActionScript, the value of the out parameter "result" will be populated with false. If the function completes without errors the value of true will be returned. This example assumes jsDefaults.synchronousCommands is set to true.

function packageFile()
{
    var enc_obj = jsCore.execute("Crypto.encryptFile", {source:"startdir://file.doc", destination:"startdir://file.enc"});

    if (!enc_obj.success)
    {
        alert("Error encrypting file:"+enc_obj.Error.description);
        return false;
    }

    var comp_obj = jsCore.execute("Compress.deflateFile", {source:enc_obj.source, destination:enc_obj.destination, key:"1234567890"});

    if (!comp_obj.success)
    {
        alert("Error compressing file:"+comp_obj.Error.description);
        return false;
    }

    return true;
}