Project: USACE ABQ 5.11: Output Canvas Items on Workspace views
Phil, 4-07-2017 (a).

SEE also Phil's project reference webpage.

Architectural Preparation / Preliminary

• SUPERSEDED -- See Revised Notes.
  
  

Architecture Analysis Topics

(A) Architectural Preparation: Route OutputCanvasConfig change notifications through a new singleton.

Notifications of changes to the OutputCanvasConfig made from the rwSettingTree-based editor (left side of image above) are propagated to the OutputCanvasScene (right side of image above) via RiverWare callbacks emitted from the OutputCanvasConfig. The OutputCanvasScene then routes some of those notifications to its contained graphics items, e.g. TeacupGfxItems.

With the current enhancement, some object associated with the RiverWare Workspace Views (WorkspaceGfxScene instances) will need to receive these notifications from multiple OutputCanvasConfigs. Being that the CallbackData structures provided in the relevant callbacks (see below) contain a reference to the containing OutputCanvasConfig, we can simplify the registration of clients to receive those callbacks by routing the callbacks through a new singleton.

class OutputCanvasConfigCallbackData : public CallbackData
{
  private:
   OutputCanvasConfig* _config;  // sender
   OutputCanvasNode* _group;     // may be NULL
   OutputCanvasNode* _node;      // may be NULL

  ... ... ...
};

Note that, internally, the OutputCanvasConfig generates all such callbacks from this private method:

void OutputCanvasConfig::sendCallback (CallbackType cbType,
                                       OutputCanvasNode* group,
                                       OutputCanvasNode* node)
{
   // NOTE: OutputCanvasConfig callbacks are intended primarily to support
   // notifications to the graphical canvas (QGraphicScene). But the
   // Output Canvas configuration tree (or its QAbstractItemModel) will
   // make use of OUTCAN_TEACUP_ADDED, OUTCAN_TEACUP_MOVED and
   // OUTCAN_TEACUP_DELETED callbacks.

   OutputCanvasConfigCallbackData dat (this, group, node);

   // NOTE: callback data accessors:
   //-- OutputCanvasConfig* config();
   //-- OutputCanvasNode* group(); // (May be NULL)
   //-- OutputCanvasNode* node();  // (May be NULL)

   callCallbacks (cbType, &dat); // [Root]
}

It will be a simple matter to create a new OutputCanvasConfigMgr singleton, just for the purpose of routing these callbacks. This would be a "Root" subclass so that it can send out callbacks (to all entities that have registered to receive callbacks from this "Root" object). For now, this new manager class wouldn't need to provide any other functionality. In particular, it would not need to keep track of the instantiated OutputCanvasConfig objects. (That is currently being done by the Sim/cwOutputDeviceMgr object).

(B) Architectural Preparation: Extract from OutputCanvasScene the management of the contained QGraphicItems into a class which can be shared with WorkspaceGfxScene.

Much of the OutputCanvasScene's implementation (a QGrahicsScene subclass) will be moved to a new OutputCanvasGfxItemMgr (graphics item manager) class. Every OutputCanvasScene AND potentially each of the three RiverWare Workspace Views will have an instance of this manager class to manage Output Canvas graphics items within its QGraphicsScene.

OutputCanvasGfxItemMgr will fundamentally support the creation of graphics items for an arbitrary set of OutputCanvasConfig items (i.e. of the types that have a direct correspondence to a graphics item, e.g. Teacups), but will have higher-level capabilities for the automatic maintenance of graphics items for multiple entire OutputCanvasConfig instances.

---