This article assumes you already have the Flex 3 SDK and FlashDevelop 3 installed and working. See my post from two years ago for help.

Compilation Options

There are two ways OpenScales can be compiled. Firstly the source code can be included with your application code. This approach is good for debugging OpenScales and learning how it works. My understanding of the OpenScales LGPL license is that this will make your application also licensed as LGPL (or a compatible license). However I’m not a lawyer so if that aspect is important to you then you will need to take a closer look.

The second way to compile OpenScales is as a library (SWC file). This library can then be linked with your application to produce the final Flash file.

Compiling OpenScales Into a Library

1. Download and install the ExportSWC plugin for Flash Develop.

2. Create a new Flex 3 project with no package name.

3. Check out OpenScales using Subversion into the folder above the project folder. Note that if you use a different location the paths in the rest of this tutorial will need to be adjusted accordingly. I recommend TortoiseSVN if using Windows.

4. Go to Project -> Properties -> Compiler Options. Click on the Additional Compiler Options field and then the small “…” button.

5. Enter:

-namespace http://openscales.org ..\OpenScales-1.1\src\openscales-fx\src\main\flex\META-INF\manifest.xml

Note the hyphen at the start of the line.

6. Click on the Classpaths tab and add the following Classpaths:

..\OpenScales-1.1\src\openscales-core\src\main\flex
..\OpenScales-1.1\src\openscales-fx\src\main\flex
..\OpenScales-1.1\src\openscales-proj4as\src\main\flex
C:\Program Files\FlexSDK\frameworks\libs
C:\Program Files\FlexSDK\frameworks\locale\en_US

then close the dialog window. Note if you copied the Flex 3 SDK to a different location then choose the correct location when adding the libs and locale classpaths.

7. Download GTween, extract the zip file and copy GTween_xx_xx.swc into the lib folder for the project.

8. In the Project tree view right click on the GTween SWC file and choose “Add To Library”. The name will turn blue.

9. In the Project tree expand “libs” and “locale”, right-click on each SWC file in turn and choose “Add To Library”. The names will turn blue.

10. Click on the Build SWC toolbar button to generate the SWC file.

You may get two warnings for the OverviewMap.mxml file, which causes the build to fail. I think this is a bug in FlashDevelop because warnings shouldn’t cause the build to fail, only errors should. However the warnings can be disabled in the compiler options. I don’t know for sure if the Overview Map control is usable because of this.

The generated SWC file will be in the bin subfolder. In FlashDevelop create a new Flex 3 project and copy the OpenScales SWC file into the lib folder, then add it to the library by right-clicking on the name in the Project tree and choosing “Add To Library”. OpenScales can now be used.

Compiling Application Code With OpenScales Code

1. Create a new Flex 3 project with a suitable package name.

2. Check out OpenScales using Subversion into the folder above the project folder. Note that if you use a different location the paths in the rest of this tutorial will need to be adjusted accordingly. I recommend TortoiseSVN if using Windows.

3. Go to Project -> Properties -> Compiler Options. Click on the Additional Compiler Options field and then the small “…” button.

4. Enter:

-namespace http://openscales.org ..\OpenScales-1.1\src\openscales-fx\src\main\flex\META-INF\manifest.xml

Note the hyphen at the start of the line.

5. Click on the Classpaths tab and add the following Classpaths:

..\OpenScales-1.1\src\openscales-core\src\main\flex
..\OpenScales-1.1\src\openscales-fx\src\main\flex
..\OpenScales-1.1\src\openscales-proj4as\src\main\flex


then close the dialog window.

6. Download GTween, extract the zip file and copy GTween_xx_xx.swc into the lib folder for the project.

7. In the Project tree view right click on the GTween SWC file and choose “Add To Library”. The name will turn blue.

Now you can add OpenScales controls to Main.mxml and build a Flex/ActionScript 3 project.

It is possible to add the GTween source code to the project instead of the SWC if needed.

You may get two warnings for the OverviewMap.mxml file, which causes the build to fail. I think this is a bug in FlashDevelop because warnings shouldn’t cause the build to fail, only errors should. However the warnings can be disabled in the compiler options. I don’t know for sure if the Overview Map control is usable because of this.

For completeness my MXML and ActionScript test code follows. Note that I avoided using MXML to create any controls, instead preferring to use ActionScript. This is just a personal preference.

Example Main.mxml file:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:os="http://openscales.org" layout="horizontal" horizontalAlign="left"
backgroundColor="#FFFFFF" backgroundGradientColors="[#FFFFFF, #FFFFFF]"
paddingTop="0" paddingLeft="0" paddingRight="0" paddingBottom="0"
creationComplete="OSMap.main();">
</mx:Application>

Example OSMap.as file:

package com.britishideas
{
  import mx.controls.*;
  import mx.core.*;
  import mx.events.FlexEvent;
  import flash.events.*;
  import flash.utils.*;
  import flash.display.Sprite;
  import org.openscales.fx.FxMap;
  import org.openscales.core.Map;
  import org.openscales.core.layer.osm.Mapnik;
  import org.openscales.core.handler.mouse.DragHandler;
  import org.openscales.core.handler.mouse.WheelHandler;
  import org.openscales.core.control.PanZoomBar;

  public class OSMap
  {
    private static var map:FxMap;
    private static var mxmlApp:Application;
    private static var osmap:Map;

    public function OSMap()
    {
    }

    public static function main():void
    {
      mxmlApp = Application(Application.application);
      map = new FxMap();
      map.width = 840;
      map.height = 840;
      map.zoom = 10;
      mxmlApp.addChild(map);
      map.addEventListener(FlexEvent.CREATION_COMPLETE, MapCreated);
    }

    private static function MapCreated(e:FlexEvent):void
    {
      osmap = map.map;
      var MapnikLayer:Mapnik = new Mapnik("Mapnik", true);
      osmap.addLayer(MapnikLayer);
      var dragHandler:DragHandler = new DragHandler(osmap, true);
      var wheelHandler:WheelHandler = new WheelHandler(osmap, true);
      osmap.zoom = 10;
      osmap.addControl(new PanZoomBar());
    }
  }
}

I noticed that the getting started tutorials on the Adobe website are aimed at people who have purchased the Flash Builder package, so skip over some of the important details required for using the free Flex 3 SDK. This post is an adaptation of Getting Started With Flex Development And Why Its Worth Learning.

• Download the Flex 3 SDK from Here.
• Extract the contents of the ZIP file to somewhere like C:\Program Files\Flex3SDK
• Add C:\Program Files\Flex3SDK\bin to the PATH variable (Control Panel -> System -> Advanced -> Enironment Variables)
• Install the debug version of the Flash player from C:\Program Files\Flex3SDK\runtimes\player

Next we need to get FlashDevelop, which is a great, and free, IDE for Flash Development.

• Download FlashDevelop from here
• Install
• Go to Tools -> Program Settings -> AS3Context
• For the setting “Flex SDK Location” specify C:\Program Files\Flex3SDK
• Click on “Close”

Now you can follow the rest of the short tutorial at Getting Started With Flex Development And Why Its Worth Learning starting with the point where a new ActionScript file is created. Within minutes you will have your first flash script built with debug output!