Yahoo! Maps Web Services - ActionScript®-Flash® API Getting Started Guide

Introduction and Prerequisites

Using a CustomSWFTool in your map application allows you to create custom interactions with the map. CustomSWFTool allows you to create a map tool using the same foundation as other built in tools to the Flash API have, such as PanTool.
When using CustomSWFTool and the AS-Flash API, you are also able to use the power of Flash to create a completely custom map, especially when combined with the other powerful tools built into the API, such as CustomSWFMarker.

This tutorial will walk through how to use CustomSWFTool and also recreate the new EdgePan tool available in API 3.04, to show how it was made and how easy it is to make such tools.

To create and test applications using the Yahoo! Maps AS-Flash API, you'll need Macromedia® Flash MX 2004® or higher and a browser with Flash Player 7 or higher. You will also need to download the Yahoo! Maps MXP (Macromedia® eXtensions Package) file that will install the appropriate classes onto your machine. An application ID is required to use the AS-Flash API. You can get an application ID here.

For best results, you should launch your web pages from a web server. However, it's possible to run applications directly from your hard drive by double-clicking on them. If you run them from your hard drive, you may see a warning from the Flash Player that your application is trying to access data from a third-party server (Yahoo!). You can remove this warning by adjusting your Flash Player settings.

Displaying a Yahoo! Map using ActionScript and Flash

Once you have agreed to the terms and downloaded the Yahoo! Maps MXP file, double click on it to launch the Macromedia Extension Manager and automatically install the extension. Please make sure that you have the latest version of the Extension Manager installed. You will need to restart the Flash IDE if you have it open in order for the classes to be available. After the extension is loaded, open the Components panel and expand the Yahoo tree where you should now see com.yahoo.maps.api.flash.YahooMap. To use the component, drag com.yahoo.maps.api.flash.YahooMap from the Components panel onto the stage. Resize the component with the Transform tool or Property inspector and test your movie to see the map. To interact with the map you will need to give the component an instance name. For the examples below, myMap is the instance name.

When adding the Map component to the stage, you should specify what the map will display by default as well as enter your Yahoo! application ID. With the component selected, click on the Parameters tab in the Properties inspector. Here you can specify the starting location, default zoom level, and Yahoo! application ID for your map. The starting location can either be an address, taking advantage of our built-in geocoding, or a latitude and longitude. The zoom level can be any integer from 1 to 17. If no zoom level is specified, the map will default to a zoom level of 14 over the specified location. If no location is specified, the map will default to the center of the United States at the specified zoom level.

Making the Map Draggable using ActionScript and Flash

To make your map draggable, import the PanTool and then add it to your map. To add the PanTool to the map, wait for the map to initialize (the EVENT_INITIALIZE event) and then use the Map.addTool() method to add the PanTool to the map. The map will use the default zoom level, application ID, and location that you set in the Properties inspector for the map component.

This example uses the demonstration application ID "YD-IuIdb7M_JX_sVWlpbqn_8g--"; you cannot use this Application ID and must request one here.

import com.yahoo.maps.tools.PanTool;
import com.yahoo.maps.markers.CustomSWFMarker;
myMap.addEventListener(
  com.yahoo.maps.api.flash.YahooMap.EVENT_INITIALIZE,
  onInitMap);
function onInitMap(eventData) {
  var panTool = new PanTool();
  myMap.addTool(panTool, true);
}

Run the example above Download source

Creating the Custom Tool

The next step will be to create the tool that will control interaction with the map. Our tool will be 100% ActionScript based, and leaves the door open for your own styling and tweaks.

Built into CustomSWFTool there a number of built in functions that you can use, such as initTool, onToolEnterFrame, onToolMouseDown, onToolMouseUp, onToolMouseMove and detach.

Open a new flash document and leave the default stage size. Save the document as 'tool.fla'.
We will be placing all of our code on our 1st frame. First we need to import the Point class and create new variables to store the size and position of the map, and the position of the mouse, relative to the map.
```
import mx.graphics.Point;
var mouseXY:Object;

var myMapSize:Object;
  
```
'mouseXY' will store the mouse position relative to the map, which will be retrieved via the onToolMouseMove function later on.
'myMapSize' will be passed from the map SWF, containing the x and y position & height and width of the map.

