More styleparser documentation.
authorRichard Fairhurst <richard@systemed.net>
Sun, 30 Jan 2011 14:23:37 +0000 (14:23 +0000)
committerRichard Fairhurst <richard@systemed.net>
Sun, 30 Jan 2011 14:23:37 +0000 (14:23 +0000)
net/systemeD/halcyon/styleparser/Rule.as
net/systemeD/halcyon/styleparser/RuleSet.as
net/systemeD/halcyon/styleparser/Style.as
net/systemeD/halcyon/styleparser/StyleList.as

index fb92a5a811e79b81dabc73fa9d5253b11bc84e7b..1a1d53adeb7d160b7085c69a7ac64f06ee9b9ec7 100644 (file)
@@ -2,7 +2,7 @@ package net.systemeD.halcyon.styleparser {
 
     import net.systemeD.halcyon.connection.*;
 
-       /**     A MapCSS selector. Contains a list of Conditions, the entity type to which the selector applies, 
+       /**     A MapCSS selector. Contains a list of Conditions; the entity type to which the selector applies; 
                and the zoom levels at which it is true. way[waterway=river][boat=yes] would be parsed into one Rule. <p>
                
                The selectors and declaration together form a StyleChooser.                                                                                       </p>
index 74e72e69de3ed3cf239e7fb9f51473a194e95f5d..650506226ee3f94f4b3e79da0fee83f202b76d4f 100644 (file)
@@ -11,10 +11,11 @@ package net.systemeD.halcyon.styleparser {
        import net.systemeD.halcyon.Globals;
        
        /** A complete stylesheet, as loaded from a MapCSS file. It contains all selectors, declarations, 
-               and embedded images are contained.                                                                                                                                              </p><p>
+               and embedded images.                                                                                                                                                            </p><p>
                
-               The RuleSet class contains the main getStyles method for finding the styles to apply to an entity,
-               plus the MapCSS parser. */
+               The RuleSet class has two principal methods: getStyles, which calculates the styles that apply
+               to an entity (returned as a StyleList); and parse, which parses a MapCSS stylesheet into
+               a complete RuleSet. */
 
        public class RuleSet {
 
@@ -228,6 +229,7 @@ package net.systemeD.halcyon.styleparser {
                        yellowgreen:0x9acd32 };
 
                /** Constructor */
+
                public function RuleSet(mins:uint,maxs:uint,redrawCall:Function=null,iconLoadedCallback:Function=null):void {
                        minscale = mins;
                        maxscale = maxs;
@@ -235,7 +237,8 @@ package net.systemeD.halcyon.styleparser {
                        iconCallback = iconLoadedCallback;
                }
 
-               /** Get styles for an object*/
+               /** Create a StyleList for an Entity, by creating a blank StyleList, then running each StyleChooser over it.
+                       @see net.systemeD.halcyon.styleparser.StyleList */
 
                public function getStyles(obj:Entity, tags:Object, zoom:uint):StyleList {
                        var sl:StyleList=new StyleList();
@@ -276,7 +279,7 @@ package net.systemeD.halcyon.styleparser {
                /** Load all images referenced in the RuleSet (for example, icons or bitmap fills).
                        FIXME: if an image is referenced twice, it'll be requested twice. */
                
-               public function loadImages():void {
+               private function loadImages():void {
                        var filename:String;
                        for each (var chooser:StyleChooser in choosers) {
                                for each (var style:Style in chooser.styles) {
index c02ba3b82e10bee98c9eb1e11e32894e2356f77b..3397936948ecfeb108e5eba65d6dd8d33989341d 100644 (file)
@@ -3,21 +3,40 @@ package net.systemeD.halcyon.styleparser {
        import flash.utils.ByteArray;
        import flash.net.*;
 
+       /** A Style is a set of graphic properties (e.g. stroke colour and width, casing colour and width, 
+               font and text size), typically derived from a MapCSS descriptor. This is the base class
+               for particular style groupings such as ShapeStyle and PointStyle.
+               
+               @see net.systemeD.halcyon.styleparser.StyleList
+               @see net.systemeD.halcyon.styleparser.StyleChooser
+       */
+
        public class Style {
 
-               /** Has this style had another style merged into it? */
+               /** Has this style had another style merged into it?
+                       (When styles cascade, then we need to merge the first style with any subsequent styles that apply.) */
                public var merged:Boolean=false;
-               /** true once a property has been set from a string */
+
+               /** Is the style active (properties have been set)? */
                public var edited:Boolean=false;
-               /** Z-index */
+
+               /** The sublayer is the z-index property _within_ an OSM layer.
+                       It enables (for example) trunk roads to be rendered above primary roads within that OSM layer, 
+                       and so on. "OSM layer 1 / sublayer 5" will render above "OSM layer 1 / sublayer 4", but below 
+                       "OSM layer 2 / sublayer 4". */
                public var sublayer:Number=5;
-               /** Should entities with this style respond to interaction like mouse movement? */
+
+               /** Does this style permit mouse interaction?
+                       (Some styling, such as P2's back-level yellow highlight for selected ways, should not respond 
+                       to mouse events.) */
                public var interactive:Boolean=true;    
-               /** 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
 
+               /** 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={};
+               
+               /** Make an exact copy of an object.
+                       Used when merging cascading styles. (FIXME: this needs some benchmarking - it may be quicker to simply iterate over .properties, 
+                       copying each one. */
                public function deepCopy():* {
                        registerClassAlias("net.systemeD.halcyon.styleparser.ShapeStyle",ShapeStyle);
                        registerClassAlias("net.systemeD.halcyon.styleparser.TextStyle",TextStyle);
@@ -30,8 +49,7 @@ package net.systemeD.halcyon.styleparser {
                        return (a.readObject());
                }
 
-               /** Add properties from another object */
-
+               /** Merge two Style objects. */
                public function mergeWith(additional:Style):void {
                        for each (var prop:String in properties) {
                                if (additional[prop]) {
@@ -41,8 +59,7 @@ package net.systemeD.halcyon.styleparser {
                        this.merged=true;
                }
 
-               /** Getters (to be overridden) */
-
+               /** Properties getter, to be overridden. */
                public function get properties():Array {
                        return [];
                }
@@ -58,19 +75,16 @@ package net.systemeD.halcyon.styleparser {
                        return false;
                }
                
-               /** If the stylesheet has width=eval('_width+2'), then this will set Style.width to 7 (say). */
+               /** Run all evals for this Style over the supplied tags.
+                       If, for example, the stylesheet contains width=eval('_width+2'), then this will set Style.width to 7. */
                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);
-                               
-                               
-                               //    
                        }
                }
 
-               /** Set property and cast as correct type (used in stylesheet imports)*/
-               
+               /** Set a property, casting as correct type. */
                public function setPropertyFromString(k:String,v:*):Boolean {
                        if (!this.hasOwnProperty(k)) { return false; }
                        if (v is Eval) { evals[k]=v; v=1; }
@@ -96,7 +110,7 @@ package net.systemeD.halcyon.styleparser {
                        return false;
                }
 
-               /** Serialise properties to a string. */
+               /** Summarise Style as String - for debugging. */
                public function toString():String {
                        var str:String='';
             for each (var k:String in this.properties) {
index 7b4435e987a4435e488c6410674d26b8e52e3d2d..c2fd02bd9290646058d0a9d7ce9a73eaf27f1fed 100644 (file)
@@ -1,11 +1,14 @@
 package net.systemeD.halcyon.styleparser {
 
-    /**
-    * A StyleList object is the full list of all styles applied to
-    * a drawn entity (i.e. node/way).
-    *
-    * Each array element applies to that sublayer (z-index). If there
-    * is no element, nothing is drawn on that sublayer.
+    /**        A StyleList object is the full list of all styles applied to
+               a drawn entity (i.e. node/way).                                                                                                 <p>
+
+               Each array element applies to that sublayer (z-index). If there
+               is no element, nothing is drawn on that sublayer.                                                               </p><p>
+               
+               StyleLists are created by StyleChooser.getStyles.                                                               </p>
+               
+               @see net.systemeD.halcyon.styleparser.StyleChooser
     */
 
        public class StyleList {
@@ -15,16 +18,20 @@ package net.systemeD.halcyon.styleparser {
                public var pointStyles:Object={};
                public var shieldStyles:Object={};
                public var maxwidth:Number=0;
+
+               /** List of sublayers used in this StyleList. */
                public var sublayers:Array=[];
-        /**
-        * zoom level at which this StyleList is valid, or -1 for all
-        */
+
+        /** Zoom level this StyleList is valid at. If -1, valid at all styles (i.e. doesn't need to be recomputed
+                       on zoom in/out); otherwise, specifies a single zoom level. */
                public var validAt:int=-1;
 
+               /** Does this StyleList contain any styles? */
                public function hasStyles():Boolean {
                        return ( hasShapeStyles() || hasTextStyles() || hasPointStyles() || hasShieldStyles() );
                }
 
+               /** Does this StyleList contain any styles with a fill? */
                public function hasFills():Boolean {
                        for each (var ss:ShapeStyle in shapeStyles) {
                                if (!isNaN(ss.fill_color) || ss.fill_image) return true;
@@ -32,6 +39,7 @@ package net.systemeD.halcyon.styleparser {
                        return false;
                }
 
+               /** Does this StyleList manually force an OSM layer? */
                public function layerOverride():Number {
                        for each (var ss:ShapeStyle in shapeStyles) {
                                if (ss['layer']) return ss['layer'];
@@ -39,10 +47,12 @@ package net.systemeD.halcyon.styleparser {
                        return NaN;
                }
                
+               /** Record that a sublayer is used in this StyleList. */
                public function addSublayer(s:Number):void {
                        if (sublayers.indexOf(s)==-1) { sublayers.push(s); }
                }
 
+               /** Summarise StyleList as String - for debugging. */
                public function toString():String {
                        var str:String='';
                        var k:String;
@@ -53,6 +63,7 @@ package net.systemeD.halcyon.styleparser {
                        return str;
                }
 
+               /** Is this StyleList valid at a given zoom? */
                public function isValidAt(zoom:uint):Boolean {
                        return (validAt==-1 || validAt==zoom);
                }