Thursday, July 10, 2008

Creating a Frameworkless MXML File

Me saying it’s been a while since I’ve blogged here is an understatement. I’ve been heads down doing work on Flex 4, atleast that’s my excuse, and I’m sticking to it. Along the way of deep-diving into the framework, I’ve learned how much of the nitty-gritty details actually work. Unfortunately, not all of it would be really valuable to you guys, but as I think of useful lessons I’ve learned, I’ll blog about them here. Anyways, on to the real post: using the Flex Builder IDE and the MXML compiler for generating framework-less code. By framework-less code, I mean no mx.core.*, no SystemManager, no Application, no UIComponents, etc… So why would you want to do this? Let’s say you want to create something really light-weight and don’t want to carry around some of the framework baggage, but you still want to use FlexBuilder IDE because it’s made for programmers, unlike the Flash Authoring IDE. Or, you want to create an ActionScript only project, but love the MXML syntax because it’s a lot easier for non-progammers to take a look at the MXML code and figure out what’s going on. Some awesome features won’t be available if you don’t use the framework (for instance, binding), but this technique might prove useful to some. At first, I didn’t know you could actually do this, but it’s quite easy. If you just have one file that is your main ActionScript file, in fact you don’t have to do anything. So let’s say I wanted to create a clock (and not a sweet analog clock, but just a digital one because I’m lame). Pop open FlexBuilder and create a simple project. Create a simple class called SimpleDigitalClock.as. You’ve got to make sure it extends Sprite because in Flash, the root object must always be a Sprite. My primitive understanding of the reason is that every SWF must have a root object that needs to be a Sprite. This object will be instantiated automatically by the Flash player. Our clock is going to be super-simple (I’m super-lazy). Here’s my version, but feel free to do something fancier with yours:
package
{
  import flash.display.Sprite;
  import flash.events.TimerEvent;
  import flash.text.TextField;
  import flash.utils.Timer;

  public class SimpleDigitalClock extends Sprite
  {
      public function SimpleDigitalClock()
      {
          super();
       
          time = new TextField();
          addChild(time);
       
          updateTime();
       
          timer = new Timer(1000);
          timer.addEventListener(TimerEvent.TIMER, updateTime);
          timer.start();
      }
   
      private var time:TextField;
      private var timer:Timer;
   
      private function updateTime(event:TimerEvent = null):void
      {
          time.text = new Date().toString();
      }
   
  }
}
As mentioned before I extend Sprite. In the constructor I create a new TextField and add it as a child. Then I call updateTime, which grabs the current time and puts it into our TextField. Lastly, I just create a Timer which runs every second to update the time so it stays current. So my FlexBuilder project looks like this (just two files): Now for the cool part. Let’s say I wanted to make this my Application. Well it’s actually really easy, just change your main MXML file to look like this:
<?xml version="1.0" encoding="utf-8"?>
<local:SimpleDigialClock xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:local="*">

</local:SimpleDigitalClock>
We can run this file, and we get this beauty: Some points to note:
  • We kept the mx namespace because the compiler needs this info, even though no components are instantiated from the mx namespace (hopefully I’ll talk about how this is done in another blog).
  • xmlns:local=”*” creates a new namespace, called local, which maps to actionscript files in my current directory.
  • All we need to do is tell the MXML compiler to instantiate our Sprite object, SimpleDigitalClock, as the root object for this SWF.
So that’s pretty damned simple. One of the things I often do is to delve into the compiled code. To do this, add “-keep” or “-keep-actionscript-generated” to the additional compiler arguments: A new folder will popup called “generated.” This will be especially small because we’re using framework-less code. In fact, it’s only 2 files: FrameworkLessClock-generated.as and FrameworkLessClock-interface.as. Only the first one’s really interesting:
/**
*  Generated by mxmlc 4.0
*
*  Package: 
*  Class:      FrameworkLessClock
*  Source:     C:\Documents and Settings\rfrishbe\My Documents\Gumbo-FP10-MyBranch\FrameworkLessClock\src\FrameworkLessClock.mxml
*  Template:   flex2/compiler/mxml/gen/ClassDef.vm
*  Time:       2008.07.10 18:37:50 PDT
*/