Next, we will create new objects that will store XY points. The points stored in these objects will define the areas on the map that will allow panning- which are the edges of the map.

var map;
var scrollLeftBuffer:Object;
var scrollRightBuffer:Object;
var scrollDownBuffer:Object;
var scrollUpBuffer:Object;
var buffer:Number = 40;      //Inside
var bufferTwo:Number = 25;   //Middle
var bufferThree:Number = 15; //Outside
var edgePanStop:Number = 3;

The last four variables, buffer, bufferTwo, bufferThree and edgePanStop, define the thickness of these panning areas along the edges.

Making it work

When the map initializes the new tool, it will call the function initTool. We will create this function next, add use its event object to create a reference to the map. This reference will be used when panning the map.
```
function initTool(event:Object) {
	map = event.map;
}
```

In the map SWF, we will be creating a function that will ultimately call a function inside the tool, and pass the map size and position data to it. The next step will be to create that function.

function getMapSize(event:Object) {
	myMapSize = event;
	scrollRightBuffer = {max:myMapSize.w, min:myMapSize.w-buffer};
	scrollDownBuffer = {max:myMapSize.h, min:myMapSize.h-buffer};
	scrollLeftBuffer = {max:myMapSize.x, min:myMapSize.x+buffer};
	scrollUpBuffer = {max:myMapSize.y, min:myMapSize.y+buffer};
}

This is where we get the sizing of the map and create the scrolling areas along the edges. Please note that if the map does not fill 100% of the stage, the math here will not create these areas correctly. If so, you will need to tweak it some.
Our next step will be to track the mouse position. Built into the CustomSWFTool is a onToolMouseMove function which includes an object passed into it that tracks the mouse position relative to the tool SWF. However, we will need to get it from the map for proper functionality. We will use this function, however our mouseXY object will get the mouse position differently.
```
function onToolMouseMove(event:Object) {
       mouseXY = { x:_parent._parent._parent._xmouse,
	                y:_parent._parent._parent._ymouse  }
};
```

Directly after, our last function within the tool will be an onToolEnterFrame function. This function is another one thats built into CustomSWFTool and is fired once per frame. Here will have a large amount of code, consisting of a number of conditionals that will execute based on the position of the mouse in relation to the scroll buffers we create above.

function onToolEnterFrame(event:Object) {
	if (mouseXY.x>=scrollRightBuffer.min && mouseXY.x<=scrollRightBuffer.max) {
		if (mouseXY.x>=(myMapSize.x+myMapSize.w)-buffer && mouseXY.x<(myMapSize.x+myMapSize.w)-bufferTwo) {
			//Inside
			var delta:Point = new Point(-20, 0);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.x>(myMapSize.x+myMapSize.w)-bufferTwo && mouseXY.x<(myMapSize.x+myMapSize.w)-bufferThree) {
			//Middle
			var delta:Point = new Point(-35, 0);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.x>(myMapSize.x+myMapSize.w)-bufferThree && mouseXY.x<=((myMapSize.x+myMapSize.w)-edgePanStop)) {
			//Outside
			var delta:Point = new Point(-70, 0);
			map.setCenterByPointDelta(delta);
		}
	}
	if (mouseXY.x<=scrollLeftBuffer.min && mouseXY.x>scrollLeftBuffer.max) {
		if (mouseXY.x>=(myMapSize.x+edgePanStop) && mouseXY.xmyMapSize.x+bufferThree && mouseXY.xmyMapSize.x+bufferTwo && mouseXY.x<=myMapSize.x+buffer) {
			// Inside
			var delta:Point = new Point(20, 0);
			map.setCenterByPointDelta(delta);
		}
	}
	if (mouseXY.y=scrollUpBuffer.max) {
		if (mouseXY.y>=(myMapSize.y+edgePanStop) && mouseXY.ymyMapSize.y+bufferThree && mouseXY.ymyMapSize.y+bufferTwo && mouseXY.y<=myMapSize.y+buffer) {
			//Inside
			var delta:Point = new Point(0, 20);
			map.setCenterByPointDelta(delta);
		}
	}
	if (mouseXY.y>scrollDownBuffer.min && mouseXY.y<=scrollDownBuffer.max) {
		if (mouseXY.y<=(myMapSize.y+myMapSize.h)-bufferTwo && mouseXY.y>=(myMapSize.y+myMapSize.h)-buffer) {
			// Inside
			var delta:Point = new Point(0, -20);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.y<(myMapSize.y+myMapSize.h)-bufferThree && mouseXY.y>myMapSize.h-bufferTwo) {
			//Middle
			var delta:Point = new Point(0, -35);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.y<((myMapSize.y+myMapSize.h)-edgePanStop) && mouseXY.y>=(myMapSize.y+myMapSize.h)-bufferThree) {
			//Outside
			var delta:Point = new Point(0, -70);
			map.setCenterByPointDelta(delta);
		}
	}
}

