Data Object Slot Groups for RiverWare 6.8 -- Design
Phil Weinstein, David Neumann, Edie Zagona, CADSWES -- Edit: 9-08-2015 (a).

(1) Overview

This document describes a design for new RiverWare capability based on this feature request from TVA:

Create Slot Groups on Data Objects: Allow arbitrary sets of slots to be grouped together (such as SEPA data, Policy Data, etc).  Allow the group and slots to be copied/pasted.

(1.1) Additional Feature Notes from TVA Discussions

Earlier, we examined a snapshot of a model currently under development by TVA to understand how Slot Groups might be used. This model has been put aside here: R:\doc\openObject\SlotGroups\models\SpecialOps6HourV6.mdl. (See also the discussion of the earlier "Revised Design" below).

In discussion with TVA, the following two tentative examples of desirable Slot Group configurations within that model were identified. (This applies to the yellow "Con" Data Objects associated with each Reservoir):

(1.2) Prior Analysis Documents

Two iterations of analysis preceded this design. A couple design and architecture ideas have been put aside based on both internal review and review with TVA. These documents are:

1. Data Object Slot Groups for RiverWare 6.8 -- Analysis / 8-20-2015
    
   • This document explores requirements and two contrasting implementations: (1) A new architectural implementation of Slot Groups, and (2) Full internal use of Aggregate Objects and their Element Objects to represent Slot Groups within a Data Object. Upon internal review, we decided against the latter on the basis of complexity and lack of actual benefit. The Design documented in this (present) document is a refinement of the former approach.
      
2. Data Object Slot Groups for RiverWare 6.8 -- Analysis (Revised Design) / 8-21-2015
    
   • This document pursues a simplified approach of assigning membership of Slots to Slot Groups simply by the names of slots starting with the names of a defined set of Slot Groups. This was based on a mistaken understanding of how Slot Groups were to be used given a relevant sample model under development by TVA. As stated in the feature request, Slot Groups really do need to be composed of arbitrary sets of slot instances.
     

(1.3) Requirements

As primarily a new display provision of the Open Object Dialog for Data Objects, we will support grouping slots together in a slot treeview.

This is somewhat analogous to the slot treeview displayed in Open Object Dialog for Aggregate Objects. See image to the right. However, slots not in a slot group would be displayed as top-level tree items.

Slot Groups can be copied from one Data Object to multiple other Data Objects in a single operation. It will be possible to do this both with, and without copying the source Slot Group's contained slots.

When Deleting a Slot Group, the user will have the options of also deleting the contained slots, or retaining them. In the latter case, they will just become ungrouped, shown as top-level treeview slot items.

As time permits, or possibly as a future enhancement, RPL Predefined Functions will be devised and implemented to support slot list enumerations based on Slot Group names.

(1.4) Related Recent Development: Copy Slots to Data Objects

A recently developed enhancement for RiverWare 6.8 (future release) supports the copying of a set of slots from any simulation object (including from a Data Object) to multiple other Data Objects. This makes use of the dialog shown to the right. This dialog is shown after selecting the slots to be copied from an Open Object Dialog and selecting the "Copy Slots to Data Objects" operation (see below).

This capability will be extended to support the copying of Slot Groups and their slots to multiple other Data Objects. The related operation of replicating Slot Groups from one Data Object to multiple other Data Objects will also be supported with an enhancement to this "Copy Slots to Data Objects" tool.

The newly developed functionality is described in this internal feature document:
Open Object Dialog, Slot Copy/Paste Enhancements for RiverWare 6.8
R:\doc\openObject\CopySlots\OpenObjCopyPasteEnh-Aug2015.docx

(2) User Interface Design

Below is a mockup of the Open Object Dialog for a Data Object showing added support for slot groups. This has a "Group" menu (in place of the "Element" menu for Aggregate Objects):

(2.1) New Slot-Group Operations

When the "Show Slot Groups" checkbox is off, slots will be presented in the traditional way, as a single-level list of slot items. See the image below. When this option is off:

1. The "tree" ornamentation is hidden; Slot items are flush against the left side of the slot list panel.
2. Sorting of slots by name (e.g. after clicking in the "Slot Name" column header) is done without regard to inclusion of slots within slot groups.
3. The other operations in the Group menu are disabled. (Note: this is not correctly shown in the mockup below).
4. The Slot Group-related items in the slot list context menu do not appear.

The "Expand-" and "Collapse All Slot Groups" actions open or close all slot group tree items, effectively showing or hiding the list items for slots within the slot groups.

The "Move Slots to Group" submenu moves the selected slots to a Slot Group on the Data Object. The first item in this submenu is "None" -- selecting that removes the selected slots its group (i.e. those slots in a Slot Group). The last item is "New Slot Group" -- this creates a default-named slot group, and moves the selected slots to that grou. Note that any particular slot instance can be a member of only one Slot Group. So, moving a slot to a group removes it from a slot group it was previously a member of.

