Requirements Analysis for a RiverWare Slot Viewer, Bake 1
Phil Weinstein, CADSWES, 7-14-2017 (b), SUPERSEDED. See Bake 2.

Overview

As a way to improve the manageability of windows in RiverWare for which many window instances are commonly used, the introduction of the Object Viewer in RiverWare 7.1 (released just this week) seems to be very successful. We are now pursuing a similarly inspired approach for Series Slots (perhaps with support also for Scalar Slots and display-only support for Periodic Slots), presenting multiple Slots in a single dialog, in a tabular presentation similar to the Edit Account dialog.

The Object Viewer is devised strictly as an "ad-hoc" tool. Objects are added to the Object Viewer (as Object Tabs) every time an Object is opened. The list of objects in the Object Viewer has no persistence. We want the Slot Viewer to similarly support "ad-hoc" operation, rather than something requiring a lot of (or really, any) set up. Each time a Series Slot is opened from anywhere in RiverWare, it is just added -- as a column, or multiple columns -- to the Slot Viewer. From the Slot Viewer, any slot can then be shown also in (or perhaps, instead in) the slot's conventional Open Slot dialog.

Potential requirements for the Slot Viewer need to be addressed in ways which are compatible with ad-hoc operation. A potential conflict which comes to mind is the requested provision for swapping in a different object for the Slot Viewer's slots. It's not hard to imagine work flows in which we would want such an operation to apply to only certain slots in the viewer. We might want to implement flags on slot items to indicate their participation in this operation. We can entertain some settings like this, but such provisions need to be evaluated in the context of the general ad-hoc use of the Slot Viewer.

Proposed Requirements and High Level Design Provisions:

Important Functional Requirements:

1. There is only a single Slot Viewer instance. (Multiple named instances could be considered in the future).
2. The Slot Viewer's presentation of Series Slots is similar to the Edit Account dialog's series slot display, with vertical time.
3. When a Series Slot is "opened" from anywhere in RiverWare, instead of showing the slot's conventional Open Slot dialog, the new Slot Viewer is shown, with the Series Slot presented as a display column.
4. It must be possible to show the Slot Viewer's slots in their open conventional Open Slot dialogs.
5. Only Series Slots having the same timestep size are shown at any given time. If Series Slots having different timestep sizes have been added to the Slot Viewer, then the user switches between those different timestep sizes, e.g. with a combobox or set of tabs.
6. It must be possible to remove Series Slots from the viewer.
7. It must be possible to reorder the viewer's Series Slots.
8. Slot values and flags are editable, including with multiple-cell and high-level editing operations (e.g. Interpolate and Adjust Values).
9. The Slot Viewer supports a "selection statistics" panel along the bottom of the dialog -- similar to that panel in Open Slot Dialogs and the SCT.
10. The Slot Viewer will not support slot renaming. However, the dialog does need to automatically update with a slot's new name when the name is changed elsewhere (i.e. in its conventional Open Slot dialog).

Other Provisions to be considered:

