Developing Widgets for Chumby: Haxe

Introduction

This is a very basic tutorial on building a simple widget for a chumby device using the Haxe language. At some point I will follow this up with some additional tutorials that cover using Haxe without FlashDevelop (Haxe is cross-platform and runs on Macs and Linux while FlashDevelop is not), using chumby parameters, FLA and other vector resources, and generally more advanced stuff. This is just to get people started. It isn't intended to act as a tutorial on how to code in general, it is assumed you know the basics. For specifics on the Haxe language and API, see the Haxe documentation at http://haxe.org/documentation

This post and related images are released under the terms of CC0 1.0 Universal (CC0 1.0) Public Domain Dedication. Please feel free to use it for any purpose and link to it from the chumby wiki and/or cut and paste it into the wiki for posterity.

Download FlashDevelop

Go to http://www.flashdevelop.org/ and download the latest version of FlashDevelop. As of this writing the latest available version is 4.6.2. It is easier to use the self-installing "Setup" version rather than the zip version. Download this executable using your browser and execute it to install.

Upon first installing and running FlashDevelop you should be presented with an "AppMan" dialog box similar to the one seen below. If you miss it on your first run you can bring it up within FlashDevelop by selecting the "Tools/Install Software..." menu item.

Select the checkbox for the option corresponding to Haxe 3 under the "Other" category and the option corresponding to "AS2 Templates" under the Extensions category.

Click the install items button in the lower right corner of the dialog to actually install your selected items. If everything goes as planned you'll now have a local install of Haxe 3 and Haxe AS2 project templates for FlashDevelop.

Create a Project

Go to the "Project/New Project..." menu. A dialog box of project options should open up (see example below), select the "AS2 Project" option under the second Haxe category (you'll probably have to scroll down to see this second Haxe category; I don't know why FlashDevelop doesn't put this option into the existing Haxe category).

Give your project a name (I used "dumbclock") and select a location for it on disk. I recommend using the "Create directory for project" option to cleanly separate this project into its own directory, which is very useful if you plan to have multiple widget projects later on. Select "OK". If this is your first ever FlashDevelop project, FlashDevelop will ask you for your name (to insert into the comment documentation blocks it autogenerates), enter your name and continue. Once past this, FlashDevelop should have set up a very basic project structure for you with 'bin' and 'src' directories and a Main.hx file in the 'src' directory. You can navigate through this project using the Project panel (which by default will dock on the right of your FlashDevelop IDE window, though you can move it).

Build the Project

Select the "Project/Build Project" menu item. You should see output in the Output panel (docks on the bottom area of the FlashDevelop IDE by default) that looks like what is seen in the screenshot below. If you don't get a successful build at this stage, there is likely something screwed up with your local Haxe installation or FlashDevelop and you may be able to get help fixing the issue either on either the FlashDevelop or Chumby Development/Widgets forums.

Executing the Flash SWF Locally

Assuming the project built successfully, you should now have a file named "dumbclock.swf" within the bin directory of your project (if you named the project something other than dumbclock, the SWF will match what your project name is). Try double clicking this file within the Project navigation panel of FlashDevelop. If you have a local install of the Adobe Flash Player (generally a Flash Player will already be installed on your system if you have a modern Windows install), you'll get an empty window that looks similar to the screenshot below. If you don't have Adobe Flash Player installed at all you will probably get a Windows dialog asking what you want to use to open the file. In this case, cancel out of that dialog and install an Adobe Flash Player via Adobe's site at http://get.adobe.com/flashplayer/

Adding Some Logic

The widget as it currently exists isn't too exciting, it does nothing but show a blank window. We can change this by adding a TextField programatically in the main function of the Main class. Modify the Main.hx file inside your 'src' directory so that the listing reads as follows:

 package ;
 
 import flash.Lib;
 import flash.Stage;
 import flash.TextFormat;
 
 class Main {
 	inline static var textSize = 72;
 	
 	static function main() {
 		var tf = Lib._root.createTextField("tf", 0, 0, 0, Stage.width, 0);
 		tf.text = "dumbclock is dumb";
 		tf.autoSize = "center";
 		
 		var format:TextFormat = new TextFormat();
 		format.size = textSize;
 		
 		tf._y = (Stage.height / 2 - textSize);
 		tf.setTextFormat(format);
 	}	
 }

Now select the "Project/Test Project" menu (or press F5) to re-execute the widget and you should see a window that looks like the screenshot below:

This widget still isn't particularly interesting as all it does is display "dumbclock is dumb" which is self-evident and not useful information. To actually make this a clock we will add an onEnterFrame listener and pull the time from the system clock. Modify the Main class so this listing looks like this:

 package ;
 
 import flash.Lib;
 import flash.Stage;
 import flash.TextFormat;
 
 class Main {
 	inline static var textSize = 72;
 	
 	static function main() {
 		var tf = Lib._root.createTextField("tf", 0, 0, 0, Stage.width, 0);
 		tf.autoSize = "center";
 		
 		var format:TextFormat = new TextFormat();
 		format.size = textSize;
 		
 		tf._y = (Stage.height / 2 - textSize);
 		tf.setTextFormat(format);
 		
 		// add an onEnterFrame event handler to Lib._root
 		Lib._root.onEnterFrame = function() {
 			// uses strftime formatting, see http://www.cplusplus.com/reference/ctime/strftime/
 			tf.text = DateTools.format(Date.now(), "%r");
 			tf.setTextFormat(format);
 		}
 	}	
 }

Again select the "Project/Test Project" menu (or press F5) to re-execute the widget and you should see a window that looks like the screenshot below.

Yay, we now have a usable (if somewhat dumb) clock!

You should now be able to upload the dumbclock.swf file to the chumby web server (login, go to apps->submit an app, fill out the form), assign it to a channel and see it running on an actual chumby device.