Communication with Flash

There are three main ways an application can communicate with the loaded Flash movie: External API, FSCommands and Variables.

FSCommands and Variables are considered to be an older way to communicate with Flash, and they are one-way only.

FSCommands were developed to send data from SWF to application. Variables are used to send data from application to SWF (though application can access and set a certain variable, there’s no way SWF movie can make the application re-read the value of the variable). That is why in case you decide to use FSCommands or variables, most probably you will have to implement them both for more complex tasks. 

More about FSCommands:

More about External API:

External API is a newer method to handle communication between application and SWF. It has become available since the release of Flash 8. External API lets you organize a full-duplex communication between Flash and application almost without any visible limitations.

 

Contents


 

External API


The ExternalInterface class is the External API, an application programming interface that enables straightforward communication between ActionScript and the Flash Player container – for example, your application which uses Flash’In’App. Adobe recommends using ExternalInterface for SWF-application communication.

You can call an ActionScript function in Flash Player, using Flash’In’App. The ActionScript function can return a value, and your application receives it immediately as the return value of the call.

This functionality replaces the fscommand() method.

From ActionScript, you can do the following regarding your application:

  • Call any function from an application using XML
  • Pass any number of arguments, with any names
  • Pass various data types (Boolean, Number, String, and so on)
  • Receive a return value from the application

From application you can:

  • Call an ActionScript function
  • Pass arguments using standard function call notation
  • Read the return value from the loaded Flash movie

To receive the calls from ExternalAPI you need to assign a delegate to ESFlashView and implement flashView:callFunction: or flashView:callFunction:withArguments: method in it. In the method you will need to implement the calls’ handler or whatever you like. Here is an example:

Listing 1: Example of flashView:callFunction: implementation:

   - (id) flashView:(ESFlashView *)flashView callFunction:(NSString *)xmlString
  {
    // show alert pane with call string as message
    NSRunAlertPane(@"External call:", xmlString, @"OK", nil, nil);
    // return string to Flash movie
    return @"return to AS";
  }

Listing 2: Example of flashView:callFunction:withArguments: implementation:

  - (id) flashView:(ESFlashView *)flashView callFunction:(NSString*)aName withArguments:(NSArray *)anArguments
  {
    // show alert pane with function name as message
    NSRunAlertPane(@"External call:", aName, @"OK", nil, nil);
    // return string to Flash movie
    return @"return to AS";
  }

NOTE: If you implement both flashView:callFunction: and flashView:callFunction:withArguments: methods, only flashView:callFunction:withArguments: will be called.

Listing 3: Example of how flashView:callFunction: can be called from SWF movie:

 ExternalInterface.call("cocoaFunc", "string argument");

At the same time, you can call ActionScript functions from your application. To do this, call callFunction: method and pass the line with the name of the function and its parameters as an argument to this method. You can also receive the return value from ActionScript function. The following code demonstrates how an application can call a function from SWF file.

Listing 4: Calling an ActionScript function using callFunction:

  // create string, which contains function name and arguments
  NSString *asFunctionString = @"<invoke name=\"asFunc\"><arguments><string>Hello from Cocoa</string></arguments></invoke>";

  // call Flash movie function
  // returnFromAS – contains call function results
  id returnFromAS = [flashView callFunction:asFunctionString];

  //display alert pane with call function results as message
  NSRunAlertPane(@"Returned from AS:", returnFromAS ? [returnFromAS description] : @"void", @"OK", nil, nil);

Listing 5: Calling an ActionScript function using invokeFunction:withArguments:

   // call Flash movie function
  // returnFromAS – contains call function results 
  id returnFromAS = [flashView invokeFunction:@"asFunc" withArguments:[NSArray arrayWithObjects:@"Hello from Cocoa", nil]];

  //display alert pane with call function results as message
   NSRunAlertPane(@"Returned from AS:", returnFromAS ? [returnFromAS description] : @"void", @"OK", nil, nil)

However, to make it work correctly you need to register a special function in SWF movie which will be available to External API. Listing 6 will show you how you can do it.

Listing 6: A sample of registering a function visible to External API:

 function asFunc(str):String {
    //eiLine – variable, connected with Input Text component
    _root.eiLine = str;
    return "returned from AS"
  }

  ExternalInterface.addCallback("asFunc", this, asFunc);

Note: Calling a function which was not declared correctly according to Listing 6 will cause your application’s crash. To avoid it, call a function as shown in Listing 5 instead.

Also, you can see how to handle External API in the source code of our GUI and API samples.

 

FSCommand


Use the fscommand() function to send a message to any program hosting Flash Player, e.g. your application using Flash’In’App or a web browser.

The fscommand() function has two parameters: command and arguments.

To use fscommand() to send a message to the application using Flash’In’App, you can pass any two parameters in the command and arguments parameters. These parameters can be strings or expressions and are used in JavaScript function that “catches,” or handles, the fscommand() function.
 
To receive FSCommand calls you need to assign a delegate to ESFlashView and implement flashView:invokeFSCommand:withArguments: method in it. In this method you will need to implement calls’ handler or whatever you like. Listing 7 shows the sample of how you can handle an FSCommand in your application.

Listing 7: Example of flashView:invokeFSCommand:withArguments: delegate method: 

  - (id) flashView:(ESFlashView *)flashView invokeFSCommand:(NSString *)commandName withArguments:(NSArray *)arguments;
  {
    if([commandName isEqualToString:@"quit"])
    {
      // if quit command was received, then close application 

      [NSApp terminate:nil];
    }
    return nil;
  }
Note: The External API is an alternative to fscommand() in Flash of v.8 and later for interoperability with container application. The External API offers more robust functionality than fscommand() in this situation. For more information, see About the External API.
 
 

Variables


Communication with the Flash movie using Variables can be organized with the help of setVariable: and getVariable: methods. You will access variables by names, so you can access any variable which is present in the Flash movie. You can find the sample of using these two functions in Listing 8.

Listing 8: A simple sample of using setVariable: and getVariable:

   // set stringVar value to "string value"
  [flashView setVariable:@"stringVar" toValue:@"string value"];
  // set intVar value to 1
  [flashView setVariable:@"intVar" toValue:[NSNumber numberWithInt:1]];
  // set floatVar value to 0.5
  [flashView setVariable:@"floatVar" toValue:[NSNumber numberWithFloat:0.5]];

  // display alert pane with swfVar value as message
  NSRunAlertPane(@"Value of \"swfVar\" variable:", [[flashView getVariable:@"swfVar"] description], @"OK", nil, nil);