Handling Flex Events in GWT

Tightly integrating Flex components in GWT applications requires that GWT is notified on events triggered in Flex. For example, when the user performs an action in the Flex component, e.g. double-clicking a node in a graph widget, we might want to perform some operations on the GWT side, e.g. updating a dependent view to show information about the double-clicked node. This tutorial shows how UI event from Flex can be forward to and handled by GWT code. The example contains a GWT text box and a Flex text box and buttons for copying the text from one to the other. This tutorial is the third part of a series of blog posts about using Flex components in GWT with the library gwt2swf:

1. GWT Wrapper for Flex components
2. Notifying GWT when a Flex widget is loaded [Demo, Source Code]
3. Handling Flex events in GWT [Demo, Source Code]

This tutorial is based on the previous one, notifying GWT when a Flex widget is loaded, and assumes that you have a similar project setup and that you have created the classes and files with the source code from that tutorial. The main ideas are similar those from the previous tutorial, but we will explicitly register our event handler bridge as a callback in Flex. That way, the Flex component can expose operations that might not be used by our GWT application, but in other applications, e.g. separate JavaScript projects, without requiring the GWT wrapper to provide hooks for those operations.

The Flex component is first extended by adding a 'send' button and changing the text to a text input. Then a method for adding a JavaScript method as event listener is implemented and exposed. When calling registered event listeners, the Flex components adds the content of the text field, so we can use it on the GWT side. Alternatively, one could implement and expose a method for getting the content of the Flex text field from JavaScript.

Text.mxml

<mx:Button id="sendButton" x="200" width="80" label="Send"/>
<mx:TextInput id="textWidget" x="0" width="200"/>

...    

public function addSendListener(jsFunctionName:String):void {
  sendButton.addEventListener(MouseEvent.CLICK, function(event:MouseEvent):void {
    ExternalInterface.call(jsFunctionName, swfID, textWidget.text);       
  });
}
      
private function init():void {
...
  addJSCallback("addSendListener", addSendListener);
}

The complete Flex component should look like this:

Text.mxml

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
  layout="absolute" creationComplete="init()"
  backgroundColor="0xffffff" paddingBottom="0" paddingLeft="0" 
  paddingRight="0" paddingTop="0">
  
  <mx:Script>
    <![CDATA[
    
    import mx.events.FlexEvent;

    public function displayText(text:String):void {
      textWidget.text = text;
    }   
      
    private function init():void {
      addEventListener(FlexEvent.APPLICATION_COMPLETE, onApplicationComplete);
      addJSCallback("displayText", displayText);
      addJSCallback("addSendListener", addSendListener);
    }
    
    private function onApplicationComplete(event:FlexEvent):void {
        callLater(function():void {
          ExternalInterface.call("_swf_application_complete", swfID);
        });
      }
    
    public static function addJSCallback(jsFunctionName:String, flexFunction:Function):void {
        try {
          if (ExternalInterface.available) {
          ExternalInterface.addCallback(jsFunctionName, flexFunction);
          }
      } catch (error:SecurityError) {
        trace("Couldn't add javascript callback: " + error);
      }
      } 
      
    public function addSendListener(jsFunctionName:String):void {
      sendButton.addEventListener(MouseEvent.CLICK, function(event:MouseEvent):void {
        ExternalInterface.call(jsFunctionName, swfID, textWidget.text);       
      });
    }
      
    public function get swfID():String {
      return Application.application.parameters.swfid;
    }

    ]]>
  </mx:Script>
  
  <mx:Button id="sendButton" x="200" width="80" label="Send"/>
  <mx:TextInput id="textWidget" x="0" width="200"/>
  
</mx:Application>

Now we can build the Flex project and copy the generated .swf file into the GWT project. It should be under the 'public' folder below the folder that contains the .gwt.xml file, e.g. in my case as 'src/de/larsgrammel/blog/flexgwt/public/Test.swf'.

The GWT wrapper keeps track of event handler that are interested in this send event. For that purpose, we add custom event and event handler classes:

TextSentEvent.java

import com.google.gwt.event.shared.GwtEvent;

public class TextSentEvent extends GwtEvent<TextSentEventHandler> {

  public static final Type<TextSentEventHandler> TYPE = new Type<TextSentEventHandler>();

  private SampleFlexWrapperWidget swfWidget;

  private String newText;

  public TextSentEvent(SampleFlexWrapperWidget swfWidget, String newText) {
    assert swfWidget != null;
    this.newText = newText;
    this.swfWidget = swfWidget;
  }

  protected void dispatch(TextSentEventHandler handler) {
    handler.onTextSent(this);
  }

  public String getNewText() {
    return newText;
  }

  public Type<TextSentEventHandler> getAssociatedType() {
    return TYPE;
  }

  public SampleFlexWrapperWidget getSWFWidget() {
    return swfWidget;
  }
}

TextSentEventHandler.java

public interface TextSentEventHandler extends EventHandler {

  void onTextSent(TextSentEvent event);

}

Now, we add a method for registering TextSentEventHandlers to our SampleFlexWrapperWidget:

SampleFlexWrapperWidget.java

...

public HandlerRegistration addTextSentEventHandler(
    TextSentEventHandler handler) {

  return addHandler(handler, TextSentEvent.TYPE);
}

The next two methods forward the Flex events to the registered event handlers:

SampleFlexWrapperWidget.java

...

public static void _onTextSent(String swfId, String text) {
  swfWidgets.get(swfId).onTextSent(text);
}
    
private void onTextSent(String text) {
  fireEvent(new TextSentEvent(this, text));
}

Now we register the _onTextSent method as listener on the Flex component by exposing it as a JavaScript method. The GWT guide recommends that Java methods should be wrapped by $entry() when exposing them as JavaScript callback points. We thus register our wrapped _onTextSent method as JavaScript handle once the Flex component finished loading.

SampleFlexWrapperWidget.java

...

public static void onSwfApplicationComplete(String swfId) {
  _registerSwfListeners(swfId);
  ...
}

private static native void _registerSwfListeners(String swfID) /*-{
  var swfWidget = $doc.getElementById(swfID);
  swfWidget.addSendListener("_swf_on_text_sent");
}-*/;

private static native void registerCallbackMethods() /*-{
  $wnd._swf_on_text_sent=
  $entry(@de.larsgrammel.blog.flexgwt.client.SampleFlexWrapperWidget::_onTextSent(Ljava/lang/String;Ljava/lang/String;));
  ...
}-*/;

Finally, we change our main code to use the new functionality of our wrapper by updating the GWT text field when the Flex component sents over new text:

FlexGWTIntegration.java

...
flexWidget.addTextSentEventHandler(new TextSentEventHandler() {
  public void onTextSent(TextSentEvent event) {
    textField.setText(event.getNewText());
  }
});

The complete FlexGWTIntegration and SampleFlexWrapperWidget should look like this now:

SampleFlexWrapperWidget.java

import java.util.HashMap;
import java.util.Map;

import pl.rmalinowski.gwt2swf.client.ui.SWFWidget;

import com.google.gwt.event.shared.HandlerRegistration;

public class SampleFlexWrapperWidget extends SWFWidget {

  private static Map<String, SampleFlexWrapperWidget> swfWidgets = new HashMap<String, SampleFlexWrapperWidget>();

  static {
    registerCallbackMethods();
  }

  private static native void _displayText(String swfID, String text) /*-{
    $doc.getElementById(swfID).displayText(text);
  }-*/;

  public static void onSwfApplicationComplete(String swfId) {
    _registerSwfListeners(swfId);
    swfWidgets.get(swfId).fireSWFWidgetReady();
  }

  private static native void _registerSwfListeners(String swfID) /*-{
    var swfWidget = $doc.getElementById(swfID);
    swfWidget.addSendListener("_swf_on_text_sent");
  }-*/;