package
{

import SimpleDigitalClock;
import flash.accessibility.*;
import flash.debugger.*;
import flash.display.*;
import flash.errors.*;
import flash.events.*;
import flash.external.*;
import flash.filters.*;
import flash.geom.*;
import flash.media.*;
import flash.net.*;
import flash.printing.*;
import flash.profiler.*;
import flash.system.*;
import flash.text.*;
import flash.ui.*;
import flash.utils.*;
import flash.xml.*;
import mx.binding.*;
import mx.core.ClassFactory;
import mx.core.DeferredInstanceFromClass;
import mx.core.DeferredInstanceFromFunction;
import mx.core.IDeferredInstance;
import mx.core.IFactory;
import mx.core.IPropertyChangeNotifier;
import mx.core.mx_internal;
import mx.styles.*;



//  begin class def

public class FrameworkLessClock
  extends SimpleDigitalClock
{

  //  instance variables
  //  type-import dummies
  //  constructor (non-Flex display object)
  /**
   * @private
   **/
  public function FrameworkLessClock()
  {
      super();
      //    our style settings
      //    properties
      //    events
  }

  //  scripts
  //  end scripts
  //    supporting function definitions for properties, events, styles, effects
  //  embed carrier vars
  //  end embed carrier vars
//  end class def
}
//  end package def
}
So you see not much happens. There’s a lot of comments in there for some framework stuff, but not much happens in our case because we don’t need that stuff. Let’s say you add event-listeners or properties to your SimpleDigitalClock. Those will get genned in here. So for a simple example, let’s create a property called timeZoneOffset, which will be the timezone offset (in minutes) that we want to change our clock to. I won’t go into the details of the math, but I think it works out… Also, let’s create a clockUpdated event, which dispatches anytime we change the text on the clock. The important pieces are highlighted in red:
package
{
  import flash.display.Sprite;
  import flash.events.Event;
  import flash.events.TimerEvent;
  import flash.text.TextField;
  import flash.utils.Timer;

  [Event("clockUpdated")]

  public class SimpleDigitalClock extends Sprite
  {
      public function SimpleDigitalClock()
      {
          super();
       
          time = new TextField();
          addChild(time);
       
          timer = new Timer(1000);
          timer.addEventListener(TimerEvent.TIMER, updateTime);
          timer.start();
      }
   
      private var time:TextField;
      private var timer:Timer;
   
      public var timeZoneOffset:int = new Date().getTimezoneOffset();
   
      private function updateTime(event:TimerEvent = null):void
      {
          var date:Date = new Date();
       
          // converts the Date to UTC by adding or subtracting the time zone offset
          var currentOffsetMilliseconds:Number = date.getTimezoneOffset() * 60 * 1000;
          var newOffsetMilliseconds:Number = timeZoneOffset * 60 * 1000;
       
          date.setTime(date.getTime() + currentOffsetMilliseconds);
          date.setTime(date.getTime() - newOffsetMilliseconds);
       
          time.text = date.toString();
          dispatchEvent(new Event("clockUpdated"));
      }
   
  }
}
The two things that really matter here are adding the public property and the event metadata. We also dispatch the event in updateTime, otherwise it’d never get fired. So let’s change these variables in MXML:
<?xml version="1.0" encoding="utf-8"?>
<local:SimpleDigitalClock xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:local="*"
  timeZoneOffset="480" clockUpdated="trace('blah')">

</local:SimpleDigitalClock>
Now, let’s take a look at our genned code from this example:
    //  constructor (non-Flex display object)
  /**
   * @private
   **/
  public function FrameworkLessClock()
  {
      super();
      // our style settings
      // properties

      this.timeZoneOffset = 480;
      // events
      this.addEventListener("clockUpdated", ___FrameworkLessClock_SimpleDigitalClock1_clockUpdated);
  }
  //  scripts
  //  end scripts
  //  supporting function definitions for properties, events, styles, effects

  /**
   * @private
   **/
  public function ___FrameworkLessClock_SimpleDigitalClock1_clockUpdated(event:flash.events.Event):void
  {
      trace('blah')
  }
You can see from the genned code it added the property we set as well as the event and a function for the event handler. So that’s it for now. I plan on blogging some more on this stuff, covering how to add children in MXML without the framework as well as some other cool topics. Post a comment if you have any questions or future blog posts that might be useful.

2 comments:

Gooswa said...

nice post always wanted to know how to do this.

Anonymous said...

Thanks, just what i needed.

(had to add <... width="200"> to see the whole time string)