Asynchronous Commands

Most calls in Flash are synchronous which means when you call a function or method the results are available for use immediately. However, some methods in Flash execute asynchronously where the data is not available immediately but returned later via a callback function.

XML.load is an example of an asynchronous Flash method. When the data from a call to XML.load is available a callback function, such as XML.onLoad or XML.onData, is called telling you the data is ready. This functionality is similar to the way asynchronous commands in SWF Studio are handled.

When you call an SWF Studio command asynchronously you provide the name and location of a callback function that SWF Studio will call when the data is ready.

Example: asynchronous call with data returned to a callback function

ssCore.Win.getPosition({}, {callback:onComplete});

function onComplete(return_obj, callback_obj, error_obj)
{
    ssCore.App.showMsgBox({prompt:return_obj.x + "," + return_obj.y});
}

Asynchronous commands are useful when calling SWF Studio methods that take time to complete their tasks. Calling a method asynchronously is often the most effective way to make a call because an asynchronous command will not cause the Flash player to block (freeze playback) while waiting for data to be returned.

Some SWF Studio commands, like FTP.transfer, can only be called asynchronously. If this call was allowed to be synchronous your SWF Studio application would appear unresponsive for the duration of the transfer. Asynchronous-only commands are identified in the help by the phrase "This method can only be called asynchronously."

Attempting to call an asynchronous-only command synchronously will fail. Asynchronous-only commands that are called without specifying a callback parameters object or that set the sync property of the callback parameters object to true will not execute and the success property of the return object will be set to false.

see also: synchronous commands