  private static native void registerCallbackMethods() /*-{
    $wnd._swf_on_text_sent=
    $entry(@de.larsgrammel.blog.flexgwt.client.SampleFlexWrapperWidget::_onTextSent(Ljava/lang/String;Ljava/lang/String;));
    $wnd._swf_application_complete=
    $entry(@de.larsgrammel.blog.flexgwt.client.SampleFlexWrapperWidget::onSwfApplicationComplete(Ljava/lang/String;));
  }-*/;

  public SampleFlexWrapperWidget(int width, int height) {
    super("flexgwtintegration/Test.swf", width, height);
    addFlashVar("swfid", getSwfId());
  }

  public HandlerRegistration addSWFWidgetReadyHandler(
      SWFWidgetReadyHandler handler) {
    
    return addHandler(handler, SWFWidgetReadyEvent.TYPE);
  }

  public HandlerRegistration addTextSentEventHandler(
      TextSentEventHandler handler) {

    return addHandler(handler, TextSentEvent.TYPE);
  }

  public static void _onTextSent(String swfId, String text) {
    swfWidgets.get(swfId).onTextSent(text);
  }

  private void onTextSent(String text) {
    fireEvent(new TextSentEvent(this, text));
  }

  public void displayText(String text) {
    _displayText(getSwfId(), text);
  }

  private void fireSWFWidgetReady() {
    fireEvent(new SWFWidgetReadyEvent(this));
  }

  protected void onLoad() {
    super.onLoad();
    SampleFlexWrapperWidget.swfWidgets.put(getSwfId(), this);
  }

  protected void onUnload() {
    SampleFlexWrapperWidget.swfWidgets.remove(getSwfId());
    super.onUnload();
  }
}

FlexGWTIntegration.java

import com.google.gwt.core.client.EntryPoint;
import com.google.gwt.event.dom.client.ClickEvent;
import com.google.gwt.event.dom.client.ClickHandler;
import com.google.gwt.event.dom.client.KeyCodes;
import com.google.gwt.event.dom.client.KeyUpEvent;
import com.google.gwt.event.dom.client.KeyUpHandler;
import com.google.gwt.user.client.ui.Button;
import com.google.gwt.user.client.ui.RootPanel;
import com.google.gwt.user.client.ui.TextBox;

public class FlexGWTIntegration implements EntryPoint {

  public void onModuleLoad() {
    final Button sendButton = new Button("Send to Flex");
    final TextBox textField = new TextBox();
    textField.setText("from GWT");

    final SampleFlexWrapperWidget flexWidget = 
      new SampleFlexWrapperWidget(300, 50);

    RootPanel.get().add(textField);
    RootPanel.get().add(sendButton);

    RootPanel.get().add(flexWidget);

    textField.setFocus(true);
    textField.selectAll();

    class MyHandler implements ClickHandler, KeyUpHandler {
      public void onClick(ClickEvent event) {
        displayTextInFlex();
      }

      public void onKeyUp(KeyUpEvent event) {
        if (event.getNativeKeyCode() == KeyCodes.KEY_ENTER) {
          displayTextInFlex();
        }
      }

      private void displayTextInFlex() {
        flexWidget.displayText(textField.getText());
      }
    }

    MyHandler handler = new MyHandler();
    sendButton.addClickHandler(handler);
    textField.addKeyUpHandler(handler);

    flexWidget.addTextSentEventHandler(new TextSentEventHandler() {
      public void onTextSent(TextSentEvent event) {
        textField.setText(event.getNewText());
      }
    });
  }
}

This example code allows you to send text from GWT to Flex and from Flex to GWT (demo). Together with the first two parts of this tutorial series, this should enable you to use a Flex component from GWT in a way that resembles the GWT API. There are a couple more details that I will cover in future posts.

Notifying GWT when a Flex widget is initialized

Flex .swf files can take a while to load. When using Flex components from within GWT, this means that the GWT user interface tends to be ready while the Flex widgets are still loading. This can cause problems if we call methods on those Flex widgets before they are completely initialized. This tutorial shows how to notify GWT when a Flex widget is ready, and how to prevent the problem of calling an uninitialized Flex widget. It is the second part of a series of blog posts about using Flex components in GWT with the library gwt2swf:

1. GWT Wrapper for Flex components
2. Notifying GWT when a Flex widget is loaded [Demo, Source Code]
3. Handling Flex events in GWT [Demo, Source Code]

This tutorial is based on the previous one, creating a GWT Wrapper for Flex components, and assumes that you have a similar project setup and that you have created the classes and files with the source code from that tutorial.

The general idea is to listen for the application complete event in Flex, to forward this event to the GWT wrapper and to notify listeners on the GWT side. For this to work, the Flex widget must include it's swfID when forwarding the event to GWT, because we need to know which Flex widget should get notified on the GWT side if we have multiple Flex widgets. For some reason, the Flex application id does not seem to work for that purpose on all browsers, so we pass it in as a Flash var:

1. Add addFlashVar call for passing the swfid into the Flex component to the SampleFlexWrapperWidget constructor:

addFlashVar("swfid", getSwfId());

The whole constructor should look like this:

public SampleFlexWrapperWidget(int width, int height) {
  super("flexgwtintegration/Test.swf", width, height);
  addFlashVar("swfid", getSwfId());
}

2. In the Flex component, add an accessor to that property:

public function get swfID():String {
  return Application.application.parameters.swfid;
}

Now we can use the swf id within Flex. The next step is to listen for the application complete event in Flex and to forward it to GWT.

3. Add the event listener for the application complete event in the init() method of our Flex widget. We use the application complete event, because we want to make sure that the widget is visible and ready (More information on the Flex Application startup event order).

addEventListener(FlexEvent.APPLICATION_COMPLETE, onApplicationComplete);

The whole init method should look like this:

private function init():void {
  addEventListener(FlexEvent.APPLICATION_COMPLETE, onApplicationComplete);
  addJSCallback("displayText", displayText);
}

4. Add the event listener method to the Flex widget. We use callLater here to make sure the widget is ready when the event is fired. The method calls the method with the javascript identifier _swf_application_complete, which we will implement soon.

import mx.events.FlexEvent;

private function onApplicationComplete(event:FlexEvent):void {
  callLater(function():void {
    ExternalInterface.call("_swf_application_complete", swfID);
  });
}

The complete Flex widget should look like this by now:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
layout="absolute" creationComplete="init()"
backgroundColor="0xffffff" paddingBottom="0" paddingLeft="0" 
paddingRight="0" paddingTop="0">
  
<mx:Script>
<![CDATA[
    
import mx.events.FlexEvent;

public function displayText(text:String):void {
  textWidget.text = text;
}   
      
private function init():void {
  addEventListener(FlexEvent.APPLICATION_COMPLETE, onApplicationComplete);
  addJSCallback("displayText", displayText);
}
    
private function onApplicationComplete(event:FlexEvent):void {
  callLater(function():void {
    ExternalInterface.call("_swf_application_complete", swfID);
  });
}
    
public static function addJSCallback(jsFunctionName:String, flexFunction:Function):void {
  try {
    if (ExternalInterface.available) {
      ExternalInterface.addCallback(jsFunctionName, flexFunction);
    }
  } catch (error:SecurityError) {
    trace("Couldn't add javascript callback: " + error);
  }
} 
      
public function get swfID():String {
  return Application.application.parameters.swfid;
}

]]>
</mx:Script>
<mx:Text id="textWidget" width="100%"/> 
</mx:Application>

5. Build the Flex project and copy the generated .swf file into the GWT project. It should be under the 'public' folder below the folder that contains the .gwt.xml file, e.g. in my case as 'src/de/larsgrammel/blog/flexgwt/public/Test.swf'.

That's it on the Flex side. On the GWT side, we need to keep track of the different widgets and their swf id's so we can forward the event to the right widget.

6. Create a static map that enables us to find the GWT wrapper for a given swf id:

private static Map<String, SampleFlexWrapperWidget> swfWidgets = new HashMap<String, SampleFlexWrapperWidget>();

