Start work on Halcyon styleparser documentation
authorRichard Fairhurst <richard@systemed.net>
Sat, 29 Jan 2011 20:01:16 +0000 (20:01 +0000)
committerRichard Fairhurst <richard@systemed.net>
Sat, 29 Jan 2011 20:01:16 +0000 (20:01 +0000)
net/systemeD/halcyon/EntityUI.as
net/systemeD/halcyon/styleparser/Condition.as
net/systemeD/halcyon/styleparser/NestedCSSLoader.as
net/systemeD/halcyon/styleparser/Rule.as
net/systemeD/halcyon/styleparser/RuleSet.as

index 7fddf783b4ae9be739a4efb4960bf5b285f36c75..5d3f2387ed8a49777aca2124b71047e090f2cbac 100644 (file)
@@ -6,7 +6,6 @@ package net.systemeD.halcyon {
        import flash.text.GridFitType;
        import net.systemeD.halcyon.Globals;
        import net.systemeD.halcyon.styleparser.StyleList;
-       import net.systemeD.halcyon.styleparser.RuleSet;
     import net.systemeD.halcyon.connection.*;
 
        /** Parent class of representations of map Entities, with properties about how they should be drawn. */ 
@@ -34,8 +33,6 @@ package net.systemeD.halcyon {
                protected var clearLimit:uint=0;
                /** Reference to parent MapPaint */
                public var paint:MapPaint;      
-               /** Reference to ruleset (MapCSS) in operation */
-               public var ruleset:RuleSet;
                /** Does object respond to clicks? */
                public var interactive:Boolean=true;
                /** Can it be deleted when offscreen? */
index 6ac993687a07b9f9a00eacdfc8cbff6b04e6fa30..b849562c973f7b285c5d60da7da42f598f56d5a1 100644 (file)
@@ -1,23 +1,33 @@
 package net.systemeD.halcyon.styleparser {
 
-       // valid conditions:
-       // _type_       _params_
-       // regex        key, regex
-       // eq           key, value
+       /**     A single tag test that forms part of a MapCSS selector.
+               For example, "highway==primary" or "population>1000".
+               Conditions are grouped in Rules.
+               
+               @see net.systemeD.halcyon.styleparser.Rule */
 
        public class Condition {
-               public var type:String;         // eq, regex, lt, gt etc.
-               public var params:Array;        // e.g. ('highway','primary')
-               
-               // ------------------------------------------------------------------------------------------
-               // Constructor function
+               public var type:String;
+               public var params:Array;
+
+               /** Create a new Condition.                                                                                                             <p>
+                 
+                       Valid types:                                                                                                                    </p><p>
+                       eq,'highway','trunk'            - simple equality test                                          </p><p>
+                       ne,'highway','trunk'            - not equals                                                            </p><p>
+                       regex,'highway','trunk.+'       - regular expression                                            </p><p>
+                       true,'bridge'                           - value is true/yes/1                                           </p><p>
+                       untrue,'bridge'                         - value is not true/yes/1                                       </p><p>
+                       set,'highway'                           - tag exists and is not ''                                      </p><p>
+                       unset,'highway'                         - tag does not exist, or is ''                          </p><p>
+                       <,'population','5000'           - numeric comparison (also <=, >, >=)           </p>
+                */
                
-               public function Condition(t:String='', ...a) {
-                       type=t; params=a;
+               public function Condition(type:String='', ...params) {
+                       this.type=type; this.params=params;
                }
                
-               // ------------------------------------------------------------------------------------------
-               // Test a hash against this condition
+               /** Test a tag hash against the Condition. */
 
                public function test(tags:Object):Boolean {
                        switch (type) {
index d088f63cb18cb852d3ae09be59f5faa0b261b437..b03f1b381de5fe3f29082a8e975cc397020986d8 100644 (file)
@@ -1,22 +1,22 @@
 package net.systemeD.halcyon.styleparser {
 
-       /** A class permitting you to load CSS files containing '@import' rules, which will be 
-       *       automatically replaced with the contents of the file.
-       *
-       *   Typical usage:
-       *
-       *               cssLoader=new NestedCSSLoader();
-       *               cssLoader.addEventListener(Event.COMPLETE, doParseCSS);
-       *               cssLoader.load("potlatch.css");
-       *
-       *       doParseCSS can then access the CSS via event.target.css.
-       */
-
        import flash.events.*;
        import flash.net.URLLoader;
        import flash.net.URLLoaderDataFormat;
        import flash.net.URLRequest;
 
+       /** A class permitting you to load CSS files containing 'import' rules, which will be 
+               automatically replaced with the contents of the file.                                                                   <p>
+       
+               Typical usage:                                                                                                                                                  </p><pre>
+       
+                       cssLoader=new NestedCSSLoader();
+                       cssLoader.addEventListener(Event.COMPLETE, doParseCSS);
+                       cssLoader.load("potlatch.css");                                                                                                         </pre><p>
+       
+               doParseCSS can then access the CSS via event.target.css.                                                                </p>
+       */
+
        public class NestedCSSLoader extends EventDispatcher {
                private var sourceCSS:String;
                public var css:String;
index 08da544f7cc65ed2dc25ae1dddcce04deef665ac..fb92a5a811e79b81dabc73fa9d5253b11bc84e7b 100644 (file)
@@ -2,20 +2,36 @@ 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, 
+               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>
+               
+               @see net.systemeD.halcyon.styleparser.Condition
+               @see net.systemeD.halcyon.styleparser.StyleChooser */
+
        public class Rule {
 
+               /** The Conditions to be evaluated for the Rule to be fulfilled. */
                public var conditions:Array = [];
+               /** Do all Conditions need to be true for the Rule to be fulfilled? (Always =true for MapCSS.) */
                public var isAnd:Boolean = true;
+               /** Minimum zoom level at which the Rule is fulfilled. */
                public var minZoom:uint = 0;
+               /** Maximum zoom level at which the Rule is fulfilled. */
                public var maxZoom:uint = 255;
-               public var subject:String='';                   // "", "way", "area", "line", "node" or "relation"
+               /** Entity type to which the Rule applies. Can be 'way', 'node', 'relation', 'area' (closed way) or 'line' (unclosed way). */
+               public var subject:String='';
                
-               public function Rule(s:String=''):void {
-                       subject=s;
+               public function Rule(subject:String=''):void {
+                       this.subject=subject;
                }
                
-               public function test(obj:Entity,tags:Object,zoom:uint):Boolean {
-                       if (subject!='' && !obj.isType(subject)) { return false; }
+               /** Evaluate the Rule on the given entity, tags and zoom level.
+                       @return True if the Rule passes, false if the conditions aren't fulfilled. */
+
+               public function test(entity:Entity,tags:Object,zoom:uint):Boolean {
+                       if (subject!='' && !entity.isType(subject)) { return false; }
                        if (zoom<minZoom || zoom>maxZoom) { return false; }
                        
                        var v:Boolean=true; var i:uint=0;
index f66609b70c647a2df1f3edbf78107ee4b88bcdc5..74e72e69de3ed3cf239e7fb9f51473a194e95f5d 100644 (file)
@@ -9,16 +9,20 @@ package net.systemeD.halcyon.styleparser {
 
     import net.systemeD.halcyon.connection.*;
        import net.systemeD.halcyon.Globals;
-//     import bustin.dev.Inspector;
        
-       /** A set of rules for rendering a map, as retrieved from a MapCSS file. */
+       /** A complete stylesheet, as loaded from a MapCSS file. It contains all selectors, declarations, 
+               and embedded images are contained.                                                                                                                                              </p><p>
+               
+               The RuleSet class contains the main getStyles method for finding the styles to apply to an entity,
+               plus the MapCSS parser. */
+
        public class RuleSet {
 
-               /** Has it loaded yet? */
+               /** Is the RuleSet fully loaded and available for use? */
                public var loaded:Boolean=false; 
-               /** Loaded images */
+               /** Hash of loaded images. Hash key is filename, value is BitmapData for the image. */
                public var images:Object=new Object();
-               /** Width of each bitmap image. */
+               /** Hash of image widths. Hash key is filename, value is pixel width. */
                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
@@ -244,7 +248,10 @@ package net.systemeD.halcyon.styleparser {
                // ---------------------------------------------------------------------------------------------------------
                // Loading stylesheet
 
-        /** Load ruleset the MapCSS file referenced in <code>str</code>.*/
+        /** Load and then parse a MapCSS stylesheet. Usually you will supply a filename, but you can also pass 
+                       a complete stylesheet in the string parameter. (Any string containing space characters will be 
+                       assumed to be a stylesheet rather than a filename.) */
+
                public function loadFromCSS(str:String):void {
                        if (str.match(/[\s\n\r\t]/)!=null) { parseCSS(str); loaded=true; redrawCallback(); return; }
 
@@ -265,9 +272,9 @@ package net.systemeD.halcyon.styleparser {
                }
 
 
-               // ------------------------------------------------------------------------------------------------
-               /** Load all referenced images*/
-               // ** will duplicate if referenced twice, shouldn't
+               /// ------------------------------------------------------------------------------------------------
+               /** 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 {
                        var filename:String;
@@ -284,8 +291,8 @@ package net.systemeD.halcyon.styleparser {
                                        var loader:ExtendedURLLoader=new ExtendedURLLoader();
                                        loader.dataFormat=URLLoaderDataFormat.BINARY;
                                        loader.info['filename']=filename;
-                                       loader.addEventListener(Event.COMPLETE,                                         loadedImage,                    false, 0, true);
-                                       loader.addEventListener(HTTPStatusEvent.HTTP_STATUS,            httpStatusHandler,              false, 0, true);
+                                       loader.addEventListener(Event.COMPLETE,                                         loadedImage,                            false, 0, true);
+                                       loader.addEventListener(HTTPStatusEvent.HTTP_STATUS,            httpStatusHandler,                      false, 0, true);
                                        loader.addEventListener(SecurityErrorEvent.SECURITY_ERROR,      onImageLoadSecurityError,       false, 0, true);
                                        loader.addEventListener(IOErrorEvent.IO_ERROR,                          onImageLoadioError,                     false, 0, true);
                                        loader.load(request.request);
@@ -293,8 +300,6 @@ package net.systemeD.halcyon.styleparser {
                        }
                }
 
-               // data handler
-
                private function loadedImage(event:Event):void {
                        var fn:String=event.target.info['filename'];
                        images[fn]=event.target.data;
@@ -335,7 +340,8 @@ package net.systemeD.halcyon.styleparser {
                // ------------------------------------------------------------------------------------------------
                // Parse CSS
 
-               /** Parse the given MapCSS file by repeatedly throwing regular expressions at it. */
+               /** Parse a MapCSS stylesheet into a set of StyleChoosers. The parser is regular expression-based 
+                       and runs sequentially through the file from start to end. */
                public function parse(css:String):void {
                        var previous:uint=0;                                    // what was the previous CSS word?
                        var sc:StyleChooser=new StyleChooser(); // currently being assembled
@@ -533,8 +539,11 @@ 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*/
+        /** Convert a colour string from CSS colour name ("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]) {