Just documentation in a few random places to do with styles, hitzones, layers etc.
authorSteve Bennett <stevagewp@gmail.com>
Mon, 20 Dec 2010 12:22:12 +0000 (12:22 +0000)
committerSteve Bennett <stevagewp@gmail.com>
Mon, 20 Dec 2010 12:22:12 +0000 (12:22 +0000)
net/systemeD/halcyon/EntityUI.as
net/systemeD/halcyon/MapPaint.as
net/systemeD/halcyon/VectorLayer.as
net/systemeD/halcyon/WayUI.as
net/systemeD/halcyon/styleparser/RuleSet.as
net/systemeD/halcyon/styleparser/Style.as
net/systemeD/potlatch2/controller/ControllerState.as

index 69800e0..0f12102 100644 (file)
@@ -20,7 +20,7 @@ package net.systemeD.halcyon {
                protected var sprites:Array=new Array();
                /** The clickable sprite that will receive events. */
                protected var listenSprite:Sprite=new Sprite();
-               /** Hitzone for the sprite */
+               /** Hitzone for the sprite - must be set by subclass-specific code. */
                protected var hitzone:Sprite;
                /** Special context-sensitive classes such as :hover. */
                protected var stateClasses:Object=new Object();
@@ -145,6 +145,7 @@ package net.systemeD.halcyon {
             }
                }
 