7. Register the widget in the map when loaded and deregister it when unloaded:

@Override
protected void onLoad() {
  super.onLoad();
  SampleFlexWrapperWidget.swfWidgets.put(getSwfId(), this);
}

@Override
protected void onUnload() {
  SampleFlexWrapperWidget.swfWidgets.remove(getSwfId());
  super.onUnload();
}

Now we can add the methods that are called from Flex.

8. Create a class initializer that calls a JSNI method to register the callback methods. That way, the first time one of our wrapper widgets gets created (i.e. the class is loaded), our callback method is registered.

static {
  registerCallbackMethods();
}

9. Create the JSNI method that links a Java method to the callback point '_swf_application_complete':

private static native void registerCallbackMethods() /*-{
  $wnd._swf_application_complete=
  @de.larsgrammel.blog.flexgwt.client.SampleFlexWrapperWidget::onSwfApplicationComplete(Ljava/lang/String;);
}-*/;

10. Add the method that routes the event to the correct wrapper and calls fireSWFWidgetReady on that wrapper:

public static void onSwfApplicationComplete(String swfId) {
  swfWidgets.get(swfId).fireSWFWidgetReady();
}

We need a special event and handler on the GWT. So lets create those and the related methods in the wrapper.

11. Create SWFWidgetReadyEvent and SWFWidgetReadyHandler

package de.larsgrammel.blog.flexgwt.client;

import com.google.gwt.event.shared.GwtEvent;

public class SWFWidgetReadyEvent extends GwtEvent<SWFWidgetReadyHandler> {

  public static final Type<SWFWidgetReadyHandler> TYPE = new Type<SWFWidgetReadyHandler>();

  private SampleFlexWrapperWidget swfWidget;

  public SWFWidgetReadyEvent(SampleFlexWrapperWidget swfWidget) {
    assert swfWidget != null;
    this.swfWidget = swfWidget;
  }

  @Override
  protected void dispatch(SWFWidgetReadyHandler handler) {
    handler.onSWFWidgetReady(this);
  }

  @Override
  public Type<SWFWidgetReadyHandler> getAssociatedType() {
    return TYPE;
  }

  public SampleFlexWrapperWidget getSWFWidget() {
    return swfWidget;
  }

}

package de.larsgrammel.blog.flexgwt.client;

import com.google.gwt.event.shared.EventHandler;

public interface SWFWidgetReadyHandler extends EventHandler {

  void onSWFWidgetReady(SWFWidgetReadyEvent event);

}

12. Add a method to register a SWFWidgetReadyHandler in the wrapper class - make sure to return the HandlerRegistration so the
listener can be remove if needed:

public HandlerRegistration addSWFWidgetReadyHandler(
  SWFWidgetReadyHandler handler) {

  return addHandler(handler, SWFWidgetReadyEvent.TYPE);
}

13. Implement the fireSWFWidgetReady method:

private void fireSWFWidgetReady() {
  fireEvent(new SWFWidgetReadyEvent(this));
}

The whole SampleFlexWrapperWidget should look similar to this by now:

package de.larsgrammel.blog.flexgwt.client;

import java.util.HashMap;
import java.util.Map;

import pl.rmalinowski.gwt2swf.client.ui.SWFWidget;

import com.google.gwt.event.shared.HandlerRegistration;

public class SampleFlexWrapperWidget extends SWFWidget {

  private static Map<String, SampleFlexWrapperWidget> swfWidgets = new HashMap<String, SampleFlexWrapperWidget>();

  static {
    registerCallbackMethods();
  }

  private static native void _displayText(String swfID, String text) /*-{
    $doc.getElementById(swfID).displayText(text);
  }-*/;

  public static void onSwfApplicationComplete(String swfId) {
    swfWidgets.get(swfId).fireSWFWidgetReady();
  }

  private static native void registerCallbackMethods() /*-{
    $wnd._swf_application_complete=
    @de.larsgrammel.blog.flexgwt.client.SampleFlexWrapperWidget::onSwfApplicationComplete(Ljava/lang/String;);
  }-*/;

