Some more doco.
authorSteve Bennett <stevagewp@gmail.com>
Sat, 11 Dec 2010 14:43:52 +0000 (14:43 +0000)
committerSteve Bennett <stevagewp@gmail.com>
Sat, 11 Dec 2010 14:43:52 +0000 (14:43 +0000)
net/systemeD/potlatch2/mapfeatures/EditorFactory.as
net/systemeD/potlatch2/mapfeatures/Presence.as

index bfa0ab0..af09546 100644 (file)
@@ -5,16 +5,20 @@ package net.systemeD.potlatch2.mapfeatures {
     import flash.display.*;
 
 
+       /** Instantiates specific editing controls such as textboxes and speed limit selectors depending on the tags of a given entity. This class has child classes that instantiate the appropriate
+       * editors correctly.
+       */
        public class EditorFactory {
            private static const PRIORITY_HIGHEST:uint = 10;
            private static const PRIORITY_HIGH:uint = 8;
            private static const PRIORITY_NORMAL:uint = 5;
            private static const PRIORITY_LOW:uint = 2;
            private static const PRIORITY_LOWEST:uint = 0;
-       
+
+        /** Returns a specific subclass of EditorFactory as appropriate for the type: "freetext", "checkbox", "choice", "slider", "number", "speed", "route", "turn". Otherwise null. */
         public static function createFactory(inputType:String, inputXML:XML):EditorFactory {
             switch ( inputType ) {
-            
+
             case "freetext": return new FreeTextEditorFactory(inputXML);
             case "checkbox": return new CheckboxEditorFactory(inputXML);
             case "choice": return new ChoiceEditorFactory(inputXML);
@@ -23,12 +27,13 @@ package net.systemeD.potlatch2.mapfeatures {
             case "speed": return new SpeedEditorFactory(inputXML);
             case "route": return new RouteEditorFactory(inputXML);
             case "turn": return new TurnRestrictionEditorFactory(inputXML);
-            
+
             }
-            
+
             return null;
         }
 
+        /** Translates a priority string ("highest") to a const (PRIORITY_HIGHEST). */
         public static function getPriority(priority:String):uint {
             switch ( priority ) {
             case "highest": return PRIORITY_HIGHEST;
@@ -39,32 +44,42 @@ package net.systemeD.potlatch2.mapfeatures {
             default: return PRIORITY_NORMAL;
             }
         }
-        
+
+        /** Default Presence behaviour: onTagMatch */
         public var presence:Presence = Presence.getPresence("onTagMatch");
+
+        /** Default sorting: PRIORITY_NORMAL */
         public var sortOrder:uint = PRIORITY_NORMAL;
+
+        /** Default category: "Standard" */
         public var category:String = "Standard";
-        
+
         private var _name:String;
         private var _description:String;
-        
+
+        /** The default EditorFactory extracts name, description and category from the provided map features XML subtree. */
         public function EditorFactory(inputXML:XML) {
             _name = String(inputXML.@name);
             _description = String(inputXML.@description);
             category = String(inputXML.@category);
         }
-        
+
+        /** Whether the tags on an entity correspond to those for the edit control. By default, returns true - must be overriden by more useful behaviour. */
         public function areTagsMatching(entity:Entity):Boolean {
             return true;
         }
 
+        /** A subclass must provide an actual edit control. This returns null. */
         public function createEditorInstance(entity:Entity):DisplayObject {
             return null;
         }
-        
+
+        /** The name of the field/tag/edit control, as defined in map features XML. */
         public function get name():String {
             return _name;
         }
 
+        /** The label given to the edited field, as defined in map features XML. */
         public function get description():String {
             return _description;
         }
index 307428a..4e81505 100644 (file)
@@ -2,12 +2,15 @@ package net.systemeD.potlatch2.mapfeatures {
 
     import net.systemeD.halcyon.connection.*;
 
-
+        /** This class defines the behaviour of the "Presence" attribute in a Map Feature definition. Presence is one of "always", "onTagMatch" or "withCategory".
+        * This is used to control whether edit controls for a feature show up on an given edit page.
+        */
        public class Presence {
            private static var ALWAYS:Presence;
            private static var ON_TAG_MATCH:Presence;
            private static var WITH_CATEGORY:Presence;
-       
+
+        /** Translates a string from the XML form (eg "onTagMatch") to a constant (ON_TAG_MATCH) */
         public static function getPresence(presence:String):Presence {
             if ( ALWAYS == null ) {
                 ALWAYS = new Presence();
@@ -23,6 +26,11 @@ package net.systemeD.potlatch2.mapfeatures {
             return ON_TAG_MATCH;
         }
 
+        /** Determines whether a given edit control (editor) should be used for a given entity, given a certain category page is open.
+        *
+        * If not overriden by a child class, the behaviour is "always": show the edit control on the "Basic" page, and on the appropriate category page.
+        *
+        */
         public function isEditorPresent(editor:EditorFactory, forEntity:Entity, forCategory:String):Boolean {
             return forCategory == null || forCategory == editor.category;
         }
@@ -33,19 +41,21 @@ package net.systemeD.potlatch2.mapfeatures {
 
     import net.systemeD.halcyon.connection.*;
     import net.systemeD.potlatch2.mapfeatures.*;
-
+    /** Special behaviour for the "onTagMatch" case: only show the edit controls if the tags specified for the feature are present on the entity. */
     class OnTagMatch extends Presence {
         public function OnTagMatch() {}
-        
+
         override public function isEditorPresent(editor:EditorFactory, forEntity:Entity, forCategory:String):Boolean {
             return (forCategory == null || forCategory == editor.category) &&
                       editor.areTagsMatching(forEntity);
         }
     }
 
+    /** Special behaviour for the "withCategory" case: only show the edit controls if the tags specified for the feature are present on the entity AND
+     * if the appropriate category page is open. */
     class WithCategory extends Presence {
         public function WithCategory() {}
-        
+
         override public function isEditorPresent(editor:EditorFactory, forEntity:Entity, forCategory:String):Boolean {
             return forCategory == editor.category &&
                       editor.areTagsMatching(forEntity);