You can now compile the tool, creating the 'tool.swf' file. Next we will go back to the map and add the tool, and pass the map size and position data to the map.

Adding the CustomSWFTool to the map

Head back to your map, and we will first be importing the CustomSWFTool, ToolBarWidget and PanTool classes. We will also create new string variables to store the URL to the tool and the icon SWFs
```
import com.yahoo.maps.tools.CustomSWFTool;
import com.yahoo.maps.tools.PanTool;
import com.yahoo.maps.widgets.ToolBarWidget;
var toolURL:String = "tool.swf";
var iconURL:String = "icon.swf";
```
We will now need to instantiate the tools and widgets we will be using.
```
var panTool = new PanTool();
var toolBar = new ToolBarWidget();
var customTool = new CustomSWFTool( toolURL, iconURL );
```
Note: A CustomSWFTool takes two parameters, the url of the tool swf and the url of the icon swf/png.
Next, we will add two event listeners, the first will listen for the initialization of the map and call the function ‘onInitMap’; and the second will be attached to CustomSWFTool and will listen for the EVENT_LOADED event and will fire off the function ‘onToolAdd’.
```
myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_INITIALIZE, onInitMap);
customTool.addEventListener(com.yahoo.maps.tools.CustomSWFTool.EVENT_LOADED, onToolAdd);
```

Our next step will be to create the function that fires on EVENT_INITIALIZE.

function onInitMap(eventData) {
	myMap.addWidget(toolBar);
	myMap.addTool(customTool, true);
	myMap.addTool(pan);
}

Because of the nature of the tool we are making, we will need pass to the tool the size and position of the map relative to the stage. We will do this after the tool has been added to the map, therefore inside the onToolAdd function that will be fired on tool load.
```
function onToolAdd(eventData) {
	tool = eventData.target.mcContainer;
	myMapSize = { x:myMap._x,
                 y:myMap._y,
                 h:myMap.map.height,
                 w:myMap.map.width };
	tool.getMapSize(myMapSize);
}
```
Next, compile the .swf and then test your map. If all has gone well, when you move your mouse to any of the edges on the map, the map will pan. The last step will be to create an icon for the ToolBarWidget. This is optional however, depending on if you included the ToolBarWidget in your map application. This icon should be a 26 x 26 pixel .swf or .png file.

Now that you have finished this tutorial, you can use CustomSWFTool to make your Flash based Yahoo! Maps even more powerful and interactive. If you have any questions or comments, you can visit the Yahoo Maps developers group (yws-maps) in Yahoo! Groups.

The finished code:

Map:

import com.yahoo.maps.tools.CustomSWFTool;
import com.yahoo.maps.tools.PanTool;
import com.yahoo.maps.widgets.ToolBarWidget;

var toolURL:String = "tool.swf";
var iconURL:String = "icon.swf";

var panTool = new PanTool();
var toolBar = new ToolBarWidget();
var customTool = new CustomSWFTool( toolURL, iconURL );

myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_INITIALIZE, onInitMap);
customTool.addEventListener(com.yahoo.maps.tools.CustomSWFTool.EVENT_LOADED, onToolAdd);

function onInitMap(eventData) {
	myMap.addWidget(toolBar);
	myMap.addTool(customTool, true);
	myMap.addTool(pan);
}