  public SampleFlexWrapperWidget(int width, int height) {
    super("flexgwtintegration/Test.swf", width, height);
    addFlashVar("swfid", getSwfId());
  }

  public HandlerRegistration addSWFWidgetReadyHandler(
      SWFWidgetReadyHandler handler) {
    return addHandler(handler, SWFWidgetReadyEvent.TYPE);
  }

  public void displayText(String text) {
    _displayText(getSwfId(), text);
  }

  private void fireSWFWidgetReady() {
    fireEvent(new SWFWidgetReadyEvent(this));
  }

  @Override
  protected void onLoad() {
    super.onLoad();
    SampleFlexWrapperWidget.swfWidgets.put(getSwfId(), this);
  }

  @Override
  protected void onUnload() {
    SampleFlexWrapperWidget.swfWidgets.remove(getSwfId());
    super.onUnload();
  }

}

14. In the client code that uses the widget, we can now disable our control widgets by default and then enable them once the Flex widgets are ready:

nameField.setEnabled(false);
sendButton.setEnabled(false);
  
flexWidget.addSWFWidgetReadyHandler(new SWFWidgetReadyHandler() {
  @Override
  public void onSWFWidgetReady(SWFWidgetReadyEvent event) {
    nameField.setEnabled(true);
    sendButton.setEnabled(true);
  }
});

I refactored the client code a bit. It now adds two similar Flex wrappers including controls by calling a addFlexWidgetAndGWTControls method. I also removed the automatic text focus - you would need to decide for one of those controls to get the focus for this to work properly. The client code looks like this:

package de.larsgrammel.blog.flexgwt.client;

import com.google.gwt.core.client.EntryPoint;
import com.google.gwt.event.dom.client.ClickEvent;
import com.google.gwt.event.dom.client.ClickHandler;
import com.google.gwt.event.dom.client.KeyCodes;
import com.google.gwt.event.dom.client.KeyUpEvent;
import com.google.gwt.event.dom.client.KeyUpHandler;
import com.google.gwt.user.client.ui.Button;
import com.google.gwt.user.client.ui.RootPanel;
import com.google.gwt.user.client.ui.TextBox;

public class FlexGWTIntegration implements EntryPoint {

  public void onModuleLoad() {
    addFlexWidgetAndGWTControls();
    addFlexWidgetAndGWTControls();
  }

  private void addFlexWidgetAndGWTControls() {
    final Button sendButton = new Button("Send");
    final TextBox nameField = new TextBox();
    nameField.setText("GWT User");

    nameField.setEnabled(false);
    sendButton.setEnabled(false);

    final SampleFlexWrapperWidget flexWidget = new SampleFlexWrapperWidget(
      100, 50);

    RootPanel.get().add(nameField);
    RootPanel.get().add(sendButton);
    RootPanel.get().add(flexWidget);

    class MyHandler implements ClickHandler, KeyUpHandler {
      public void onClick(ClickEvent event) {
        displayTextInFlex();
      }

      public void onKeyUp(KeyUpEvent event) {
        if (event.getNativeKeyCode() == KeyCodes.KEY_ENTER) {
          displayTextInFlex();
        }
      }

      private void displayTextInFlex() {
        flexWidget.displayText(nameField.getText());
      }
    }

    // Add a handler to send the name to the server
    MyHandler handler = new MyHandler();
    sendButton.addClickHandler(handler);
    nameField.addKeyUpHandler(handler);

    flexWidget.addSWFWidgetReadyHandler(new SWFWidgetReadyHandler() {
      @Override
      public void onSWFWidgetReady(SWFWidgetReadyEvent event) {
        nameField.setEnabled(true);
        sendButton.setEnabled(true);
      }
    });
  }
}

With this approach, your GWT controls should be disabled until the Flex widgets are completely loaded - and it should work with multiple Flex widgets. More on integrating Flex and GWT will be covered in future posts, so stay tuned.