Ticket #1357: ordering-updated.patch

lib/OpenLayers/Renderer/Elements.js

@@ -5 +5 @@
-/**
- * @requires OpenLayers/Renderer.js
- */
+/**
+ * Class: OpenLayers.ElementsIndexer
+ * This class takes care of figuring out which order elements should be
+ * placed in the DOM based on given indexing methods. 
+ */
+OpenLayers.ElementsIndexer = OpenLayers.Class({
+   
+    /**
+     * Property: maxZIndex
+     * {Integer} This is the largest-most z-index value for a node
+     * contained within the indexer.
+     */
+    maxZIndex: null,
+    
+    /**
+     * Property: order
+     * {Array<String>} This is an array of node id's stored in the
+     * order that they should show up on screen. Id's higher up in the
+     * array (higher array index) represent nodes with higher z-indeces.
+     */
+    order: null, 
+    
+    /**
+     * Property: indices
+     * {Hash} This is a hash that maps node ids to their z-index value
+     * stored in the indexer. This is done to make finding a nodes z-index 
+     * value O(1).
+     */
+    indices: null,
+    
+    /**
+     * Property: compare
+     * {Function} This is the function used to determine placement of
+     * of a new node within the indexer. If null, this defaults to to
+     * the Z_ORDER_DRAWING_ORDER comparison method.
+     */
+    compare: null,
+   
+    /**
+     * APIMethod: initialize
+     * Create a new indexer with 
+     * 
+     * Parameters:
+     * ordering - {Function} The canonical name of the indexing method to
+     * use. See OpenLayers.ElementsIndexer.Translations below. If null, 
+     * this defaults to "z".
+     */
+    initialize: function(ordering) {
+        
+        var compareMethod = OpenLayers.ElementsIndexer.Translations[ordering];
+        
+        this.compare = compareMethod || OpenLayers.ElementsIndexer.IndexingMethods.Z_ORDER_DRAWING_ORDER;
+        this.order = [];
+        this.indices = {};
+        this.maxZIndex = 0;
+    },
+    
+    /**
+     * APIMethod: insert
+     * Insert a new node into the indexer. In order to find the correct positioning for
+     * the node to be inserted, this method uses a binary search. This makes inserting
+     * O(log(n)). 
+     * 
+     * Parameters:
+     * newNode - The new node to be inserted.
+     */
+    insert: function(newNode) {
+        var nodeId = this.getNodeId(newNode);
+        
+        this.determineZIndex(newNode);       
-
+        var leftIndex = -1;
+        var rightIndex = this.order.length;
+        var middle;
+
+        while (rightIndex - leftIndex > 1) {
+            middle = parseInt((leftIndex + rightIndex) / 2);
+            
+            var nextId = this.order[middle];
+            var next = OpenLayers.Util.getElement(nextId);
+            
+            var placement = this.compare(this, newNode, next);
+            
+            if (placement > 0) {
+                leftIndex = middle;
+            } else {
+                rightIndex = middle;
+            } 
+        }
+        
+        this.order.splice(rightIndex, 0, nodeId);
+        this.indices[nodeId] = this.getZIndex(newNode);
+        
+        // Return the next item in the array -- the id of the node that should
+        // follow this one directly in the index order -- if any.
+        var nextIndex = rightIndex + 1;
+        
+        var returnVal = null;
+        if (nextIndex > 0 && nextIndex < this.order.length) {
+            returnVal = this.order[nextIndex];
+        }
+        return returnVal;
+    },
+    
+    remove: function(node) {
+        var nodeId = this.getNodeId(node);
+        var arrayIndex = this.order.indexOf(nodeId);
+        if (arrayIndex >= 0) {
+            // Remove it from the order array, as well as deleting the node
+            // from the indeces hash.
+            this.order.splice(arrayIndex, 1);
+            delete this.indices[nodeId];
+            
+            // Reset the maxium z-index based on the last item in the order array.
+            var lastId = this.order[this.order.length - 1];
+            this.maxZIndex = this.indices[lastId];
+        }
+    },
+    
+    exists: function(node) {
+        var nodeId = this.getNodeId(node);
+        return this.indices[nodeId] != null;  
+    },
+    
+    /**
+     * APIMethod: getZIndex
+     * Get the z-index value for the current node from the node data itself.
+     */
+    getZIndex: function(node) {
+        return node._style.graphicZIndex;  
+    },
+
+    /**
+     * APIMethod: getMaxZIndex
+     * Get the maximum z-index stored within the indexer.
+     */
+    getMaxZIndex: function() {
+        return this.maxZIndex;
+    },
+    
+    /**
+     * APIMethod: setZIndex
+     * Set the z-index for the given node.
+     */
+    setZIndex: function(node, zIndex) {
+        node._style.graphicZIndex = zIndex;  
+    },
+    
+    /**
+     * Method: determineZIndex
+     * Determine the z-index for the current node if there isn't one, 
+     * and set the maximum value if we've found a new maximum.
+     */
+    determineZIndex: function(node) {
+        var zIndex = node._style.graphicZIndex;
+        
+        // Everything must have a zIndex. If none is specified,
+        // this means the user *must* (hint: assumption) want this
+        // node to succomb to drawing order. To enforce drawing order
+        // over all indexing methods, we'll create a new z-index that's
+        // greater than any currently in the indexer.
+        if (zIndex == null) {
+            zIndex = this.maxZIndex;
+        }
+        
+        if (zIndex > this.maxZIndex) {
+            this.maxZIndex = zIndex;
+        }
+        
+        node._style.graphicZIndex = zIndex;
+    },
+    
+    /**
+     * Method: getNodeId
+     * Get the id of the node passed in.
+     */
+    getNodeId: function(node) {
+        return node.id;  
+    },
+   
+    CLASS_NAME: "OpenLayers.ElementsIndexer"
+});
+
+
+// These are the compare methods for figuring out where a new
+// node should be placed within the indexer. These methods are very 
+// similar to general sorting methods in that they return -1, 0, and 1 
+// to specify the direction in which new nodes fall in the ordering.
+OpenLayers.ElementsIndexer.IndexingMethods = {
+    /**
+     * Method: Z_ORDER
+     * This compare method is used by other comparison methods.
+     * It can be used individually for ordering, but is not recommended,
+     * because it doesn't subscribe to drawing order.
+     */    
+    Z_ORDER: function(indexer, newNode, next) {
+        var newZIndex = indexer.getZIndex(newNode);
+
+        var returnVal = 0;
+        if (next) {
+            var nextZIndex = indexer.getZIndex(next);
+            returnVal = newZIndex - nextZIndex; 
+        }
+        
+        return returnVal;
+    },
+    /**
+     * API Method: Z_ORDER_DRAWING_ORDER
+     * This method orders nodes by their z-index, but does so in a way
+     * that, if there are other nodes with the same z-index, the newest drawn
+     * will be the front most within that z-index. This is the default
+     * indexing method.
+     */
+    Z_ORDER_DRAWING_ORDER: function(indexer, newNode, next) {
+        var returnVal = OpenLayers.ElementsIndexer.IndexingMethods.Z_ORDER(indexer, newNode, next);
+        
+        // Make Z_ORDER subscribe to drawing order by pushing it above
+        // all of the other nodes with the same z-index.
+        if (next && returnVal == 0) {
+            returnVal = 1;
+        }
+        
+        return returnVal;
+    },
+    /**
+     * API Method: Z_ORDER_Y_ORDER
+     * This one should really be called Z_ORDER_Y_ORDER_DRAWING_ORDER, as it
+     * best describes which ordering methods have precedence (though, the name would
+     * be too long). This method orders nodes by their z-index, but does so in a way
+     * that, if there are other nodes with the same z-index, the nodes with the
+     * lower y position will be "closer" than those with a higher y position. 
+     * If two nodes have the exact same y position, however, then this method
+     * will revert to using drawing order to decide placement.
+     */
+    Z_ORDER_Y_ORDER: function(indexer, newNode, next) {
+        var returnVal = OpenLayers.ElementsIndexer.IndexingMethods.Z_ORDER(indexer, newNode, next);
+        
+        if (next && returnVal == 0) {
+            var newLat = newNode._geometry.getBounds().bottom;
+            var nextLat = next._geometry.getBounds().bottom;
+            
+            var result = nextLat - newLat;
+            
+            if (result == 0) {
+                returnVal = 1;
+            } else {
+                returnVal = result;
+            }
+        }
+        
+        return returnVal;       
+    }
+}
+
-/**
+ * Translate canonical names for ordering methods to their 
+ * function equivalents. 
+ */
+OpenLayers.ElementsIndexer.Translations = {
+    "z" : OpenLayers.ElementsIndexer.IndexingMethods.Z_ORDER_DRAWING_ORDER,
+    "y" : OpenLayers.ElementsIndexer.IndexingMethods.Z_ORDER_Y_ORDER   
+}
+
+
+/**
- * Class: OpenLayers.Renderer.Elements
- * This is another virtual class in that it should never be instantiated by 
- *  itself as a Renderer. It exists because there is *tons* of shared 
@@ -42 +305 @@
-    xmlns: null,
-    
-    /**
+     * Property: Indexer
+     * An instance of OpenLayers.ElementsIndexer created upon
+     * initialization.
+     */
+    indexer: null, 
+    
+    BACKGROUND_ID_SUFFIX: "_background",
+    
+    /**
-     * Property: minimumSymbolizer
-     * {Object}
-     */
@@ -57 +329 @@
-     * 
-     * Parameters:
-     * containerID - {String}
+     * ordering - {String} The cononical name for the ordering method
+     * used (such as "z"). See OpenLayers.ElementsIndexer.Translations above. 
-     */
-
+, ordering
-        OpenLayers.Renderer.prototype.initialize.apply(this, arguments);
-
-        this.rendererRoot = this.createRenderRoot();
@@ -66 +340 @@
-        
-        this.rendererRoot.appendChild(this.root);
-        this.container.appendChild(this.rendererRoot);
+        
+        this.indexer = new OpenLayers.ElementsIndexer(ordering);
-    },
-    
-    /**
@@ -135 +411 @@
-            return;
-        };
-
+        var id = geometry.id;
+        
+        if (style.backgroundGraphic) {
+            this.redrawBackgroundNode(id, geometry, style, featureId);
+        }
+        
-        if (style.display != "none") {
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-        } else {
-geometry.
+
-            if (node) {
-                node.parentNode.removeChild(node);
-            }
-        }
-    },
+    
+    redrawNode: function(id, geometry, style, featureId) {
+        // Get the node if it's already on the map.
+        var currentNode = OpenLayers.Util.getElement(id);
+        
+        // Create a new node, or use the current one if it's
+        // already there.
+        var newNode;
+        if (!currentNode) {
+            var nodeType = this.getNodeType(geometry, style);
+            newNode = this.createNode(nodeType, id);
+        } else {
+            newNode = currentNode;
+        }
+        
+        // Set the data for the node, then draw it.
+        newNode._featureId = featureId;
+        newNode._geometry = geometry;
+        newNode._geometryClass = geometry.CLASS_NAME;
+        newNode._style = style;
+        newNode = this.drawGeometryNode(newNode, geometry, style);
+        
+        // If the node is known to the indexer, remove it so we can
+        // recalculate where it should go.
+        if (this.indexer.exists(newNode)) {
+            this.indexer.remove(newNode);
+        }
+        
+        // Insert the node into the indexer so it can show us where to place it.
+        // Note that this operation is O(log(n)). If there's a performance problem
+        // (when dragging, for instance) this is likely where it would be.
+        var nextNodeId = this.indexer.insert(newNode);
-
+        // If the new node should be before another in the index
+        // order, insert the new node before the next; else, lets just
+        // append the new one on the end, making it the highest in the index order.
+        if (nextNodeId) {
+            var nextNode = OpenLayers.Util.getElement(nextNodeId);
+            this.root.insertBefore(newNode, nextNode);
+        } else {
+            this.root.appendChild(newNode);
+        }
+        
+        this.postDraw(newNode); 
+    },
+    
+    redrawBackgroundNode: function(id, geometry, style, featureId) {
+        var backgroundStyle = OpenLayers.Util.extend({}, style);
+        
+        // Set regular style attributes to apply to the background styles.
+        backgroundStyle.externalGraphic = backgroundStyle.backgroundGraphic;
+        backgroundStyle.graphicXOffset = backgroundStyle.backgroundXOffset;
+        backgroundStyle.graphicYOffset = backgroundStyle.backgroundYOffset;
+        backgroundStyle.graphicZIndex = backgroundStyle.backgroundGraphicZIndex;
+        
+        // Erase background styles.
+        backgroundStyle.backgroundGraphic = null;
+        backgroundStyle.backgroundXOffset = null;
+        backgroundStyle.backgroundYOffset = null;
+        backgroundStyle.backgroundGraphicZIndex = null;
+        
+        this.redrawNode(id + this.BACKGROUND_ID_SUFFIX, geometry, backgroundStyle, null);
+    },
+
-    /**
-     * Method: drawGeometryNode
-     * Given a node, draw a geometry on the specified layer.
@@ -337 +668 @@
-                this.eraseGeometry(geometry.components[i]);
-            }
-        } else {    
-
+
+
+
+
-            if (element && element.parentNode) {
+                if (element.geometry) {
+                    element.geometry.destroy();
+                    element.geometry = null;
+                }
-                element.parentNode.removeChild(element);
+                
+                this.indexer.remove(element);
-            }
+            
+            var backgroundId = geometry.id + this.BACKGROUND_ID_SUFFIX;
+            var backgroundElement = OpenLayers.Util.getElement(backgroundId);
+            if (backgroundElement && backgroundElement.parentNode) {
+                if (backgroundElement.geometry) {
+                    backgroundElement.geometry.destroy();
+                    backgroundElement.geometry = null;
+                }
+                backgroundElement.parentNode.removeChild(backgroundElement);
+                
+                this.indexer.remove(backgroundElement);
+            }
-        }
-    
-
+
+
-    /** 
-     * Method: nodeFactory
-     * Create new node of the specified type, with the (optional) specified id.

lib/OpenLayers/Layer/Vector.js

@@ -130 +137 @@
-     * {<OpenLayers.Renderer>}
-     */
-    renderer: null,
+    
+    /**
+     * APIProperty: ordering
+     * {String} The ordering method that the layer's renderer should use.
+     * 
+     * Valid values are:
+     *      "z" - Use z-ordering.
+     *      "y" - Use y-ordering.
+     * 
+     * This defaults to z-ordering if no ordering is specified.
+     */
+    ordering: "z",
-   
-    /** 
-     * APIProperty: geometryType
@@ -213 +233 @@
-        for (var i = 0; i < this.renderers.length; i++) {
-            var rendererClass = OpenLayers.Renderer[this.renderers[i]];
-            if (rendererClass && rendererClass.prototype.supported()) {
-this.renderer = new rendererClass(this.div
-
+ this.renderer = new rendererClass(this.div, this.ordering
+ 
-            }  
-        }  
-    },