11. Among the choices of timestep size (see #5, above) could be a special option for Scalar Slots, where a set of Scalar Slots are all presented together in a tabular arrangement (like the Scalar Slots tab in the SCT).
12. Display-only support for Periodic Slots, interpolated or stepped, according to the Periodic Slot's default lookup setting.*
13. Operations to show and hide the multiple columns (beyond the first column) of AggSeriesSlots and MultiSlots.
14. Support for Table Series Slots. (Internally, these are a Table Slot subclass, not a special type of Series Slot, as such).**
15. An operation to show (all or some of) the Slot Viewer's slots on a different simulation object. (Various design alternatives are explored below).

(*) Display-only support for Periodic Slots as interpolated (or stepped) values within a series display might be a valuable SCT enhancement. (However, the SCT's series data display is implemented with different C++ classes).

(**) Although support for Table Series Slot columns may not be an important requirement, the existing C++ classes used to implement the Slot Viewer do readily support those.

Reconsidered Prior Requirements:

A prior analysis from late April suggested the following provisions:

• A Series Slots could be "torn off" by dragging the column header out from the Slot Viewer. The new Object Viewer supports that sort of operation on its Object Tabs.
• The Slot Viewer's Series Slots could be reordered by dragging a column header to a different position.

These drag operations interfere with the use of dragging along the column header to select multiple selected slots (display columns). Selection of whole slots in this manner is important for many operations on slots we need to support. We will support slot reordering and the showing of separate Open Slot dialogs in other ways.

REVISION (7-15-2017): We can actually use DRAGGING a display column header to show the Slot's Open Slot dialog -- and also dragging the Open Slot dialog's icon (or something) back into the Slot Viewer. Those GUI operations would not interfere with dragging along the column headers to select contiguous slots. (This would be implemented with low level mouse events, not Qt drag events, as such).

Slot Viewer Control Design

The Slot Viewer will present most of the conventional Open Slot Dialog controls above the series data table. This includes:

• A numeric value line editor, in which the current cell's (one of the selected cell's) value is shown in full precision. Entering a value in this line editor causes that value to be assigned to all of the selected cells.
• A DateTime Spinner, with global time navigation controls.
• A "Plot Slots" icon button.

Above those legacy controls will be new controls for operating on the set of slots shown in the Slot Viewer. Here is one possible design:

The "Slots" combobox would be populated with only the timestep sized actually represented by Series Slots actually present within the Slot Viewer.

• The mockup above shows also a "Scalar" option, if we choose to support a Scalar Slot table (with one row per scalar).
• Instead of an "Add Slots ..." button, this combo box could have an "Add Slots ..." item (probably as the last item).

A treeview button shows a second row of controls. Depicted above are controls for these operations:

• "Add Slots ..." button. This brings up the GUS slot selector with the slot type filter shown and pre-selected to "Series Slots". When slots are added to the SCT, the series data table is scrolled to the added slots. We could also present a similar "Insert Slots ..." operation to insert picked slots before the first selected slot.
• "Paste Slots" icon button. This pastes slots from the Slot Clipboard.
• "Open" button. This shows the selected slots in their own Open Slot dialogs.
• "Copy Slots" icon button. This copies the selected slots to the Slot Clipboard.
• "Move Left" and "Move Right" arrow icon buttons. These move the selected slots to the right or left.
  ... in "Scalar" mode (if implemented), these would be changed to Up and Down icon buttons.
• "Remove Slots" icon button, removes the selected slots from the Slot Viewer.

Operations dependent on the current Slot selection would be dynamically conditioned (enabled/disabled) based on the current Slot selection (whole selected display columns).

"Change Object" Operation, or "Wildcard Object" Provision

There are many ways in which the Object of slots in the Slot Viewer could be swapped out with a different Object. Since this is the ad-hoc tool where ALL series slots are shown immediately when they are "opened", and we are not saving named Slot Viewer configurations, this feature shouldn't incorporate a lot of setup.

A "Change Object" Operation requires two general inputs:

1. The Object to which slots will be switched.
2. Which Slot Items in the Slot Viewer will be affected.

(A) The Object could be identified in these ways:

1. The Object currently being shown the Object Viewer. This could be either a one-shot operation in the Slot Viewer, or dynamically triggered from changes in the Object Viewer.
2. An object picked with the GUS Object Selector. (This isn't ideal if the user is typically switching between a small subset of objects).
3. One of several objects in a small list of object names maintained with the Slot Viewer. (We could make this small list persistent within the RiverWare Model).
4. One of the objects currently in the Object Viewer (i.e. not necessarily its current object).

(B) The Slots could be identified in these ways:

1. All Slot Items
2. All Slot Items on the same type of Object as the Picked Object. (This would probably treat all Reservoir subclasses as just Reservoirs).
3. Slot items identified as "Wildcard Object" Slot Items.
4. Slot items NOT identified as "Locked" Slot Items.

The following mockup (on the right side) demonstrates the "Wildcard Object" Slot Item design (B3) where particular Slot Items are identified as "Wildcard Object" Slots. Those would be indicated with a some sort of ornamentation in the column header (e.g. a cyan background, matching the color of the "Set Obj Wildcard" button). This supports both the (A1) "Object currently shown in the Object Viewer" and (A3) "One of several objects in a small list of object names maintained in the Slot View" (and persistent in the model file).

• The "From Object Viewer" selection causes a Change Operation every time the Object Viewer's current tab changes.
• The "Add Objects..." selection shows the GUS Object Selector to add an object to the combo box. The mockup illustrates four such added reservoirs.
• The Red Minus icon button is enabled only if one of the added objects are selected. It removes the currently selected item from the list.
• The "Set Obj Wildcard" and "Clear Obj Wildcard" buttons are enabled only if at least one Slot item (display column) is selected. They set or clear the "Obj Wildcard" flag on the selected Slots.

Implementation

Many of the series data displays in RiverWare -- but not the SCT -- are implemented with a common set of classes -- a dialog class (SlotQtDlg, with four different application modes) and a series data table class (SlotDataTableView, a QTableView subclass, with supporting data model and delegate classes). The four "applications" are:

1. Open Slot (which supports Series Slots, Table Slots and Periodic Slots)
2. Edit Account
3. Object Account Summary
4. Exchange Balance

Once the array of Slots (actually, of Slot Column References) is set up within the series data table's QAbstractTableModel subclass, much of the operation of these classes, e.g. displaying and editing series slot values, and support for the "selection statistics", is independent of the particular application.

The Edit Account application is basically the closest to what's required for the Slot Viewer. But the Object Account Summary application has some dynamic provisions which are also relevant, dynamically installing a new list of slots based on names from two different lists: Accounts on an Object, and the names of Series Slots on Accounts.

The Slot Viewer would be fifth application of these classes. Work to implement this application includes supporting widget and menu creation and layout within SlotQtDlg, and algorithms to build the Slot Column Reference (SlotColRef) list within the series data table model class. An alternative to extending SlotQtDlg with a new application is creating a new dialog class which makes use of the series data table class. That approach should also be considered. In fact, that sort of thing was done recently by Patrick Lynn for the RiverWare Scenario Explorer.

--- (end) ---