function onToolAdd(eventData) {
	tool = eventData.target.mcContainer;
	myMapSize = { x:myMap._x,
                 y:myMap._y,
                 h:myMap.map.height,
                 w:myMap.map.width };
	tool.getMapSize(myMapSize);
}

Tool:

import mx.graphics.Point;
var mouseXY:Object;
var myMapSize:Object;
var map;
var scrollLeftBuffer:Object;
var scrollRightBuffer:Object;
var scrollDownBuffer:Object;
var scrollUpBuffer:Object;
var buffer:Number = 40;
//Inside
var bufferTwo:Number = 25;
//Middle
var bufferThree:Number = 15;
//Outside
var edgePanStop:Number = 3;
function initTool(event:Object) {
	map = event.map;
}
function getMapSize(event:Object) {
	myMapSize = event;
	scrollRightBuffer = {max:myMapSize.w, min:myMapSize.w-buffer};
	scrollDownBuffer = {max:myMapSize.h, min:myMapSize.h-buffer};
	scrollLeftBuffer = {max:myMapSize.x, min:myMapSize.x+buffer};
	scrollUpBuffer = {max:myMapSize.y, min:myMapSize.y+buffer};
}
function onToolMouseMove(event:Object) {
	mouseXY = {x:_parent._parent._parent._xmouse, y:_parent._parent._parent._ymouse};
}
function onToolEnterFrame(event:Object) {
	if (mouseXY.x>=scrollRightBuffer.min && mouseXY.x<=scrollRightBuffer.max) {
		if (mouseXY.x>=(myMapSize.x+myMapSize.w)-buffer && mouseXY.x<(myMapSize.x+myMapSize.w)-bufferTwo) {
			//Inside
			var delta:Point = new Point(-20, 0);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.x>(myMapSize.x+myMapSize.w)-bufferTwo && mouseXY.x<(myMapSize.x+myMapSize.w)-bufferThree) {
			//Middle
			var delta:Point = new Point(-35, 0);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.x>(myMapSize.x+myMapSize.w)-bufferThree && mouseXY.x<=((myMapSize.x+myMapSize.w)-edgePanStop)) {
			//Outside
			var delta:Point = new Point(-70, 0);
			map.setCenterByPointDelta(delta);
		}
	}
	if (mouseXY.x<=scrollLeftBuffer.min && mouseXY.x>scrollLeftBuffer.max) {
		if (mouseXY.x>=(myMapSize.x+edgePanStop) && mouseXY.xmyMapSize.x+bufferThree && mouseXY.xmyMapSize.x+bufferTwo && mouseXY.x<=myMapSize.x+buffer) {
			// Inside
			var delta:Point = new Point(20, 0);
			map.setCenterByPointDelta(delta);
		}
	}
	if (mouseXY.y=scrollUpBuffer.max) {
		if (mouseXY.y>=(myMapSize.y+edgePanStop) && mouseXY.ymyMapSize.y+bufferThree && mouseXY.ymyMapSize.y+bufferTwo && mouseXY.y<=myMapSize.y+buffer) {
			//Inside
			var delta:Point = new Point(0, 20);
			map.setCenterByPointDelta(delta);
		}
	}
	if (mouseXY.y>scrollDownBuffer.min && mouseXY.y<=scrollDownBuffer.max) {
		if (mouseXY.y<=(myMapSize.y+myMapSize.h)-bufferTwo && mouseXY.y>=(myMapSize.y+myMapSize.h)-buffer) {
			// Inside
			var delta:Point = new Point(0, -20);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.y<(myMapSize.y+myMapSize.h)-bufferThree && mouseXY.y>myMapSize.h-bufferTwo) {
			//Middle
			var delta:Point = new Point(0, -35);
			map.setCenterByPointDelta(delta);
		}
		if (mouseXY.y<((myMapSize.y+myMapSize.h)-edgePanStop) && mouseXY.y>=(myMapSize.y+myMapSize.h)-bufferThree) {
			//Outside
			var delta:Point = new Point(0, -70);
			map.setCenterByPointDelta(delta);
		}
	}
}