Potlatch 1/Development overview/Client overview

This isn't a complete reference to everything in the Potlatch SWF, but it should give you a bit of an idea of how things fit in, where. The code is reasonably liberally commented, too.

• potlatch.as is the main code file, and most of what you'll need is in there
• gps.as loads and processes GPS tracks
• properties.as is the tag-editing code (also referred to as properties or attributes)
• tiles.as is the tiled background (under development, not currently active)
• ui.as is a set of standard code for pull-down menus, dialogue boxes and checkboxes

Movieclips

The main Potlatch movie clip is addressed _root. Within this are several movie clips. The main one is _root.map, which is the actual map. All ways and POIs are subclips of this, so when you drag the map, the ways go with it.

• _root.map.ways - way polylines
• _root.map.pois - POI nodes
• _root.map.gpx - GPX track
• _root.map.areas - area fills and way casing

These have further clips nested in them, so:

• _root.map.ways.1872 is the way with id 1872
• _root.map.pois.29876 is the way with id 29876

In ActionScript, your own objects can extend movieclips. So although _root.map is just a plain movieclip, _root.map.ways.1872 is an object of type OSMWay, which has movieclip functionality and a whole host of its own methods: see below for more. (However, since each movieclip has an overhead of about 1k, it's worth being a bit restrained in creating them!)

Other clips include:

• _root.yahoo - Yahoo layer
• _root.properties - tag editing window (again, plenty of subclips)
• _root.i_scissors, _root.i_gps etc. - buttons

It's recommended that you don't mess with _root.masksquare and the like - Flash masking (to stop the map appearing over the tag panel) is a fairly obscure art.

Some Potlatch fundamentals

• All co-ordinates in ways, POIs etc. are stored projected.
• Don't let the way that other OSM applications treat nodes confuse you: Potlatch doesn't behave like that. A point in a polyline is one thing; a stand-alone point of interest (POI) is another. Even though they're both saved as nodes in the db, they're completely different objects in Potlatch.

Classes for nodes and ways

OSMWay

A way.

Properties

• this._name - way id
• this.path - array of points
• this.attr - hash of keys and values
• this.clean - boolean: changed since last upload?
• this.uploading - boolean: currently being uploaded to server? (if yes, don't try and upload again)
• this.locked - boolean: locked? (if yes, don't upload)
• this.oldversion - previous version number if retrieved from history
• this.mergedways - list of any ways merged into this
• this.xmin, this.xmax, this.ymin, this.ymax - bounding box of way

Methods

• Server communication: this.load, this.loadFromDeleted, this.remove, this.upload, this.reload
• Drawing: this.redraw, this.select, this.highlight, this.highlightPoints
• Geometry: this.splitWay, this.mergeWay, this.addPointFrom, this.reverseWay
• Click event handlers: this.onRollOver, this.onRollOut, this.onPress
• Miscellaneous:
  • this.clearPOIs - remove any POIs from the map where that node is in this way
  • this.direction - update direction icon based on way orientation
  • this.deleteMergedWays - remove any ways from server which have been merged into this one

AnchorPoint

An AnchorPoint is the red node that you see when you have selected a way.

Properties

• this._name - position in way (0 upwards)
• this.way - id of way it belongs to (should be same as _root.wayselected)
• this.node - id of node

Methods

• Click event handlers: this.onRollOver, this.onPress
• Drag handling: this.beginDrag, this.trackDrag, this.endDrag
• Elastic band drawing: this.startElastic, this.trackElastic, this.endElastic
  • see also restartElastic(), which starts the elastic band again if it's just been ended

AnchorHint

An AnchorHint is the blue node that you see when you mouse-over another way (while drawing). Its properties are the same as an AnchorPoint. Its only methods are the click event handlers this.onRollOver, this.onRollOut, this.onPress.

POI

A POI is a stand-alone node that isn't part of a way.

Properties

• this._name - node id
• this._x, this._y - position
• this.attr - hash of keys and values
• this.clean - boolean: changed since last upload?
• this.uploading - boolean: currently being uploaded to server? (if yes, don't try and upload again)
• this.locked - boolean: locked? (if yes, don't upload)

Methods

• Server communication: this.remove, this.reload, this.upload
• Click event handlers: this.onRollOver, this.onPress
• Drag handling: this.beginDrag, this.trackDrag, this.endDrag
• this.select

General support functions

Co-ordinate conversion

(to complete)

Global variables

Potlatch makes extensive use of global variables which are initialised at the top of potlatch.as. These are all commented, but the most frequently used are:

• _root.wayselected - currently selected way id (or 0)
• _root.pointselected - currently selected point within way (or -2). Note that this is the position in the way (0 for the first, etc.), not its id.
• _root.poiselected - currently selected POI (or 0)
• _root.drawpoint - is point being drawn (elastic band)? -1 no, 0+ position within way (as per pointselected)
• _root.newwayid, _root.newnodeid, _root.newpoiid - negative IDs to assign to next newly created objects
• _root.scale - current map scale

You'll find lots of references to _root.ws throughout the code. This is a reference to _root.map.ways[_root.wayselected], i.e. the currently selected way.

Debugging

The best way to debug is to compile with the --trace option. This will enable a static text window.

You can then write debug information to this window with _root.chat.text="Debug stuff".