+               // What does this do, could someone please document?
                protected function setListenSprite():void {
                        var l:Sprite=paint.getHitSpriteAt(layer);
                        var s:Sprite;
index 62e0a37..412d4ea 100644 (file)
@@ -36,6 +36,15 @@ package net.systemeD.halcyon {
 
                // Set up layering
 
+               /** Creates paint sprites and hit sprites for all layers in range. This object ends up with a series of child sprites
+                * as follows: p0,p1,p2..px, h0,h1,h2..hx where p are "paint sprites" and "h" are "hit sprites". There is one of each type for each layer.
+                * <p>Each paint sprite has 4 child sprites (fill, casing, stroke, names). Each hit sprite has 2 child sprites (way hit tests, node hit tests).</p>  
+                * <p>Thus if layers range from -5 to +5, there will be 11 top level paint sprites followed by 11 top level hit sprites.</p>
+                * 
+                * @param map The map to be rendered.
+                * @param minlayer The lowest layer in that map that will be rendered.
+                * @param maxlayer The top layer in that map that will be rendered.
+                * */ 
                public function MapPaint(map:Map,minlayer:int,maxlayer:int) {
                        mouseEnabled=false;
 
@@ -71,6 +80,7 @@ package net.systemeD.halcyon {
                        return getChildAt(l-minlayer) as Sprite;
                }
 
+               /** Returns the hit sprite for the given layer. */
                public function getHitSpriteAt(l:int):Sprite {
                        return getChildAt((l-minlayer) + (maxlayer-minlayer+1)) as Sprite;
                }
@@ -286,6 +296,7 @@ package net.systemeD.halcyon {
                        delete nodeuis[oldID];
                }
 
+               /** Make a new sprite for painting on */
                private function getPaintSprite():Sprite {
                        var s:Sprite = new Sprite();
                        s.mouseEnabled = false;
index b1640d4..c301cac 100644 (file)
@@ -50,7 +50,7 @@ package net.systemeD.halcyon {
         /** Create a new node on the vector layer. Note that the node won't show up until on the map
         * until the the relevant nodeUI is created, so you will need to instruct the paint to create one
         *
-        * e.g. layer.paint.updateEntityUIs(layer.getObjectsByBbox(...)...);
+        * e.g. <code>layer.paint.updateEntityUIs(layer.getObjectsByBbox(...)...);</code>
         */
                public function createNode(tags:Object,lat:Number,lon:Number):Node {
                        var node:Node = new Node(negativeID, 0, tags, true, lat, lon);
index 1a2df69..949a857 100644 (file)
@@ -343,7 +343,7 @@ package net.systemeD.halcyon {
                                nodeStateClasses['junction']=(node.numParentWays>1);
                                paint.createNodeUI(node,r,layer,nodeStateClasses);
                        }
-                       if (!drawn) { return false; }
+                       if (!drawn) { return false; } // If not visible, no hitzone.
                        
             // create a generic "way" hitzone sprite
                        if (interactive && drawn) {
index f45ad9b..81232be 100644 (file)
@@ -11,11 +11,15 @@ package net.systemeD.halcyon.styleparser {
        import net.systemeD.halcyon.Globals;
 //     import bustin.dev.Inspector;
        
+       /** A set of rules for rendering a map, as retrieved from a MapCSS file. */
        public class RuleSet {
 
-               public var loaded:Boolean=false;                        // has it loaded yet?
-               public var images:Object=new Object();          // loaded images
-               public var imageWidths:Object=new Object();     // width of each bitmap image
+               /** Has it loaded yet? */
+               public var loaded:Boolean=false; 
+               /** Loaded images */
+               public var images:Object=new Object();
+               /** Width of each bitmap image. */
+               public var imageWidths:Object=new Object();     
                private var redrawCallback:Function=null;       // function to call when CSS loaded
                private var iconCallback:Function=null;         // function to call when all icons loaded
                private var iconsToLoad:uint=0;                         // number of icons left to load (fire iconCallback when ==0)
@@ -219,6 +223,7 @@ package net.systemeD.halcyon.styleparser {
                        yellow:0xffff00,
                        yellowgreen:0x9acd32 };
 
+               /** Constructor */
                public function RuleSet(mins:uint,maxs:uint,redrawCall:Function=null,iconLoadedCallback:Function=null):void {
                        minscale = mins;
                        maxscale = maxs;
@@ -226,7 +231,7 @@ package net.systemeD.halcyon.styleparser {
                        iconCallback = iconLoadedCallback;
                }
 
-               // Get styles for an object
+               /** Get styles for an object*/
 
                public function getStyles(obj:Entity, tags:Object, zoom:uint):StyleList {
                        var sl:StyleList=new StyleList();
@@ -239,6 +244,7 @@ package net.systemeD.halcyon.styleparser {
                // ---------------------------------------------------------------------------------------------------------
                // Loading stylesheet
 
+        /** Load ruleset the MapCSS file referenced in <code>str</code>.*/
                public function loadFromCSS(str:String):void {
                        if (str.match(/[\s\n\r\t]/)!=null) { parseCSS(str); loaded=true; redrawCallback(); return; }
 
@@ -267,7 +273,7 @@ package net.systemeD.halcyon.styleparser {
 
 
                // ------------------------------------------------------------------------------------------------
-               // Load all referenced images
+               /** Load all referenced images*/
                // ** will duplicate if referenced twice, shouldn't
                
                public function loadImages():void {
@@ -336,6 +342,7 @@ package net.systemeD.halcyon.styleparser {
                // ------------------------------------------------------------------------------------------------
                // Parse CSS
 
+               /** Parse the given MapCSS file by repeatedly throwing regular expressions at it. */
                public function parse(css:String):void {
                        var previous:uint=0;                                    // what was the previous CSS word?
                        var sc:StyleChooser=new StyleChooser(); // currently being assembled
@@ -467,7 +474,7 @@ package net.systemeD.halcyon.styleparser {
                        ss.sublayer=ps.sublayer=ts.sublayer=hs.sublayer=sub;
                        xs.sublayer=10;
                        
-                       // Find interactive
+                       // Find "interactive" property - it's true unless explicitly set false.
                        var inter:Boolean=true;
                        if (t['interactive']) { inter=t['interactive'].match(FALSE) ? false : true; delete t['interactive']; }
                        ss.interactive=ps.interactive=ts.interactive=hs.interactive=xs.interactive=inter;
@@ -533,6 +540,8 @@ package net.systemeD.halcyon.styleparser {
                        return null;
                }
 
+        /** Convert a color string given as either descriptive ("blue"), short hex ("#abc") or long hex ("#a0b0c0"), to an integer. 
+        * @default 0*/
         public static function parseCSSColor(colorStr:String):uint {
             colorStr = colorStr.toLowerCase();
             if (CSSCOLORS[colorStr]) {
index 8f8e22e..c02ba3b 100644 (file)
@@ -5,14 +5,17 @@ package net.systemeD.halcyon.styleparser {
 
        public class Style {
 
+               /** Has this style had another style merged into it? */
                public var merged:Boolean=false;
-               public var edited:Boolean=false;                // true once a property has been set from a string
+               /** true once a property has been set from a string */
+               public var edited:Boolean=false;
+               /** Z-index */
                public var sublayer:Number=5;
+               /** Should entities with this style respond to interaction like mouse movement? */
                public var interactive:Boolean=true;    
-               public var evals:Object={};                             // compiled SWFs for each eval. We keep it here, not in the property 
-                                                                                               //  | itself, so that we can retain typing for each property
-
-               // Return an exact copy of this object
+               /** Compiled SWFs for each eval. We keep it here, not in the property itself, so that we can retain typing for each property */
+               public var evals:Object={};
+               /** Return an exact copy of this object */
                // ** this needs some benchmarking - may be quicker to iterate over .properties, copying each one
 
                public function deepCopy():* {
@@ -27,7 +30,7 @@ package net.systemeD.halcyon.styleparser {
                        return (a.readObject());
                }
 
-               // Add properties from another object
+               /** Add properties from another object */
 
                public function mergeWith(additional:Style):void {
                        for each (var prop:String in properties) {
@@ -38,34 +41,35 @@ package net.systemeD.halcyon.styleparser {
                        this.merged=true;
                }
 
-               // Getters (to be overridden)
+               /** Getters (to be overridden) */
 
                public function get properties():Array {
                        return [];
                }
                
+               /** Does this style require anything to be drawn? (To be overridden.) */
                public function get drawn():Boolean {
                        return false;
                }
                
-               // Eval handling
-               
+               /** Are there any eval functions defined? */
                public function hasEvals():Boolean {
                        for (var k:String in evals) { return true; }
                        return false;
                }
                
+               /** If the stylesheet has width=eval('_width+2'), then this will set Style.width to 7 (say). */
                public function runEvals(tags:Object):void {
                        for (var k:String in evals) {
                                // ** Do we need to do typing here?
                                this[k]=evals[k].exec(tags);
                                
-                               // ** If the stylesheet has width=eval('_width+2'), then this will set Style.width to 7 (say).
+                               
                                //    
                        }
                }
 
-               // Set property and cast as correct type (used in stylesheet imports)
+               /** Set property and cast as correct type (used in stylesheet imports)*/
                
                public function setPropertyFromString(k:String,v:*):Boolean {
                        if (!this.hasOwnProperty(k)) { return false; }
@@ -92,6 +96,7 @@ package net.systemeD.halcyon.styleparser {
                        return false;
                }
 
+               /** Serialise properties to a string. */
                public function toString():String {
                        var str:String='';
             for each (var k:String in this.properties) {
index 369bbe5..da6be41 100644 (file)
@@ -149,6 +149,7 @@ package net.systemeD.potlatch2.controller {
                        }
                }
 
+               /** Find the MapPaint object that this DisplayObject belongs to. */
                protected function getMapPaint(d:DisplayObject):MapPaint {
                        while (d) {
                                if (d is MapPaint) { return MapPaint(d); }