diff view/View.h @ 842:8432d2551fb2 tonioni

Update subrepos and merge from default branch

--- a/view/View.h	Fri Jul 18 15:06:04 2014 +0100
+++ b/view/View.h	Tue Sep 02 16:23:48 2014 +0100
@@ -145,37 +145,89 @@
      */
     virtual void scroll(bool right, bool lots, bool doEmit = true);
 
+    /**
+     * Add a layer to the view. (Normally this should be handled
+     * through some command abstraction instead of using this function
+     * directly.)
+     */
     virtual void addLayer(Layer *v);
-    virtual void removeLayer(Layer *v); // does not delete the layer
-    virtual int getLayerCount() const { return m_layers.size(); }
 
     /**
-     * Return a layer, counted in stacking order.  That is, layer 0 is
-     * the bottom layer and layer "getLayerCount()-1" is the top one.
+     * Remove a layer from the view. Does not delete the
+     * layer. (Normally this should be handled through some command
+     * abstraction instead of using this function directly.)
+     */
+    virtual void removeLayer(Layer *v);
+
+    /**
+     * Return the number of layers, regardless of whether visible or
+     * dormant, i.e. invisible, in this view.
+     */
+    virtual int getLayerCount() const { return m_layerStack.size(); }
+
+    /**
+     * Return the nth layer, counted in stacking order.  That is,
+     * layer 0 is the bottom layer and layer "getLayerCount()-1" is
+     * the top one. The returned layer may be visible or it may be
+     * dormant, i.e. invisible.
      */
     virtual Layer *getLayer(int n) {
-        if (n < int(m_layers.size())) return m_layers[n]; else return 0;
+        if (n < int(m_layerStack.size())) return m_layerStack[n];
+        else return 0;
     }
 
     /**
-     * Return the top layer.  This is the same as
-     * getLayer(getLayerCount()-1) if there is at least one layer, and
-     * 0 otherwise.
+     * Return the nth layer, counted in the order they were
+     * added. Unlike the stacking order used in getLayer(), which
+     * changes each time a layer is selected, this ordering remains
+     * fixed. The returned layer may be visible or it may be dormant,
+     * i.e. invisible.
      */
-    virtual Layer *getTopLayer() {
-        return m_layers.empty() ? 0 : m_layers[m_layers.size()-1];
+    virtual Layer *getFixedOrderLayer(int n) {
+        if (n < int(m_fixedOrderLayers.size())) return m_fixedOrderLayers[n];
+        else return 0;
     }
 
     /**
-     * Return the layer last selected by the user.  This is normally
-     * the top layer, the same as getLayer(getLayerCount()-1).
-     * However, if the user has selected the pane itself more recently
-     * than any of the layers on it, this function will return 0.  It
-     * will also return 0 if there are no layers.
+     * Return the layer currently active for tool interaction. This is
+     * the topmost non-dormant (i.e. visible) layer in the view. If
+     * there are no visible layers in the view, return 0.
+     */
+    virtual Layer *getInteractionLayer();
+
+    virtual const Layer *getInteractionLayer() const;
+
+    /**
+     * Return the layer most recently selected by the user. This is
+     * the layer that any non-tool-driven commands should operate on,
+     * in the case where this view is the "current" one.
+     *
+     * If the user has selected the view itself more recently than any
+     * of the layers on it, this function will return 0, and any
+     * non-tool-driven layer commands should be deactivated while this
+     * view is current. It will also return 0 if there are no layers
+     * in the view.
+     *
+     * Note that, unlike getInteractionLayer(), this could return an
+     * invisible (dormant) layer.
      */
     virtual Layer *getSelectedLayer();
+
     virtual const Layer *getSelectedLayer() const;
 
+    /**
+     * Return the "top" layer in the view, whether visible or dormant.
+     * This is the same as getLayer(getLayerCount()-1) if there is at
+     * least one layer, and 0 otherwise.
+     *
+     * For most purposes involving interaction or commands, you
+     * probably want either getInteractionLayer() or
+     * getSelectedLayer() instead.
+     */
+    virtual Layer *getTopLayer() {
+        return m_layerStack.empty() ? 0 : m_layerStack[m_layerStack.size()-1];
+    }
+
     virtual void setViewManager(ViewManager *m);
     virtual void setViewManager(ViewManager *m, int initialFrame);
     virtual ViewManager *getViewManager() const { return m_manager; }
@@ -236,6 +288,8 @@
 
     virtual int getPropertyContainerCount() const;
 
+    // The 0th property container is the view's own; the rest are the
+    // layers in fixed-order series
     virtual const PropertyContainer *getPropertyContainer(int i) const;
     virtual PropertyContainer *getPropertyContainer(int i);
 
@@ -368,7 +422,8 @@
 
     bool                m_deleting;
 
-    LayerList           m_layers; // I don't own these, but see dtor note above
+    LayerList           m_layerStack; // I don't own these, but see dtor note above
+    LayerList           m_fixedOrderLayers;
     bool                m_haveSelectedLayer;
 
     QString             m_lastError;