Requirements Analysis for a RiverWare Slot Viewer, Bake 2
Phil Weinstein, David Neumann, Edie Zagona, CADSWES, 7-19-2017 (a), Ready for Review.

Document History:

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 last week) seems to be successful. We are now pursuing a similar approach for Series 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 -- 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.

(*) Initial support is limited to single-column Series Slots and the first column of MultiSlots having the same timestep size as the run controller. All other slots are shown only in their own conventional Open Slot dialogs and the SCT. [7-17-2017].

Proposed Requirements and High Level Design Provisions:

Functional Requirements:

Generally, all capabilities of the Open Series Slot dialog will be provided by the Slot Viewer, including data display provisions, editing operations, and data I/O. Some operations and display provisions are enabled only when exactly one slot is selected. Slots are selected by clicking in, or dragging across timestep cells within the slot's display column.

The Slot Viewer supports the following capabilities.

  1. There is only a single Slot Viewer instance. (Multiple instances, possibly named and persistent, 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 supported slot type 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. Initial support is limited to single-column Series Slots and the first column of MultiSlots having the same timestep size as the run controller.
  5. Operations on the set of slots shown in the viewer:
    1. Show the selected slots in their own conventional Open Slot dialogs.
    2. Drag the selected slot off into its own Open Slot dialog (removing the slot from the viewer).
    3. Drag a conventional Open Slot dialog (for the supported slot types) into the Slot Viewer.
    4. Add more slots to the Slot Viewer via the GUS Slot Selector or Pasting from the Slot Clipboard.
    5. Remove the selected slots, or a single slot (by clicking a Red-X icon button in its column header).
    6. Reorder the viewer's slots (display columns) by dragging single column headers.
  6. Operations on the viewer's slots' properties:
    1. Rename the single selected slot.
    2. Display and editing of the single selected slot's description text.
    3. Edit numeric values and flags, including with multiple-cell selections and high-level editing operations (e.g. Interpolate and Adjust Values).
  7. Other special operations:
    1. Slot value import and export operations.
    2. Plotting of selected slots.
    3. Column width operations (e.g. fit data) and manual column width adjustments.

Excluded provisions:

The following features have been talked about relative to the Slot Viewer, but will not be part of the initial implementation. (Some of these features were briefly explored in the initial draft of this document).

  1. Support for Series Slots having a different timestep sizes. There are a couple possibilities for this:
    1. A switch (combo box or tabs) for each timestep size among the slots present in the slot viewer.
    2. Series Slots having a larger timestep size could be shown by repeating their values in the smaller timestep rows, non-editable except in cells alligned with the slot's (larger) timestep.
  2. Support for multiple-column Series Slots, with operations to show and hide the multiple columns (i.e. beyond the first column).
  3. A panel or page presenting a table of Scalar Slots (and 1x1 Table Slots), one row per scalar slot, similar to the SCT's Scalar tab. (Showing this page could be based on a "Scalar Slots" item in the timestep size selector mentioned above).
  4. Display-only support for Periodic Slots by interpolating or stepping the slot's values (according to the Periodic Slot's default lookup algorithm).
  5. Support for Table Series Slots. (Internally, these are a Table Slot subclass, not a special type of Series Slot, as such).
  6. An operation to show (all or some of) the Slot Viewer's slots on a different simulation object. (This sort of feature, especially, would need more discussion).

Slot Viewer Dialog Design

The Slot Viewer is essentially an Open Series Slot dialog, but supporting a list of SeriesSlots rather than just one. Operations on a whole slot will affect the single selected slot or multiple selected slots. Here is a mockup of a possible Slot Viewer design, and a RiverWare 7.1 Open Slot dialog:

Here is a detail of the GUI controls along the top of the Slot Viewer:

First Row:

Second Row:

Here is a detail of the slot column headers:

Display columns (for particular Series Slots) can be removed from the viewer by clicking the Red-X button. Some differences from what is shown here should be considered:

  1. The row of slot column labels (i.e. "Total" in the example above) doesn't need to be shown if all slots are top-level slots (which will generally be the case).
  2. The Red-X buttons could be hidden (or shown as grey) in non-selected columns.

New Operations: Series Slot List Management

Beyond the operations supported in the Open Series Slot dialog, the Slot Viewer also needs to support operations on its current list of slots (i.e. the series slots shown as column in the series data display table).

The current Open Series Slot dialog (in RiverWare 7.1) provides whole-slot operations in its File menu, as depicted here:

Those operations are, by and large, I/O operations, so could reasonably remain in that menu. We currently propose adding a new "Slots" menu to present the following new operations.

  1. Open Selected Slots...
  2. Insert Slots with Slot Selector...
  3. Append Slots with Slot Selector...
  4. Paste (Insert) Slots
  5. Paste (Append) Slots
  6. Copy Selected Slots
  7. Remove Selected Slots

We could also consider moving the "Plot" and "SCT..." operations to the "Slots" menu.

Special column header drag implementations support these features:

  1. Slots (display columns) can be dragged to a different postion.
  2. Dragging a column header out from the dialog causes that slot to be removed from the viewer and shown in its own Open Slot dialog.
  3. Dragging an Open Slot Dialog's column header into the Slot Viewer inserts a column for that slot in the viewer and closes the Open Slot Dialog.

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.

--- (end) ---