"Create New Slot Group" adds a default-named Slot Group.

"Delete Slot Groups" (enabled only when at least one Slot Group item is selected in the slot list) deletes the selected Slot Groups, after showing a confirmation dialog having these three buttons:

• "Slot Groups Only" causes all slots within the selected slot groups to be retained. They will appear as top-level slot items (not contained within any slot group).
• "Slots Too" causes all slots within the selected groups to also be deleted.
• "Cancel" aborts the deletion operation.

To provide a meaningful name to a newly created Slot Group (i.e. after performing Create New Slot Group), the user can edit the group's list item's name directly, but double clicking on it. (This is similar to how Aggregate Object Elements' names are assigned). The edited name must be distinct from the names of all Slots and other Slot Groups on the object, and cannot be "None".

The slot list context menu on slot items will now contain these two actions. (These have been described above). See the following image.

1. Show Slot Groups (checkbox)
2. Move Slots to Group (submenu). This is shown only if the "Shoe Slot Groups" checkbox is on.

(2.2) Slot Ordering Operations

The following mockup shows the Open Object Dialog's slot ordering controls for a data object having slot groups.

Slot Group items in the Open Object Dialog (for Data Objects) are included in the custom orderings implemented for Slots. When the "Custom
for this Object" ordering is selected (e.g. as opposed to Column Sort) slots and slot groups can be moved up or down using the blue arrow icon
buttons below the slot list/tree.

Custom slot ordering now includes these new provisions:

1. Multiple selected Slot Group items can be moved up or down in the list.
2. Slots within (under) a Slot Group can be moved up and down within the group. It is not possible to move Slots into or out from a Slot Group with these controls. Any selected slots not in a slot group "jump over" any encountered slot group.

The blue arrow icon buttons are disabled if BOTH Slot and Slot Group items are selected -- only one or the other type can be moved up or down at any given time. However, any arbitrary Slot selection can be active when moving slots, including both slots in, and not in, slot groups, as illustrated above.

(2.3) Slot Group Copy and Paste Operations

Background: The RiverWare Slot Clipboard currently contains references to existing slots in the loaded RiverWare model. That is, "copying slots" causes references to those slots to be placed in that clipboard. Most applications which can "paste" slots into a slot list (e.g. the Chart output device configuration dialog, one of many examples) make use of those slot references as references. Only the Open Object Dialog for Data Objects actually make copies (new cloned instances) of the slots when pasting from the slot clipboard.

The RiverWare Slot Clipboard will be enhanced to support references Slot Groups. At any given time, the Slot Clipboard will contain references to only slots or slot groups. But when the Slot Clipboard contains references to Slot Groups, any application within RiverWare which queries the Slot Clipboard for slots -- e.g. the (Pie-) Chart output device configuration dialog -- will "see" references to all of the slots within the clipboard's current Slot Groups.

The Open Object Dialog supports pasting of slots from the Slot Clipboard only when that dialog is for a Data Object. It will support different behaviors for the two cases of the Slot Clipboard containing slots vs. slot groups. If the slot clipboard contains groups, a new Slot Group will be created on the Data Object if that object doesn't already have a Slot Group with that name. Then, any slots within the clipboard's referenced Slot Groups will be copied (cloned) into those Slot Groups in the dialog's Data Object.

The two variants of slot / slot group pasting will implement the same slot name uniqueness algorithm. That is, if the Data Object already has a slot with copied slot's name, the newly created slot on the Data Object will be given the next available four-digit numeric suffix to insure slot name uniqueness.

(3) Development Notes

(3.1) Data Model

Data Objects maintain a set of Slot Groups as dynamically allocated C++ objects. Slot Groups maintain a list of references to the slots in the group -- however, groups don't "own" those slots. The relationship between a Data Object and its slots will not change -- slot instances will still be managed directly by their containing object.

Other Data Model tasks:

1. The SlotOrderManager class will need to be enhanced to support object and object-class-based custom slot orderings. Slot Groups will be interspersed with Slots within the slot order. When Slot Groups are in use, the need for all slots in a Slot Group being contiguous will be enforced in the GUI, and only checked within the data model.
    
2. As mentioned above, the Slot Clipboard will need to be enhanced to support a set of selected Slot Groups. There will be a new method to retrieve the clipboard's set of groups (as pointer references to SlotGroup instances). Also the existing method to retrieve the clipboard's set of slots will expand those groups to Slot references (pointer references to Slot instances). See also the extensive "Slot Group Copy and Paste Operations" discussion above.

(3.2) Open Object Dialog: Slot ListView Items

In parallel with the OpenObjectDlg::SlotListViewItem class (a Qt4 QTreeWidgetItem subclass), a new SlotGroupListViewItem class will be developed to represent SlotGroup list items.

(4) Estimates

The following tasks wouldn't be done in this exact order. GUI provisions will be implemented as the required data model provisions are put in place.

---