SCT Series Slot List Composition Mode in RiverWare 6.1
Analysis and Development Proposal
Phil Weinstein, CADSWES, 8-15-2011, Ready for Review, including development analysis and estimate.
See also: Functional Description ; Review One ; Review Two

• (1.0) Requirements
• (2.0) Design
• (2.1) SCT "Slots" Menu
• (2.2) Series Slot List Composition Views
• (2.3) Treeview and Listview Columns
• (2.4) Operations
• (3.0) Development Tasks
• (3.1) Development Estimates

(1.0) Requirements

In the current and earlier versions of RiverWare (6.1 development), defining and reordering the list of series slots in the SCT series slot table is difficult. It needs to be easier to modify the order of slot items and groups of slot items, and to define and maintain slot item groups containing similar slots on different simulation objects and accounts.

A new special mode of the SCT should temporarily replace the SCT's series slot data table (on the "Series Slot" tab) with a listview / treeview supporting these slot list maintenance functions:

1. Insert slot dividers and multiple new slot items for slots picked with the GUS slot selector,
2. Remove multiple slot items and slot dividers,
3. Edit slot item and divider text,
4. Move multiple individual selected slot items within the slot list,
5. Move groups of slot items within the slot list without mistakenly reordering the slot items within the groups,
6. For a slot item group made up of slots from one simulation object or one account:
   1. Create slot item groups with the same slots (as available) from other simulation objects or accounts picked with the GUS object or account selector,
   2. Apply the order of the slots within the group to similar slot groups.

For the simulation object and account "slot item group" operations above, the creation of new groups based on other objects, or the application of the slot order to other groups, should not depend on an exact match of the visible slots of the various objects involved in the operation. In particular, reservoirs -- and any future object classes related in an inheritance hierarchy -- should be handled polymorphically (e.g. just as "reservoirs").

The user should be able to perform these operations with minimal interaction (e.g. through the use of context menus and visible GUI controls). The user should not have to define "template" objects for the "slot item group" operations. The characterization of a slot item group as being composed of slots from the same simulation object or account must be automatic -- i.e. for the advanced operations supported on those special groups.

Slot item groups will be defined with the placement of "slot divider items" between contiguous groups of slot items. This is the basis of the "slot navigation" support in the current SCT's "Go To" menu illustrated in the following two screenshots. Note that slot divider items have optional user-provided text. Dividers without text are identified with the text of the subsequent slot item. The actual divider items may be shown with text (only in horizontal timestep orientation), or may be shown without text, as thin divider lines (in both axis orientations). (These provisions are already available in the SCT and its series slot data table).

(2.0) Design

General notes:

1. Series Slot list edits will effectively be immediately applied. The user will not be able to abort changes. (The user does have the option of not saving the SCT to the file system, and of reloading the SCT file if irreversible mistakes have been made).
    
2. For brevity, this document refers to all slot items as being for slots. But actually, the SCT Series Slot Data Table also supports slot columns on Table Series Slots. For such items, the full Slot Name and Column Label are shown.

(2.1) SCT "Slots" Menu

An "Edit Series Slot List..." menu operation will be added to the "Slots" menu -- tentatively above the "Insert Slots..." menu. (The current menu, before the introduction of this new feature, is shown to the right). Selecting the "Edit Series Slot List..." menu operation will force the "Series Slot" tab to be shown, and will temporarily replace the Series Slot Data Table with the Series Slot List Composition Listview.

The removal of redundant operations in this menu (i.e. implemented by the new listview tool) needs to be considered. There is some benefit to keeping some of these operations available for direct application to the Series Slot Data Table, e.g. for removing slots which don't have "interesting" data -- and similarly, for tentatively adding slots to see if they do.

(2.2) Series Slot List Composition Views

The Series Slot List Composition mode will have two distinct modes:

• Slot Groups -- Shows a two-level TreeView with Slot Dividers being top-level items, and subsequent Slot Items shown as its children. This mode allows the movement of multiple selected Groups up or down among the other Groups, using the arrow buttons (see below). An implicit initial divider (group) always exists.
• Slot Items -- Shows a single-level ListView with both Slot Dividers and Slot Items. This mode allows the movement of multiple selected dividers and/or slot items up or down with the arrow buttons (see below). An implicit initial divider always exists.

(2.3) Treeview and Listview Columns

The following columns will be shown (with individual content for each slot divider and slot item):

1. Slot Type Icon -- only on slot items, and only if the slot actually exists in the model
2. Slot Item Label -- Editable text for both divider and slot items. The label for slot items is initially the complete slot name (when it is added to the SCT), but can be changed by the user.
3. Slot Name -- Non-editable. complete slot name (with containing object). Optionally shown based on a checkbox below the list: "[x] Show both Slot Labels and Slot Names."
4. Unit Type -- only for slot items, and only if the slot actually exists in the model.

(2.4) Operations

The following buttons and/or context menu operations will be implemented. They operate on the selected Treeview or Listview items. The enabledness of each operation depends on the item selection. Buttons are shown below the list -- possibly in two rows. The decision about whether or not an operation is deployed as an actual button will be made after looking at some prototype screenshots (TBD).

Button and/or Context Menu Op	Description	Enabled
	(Buttons only). Move selected items up or down one position. Rapid repeated clicking will operate smoothly. In "Slot Groups" mode, only whole groups are moved. In "Slot Items" mode, this operation CAN move items to different groups.	Single or Multiple Selection.
Insert Slots ...	Brings up GUS to select slots to be inserted (generally) above the item. (When operated on a Divider Item in "Slot Groups" mode, new slots are inserted below the divider -- to be part of the divider's group; This, I think, will seem natural when you see it).	Single Selection
Insert Divider	Inserts a Slot Divider above the selected item. If in "Slot Groups" mode on a slot item, this effectively divides the slot item's group into two groups.	Single Selection
Remove	Removes the Selected Items. When operated in "Slot Items" mode on Divider (top-level) items, the children are not removed. Instead, they become "members" of the prior group. Note: The topmost item (always a divider) is never actually removed.	Single or Multiple Selection, except not enabled in "Slot Items" mode if only the first item (which is always a divider) is selected.
Create Similar Object Groups ...	Brings up the SimObj or Account GUS selector in multiple-selection mode, limited to the "base" class of the selected group. For example, when operating on a storage reservoir, GUS will allow the selection of reservoirs of any type -- not just storage reservoirs.	Single Slot Divider Selection on single-SimObj or -Account Groups.
Apply Order to Similar Groups	The order of slots in the single selected group is applied to other single-object groups having the same base type (e.g. all reservoirs for a reservoir). Slots in those other groups not represented in the selected group will retain their order relative to prior items which ARE in the selected group. Generally, the results will be best when the user operates on the object groups having the highest number of instantiated slots.	Single Slot Divider Selection on single-SimObj or -Account Group.
Sort Into Object Groups ...	Sort the selected items into multiple single-SimObj groups. Pre-existing dividers in the selection are removed.	Single or Multiple Slot Item Selection
Sort Into Account Groups ...	Sort the selected items into multiple single-Account groups. Pre-existing dividers in the selection are removed.	Single or Multiple Slot Item Selection
Open Item Close Item	Treeview top-level item "tree" controls. Context Menu Only; and shown only in "Slot Groups" mode on "Divider" (top-level) items.	Slot Divider Selections. Enabled when some selected items are not in the "target" open/closed state.
Open All Items Close All Items		Enabled when some selected items are not in the "target" open/closed state.
Done	Terminate the "Slot List Composition Mode" and revert the "Series Slot" tab to showing the actual Series Slot Data Table.	Always Enabled

(3.0) Development Tasks

(1) GUI Framework

1. Basic "EditSctSlotListPanel" QFrame class with a widget layout defined using Qt Designer (as a Qt4 "UI" file). This will contain basic controls (generally buttons and checkboxes) and a container widget for the Slot List QTreeView ("EditSctSlotListTreeView"). [This is a mostly technical task, and doesn't involve an actual determination of exactly which operations (see above) will be deployed as actual buttons].
2. An SctView subclass to manage the "EditSctSlotListPanel" within the SCT Dialog.
3. Add to the SCT Dialog's "Slot" menu: "Edit Series Slot List..." menu item.
4. Enhance the internal SctView switching mechanism to conditionally show the "EditSctSlotListPanel" in place of the Series Slot Data Table (which is itself a QStackedWidget which switches between four different SctViews -- for the different axis orientations and timestep aggregation modes).

(2) Slot List QTreeView -- Qt4 Model/View architecture based QTreeView

A full model/view based QTreeView is warranted for this application, requiring incell editing (for slot item label and divider text editing) and unforseen future GUI enhancements. The following classes will be developed:

• EditSctSlotListTreeView -- a QTreeView, encapsulating some low-level application list and tree functions.
• EditSctSlotListTreeView::SlotItem -- item data class ("POD" -- plain old data). Each instance will encapsulate a SctConfigSlotData record which describes the configuration for a Slot Item or Divider in the SCT.
• EditSctSlotListTreeView::ItemModel -- a QAbstractItemModel implementation
• EditSctSlotListTreeView::ItemDelegate -- a QStyledItemDelegate implementation

The EditSctSlotListPanel and EditSctSlotListTreeView classes will compose and modify an ordered list of SctConfigSlotData records which defines the slot and divider items within an SCT configuration. The latter will internally implement the lower-level operations which can be understood in the context of a list or tree of items, e.g. the "move up" and "move down" functions. The major development subtasks for the creation of the Slot List QTreeView and its supporting classes are:

• Some maintenance in the SctConfig class to allow access to its list of SctConfigSlotData records.
• Basic definition of the four classes (listed above).
• ItemModel implementation for the structure of the items in the two modes of operation.
• An item selection and selection persistence mechanism (based on application-level item instance handles).
• Incell editing (in the Slot and Divider Item Label column)
• Custom background color for dividers (using the currently set Divider Background color from the SCT configuration).
• Context menu implementation (basic implementation without actual operations).

See also Task 4 -- Basic List Operations -- also implemented in this QTreeView class.

(3) User Interface Design and Review

As previously described, various user operations will be implemented as either buttons or contentxt menu operations or both. One or more "proposals" for user interface design with regard to these controls need to be prepared and reviewed -- at least as screenshots, and possibly as a slightly functional prototype.

(4) Basic List Operations

The following operations will be implemented within the QTreeView (EditSctSlotListTreeView) and its supporting classes:

• Move Selected Items Up or Down in Slot Items mode (where items are shown as a list)
• Move Selected Item Groups Up or Down in Slot Groups mode (where slot items are shown as children of the preceding divider item).
• Insert Slots ... (using GUS slot selector)
• Insert Divider
• Remove (selected items)
• Open / Close TreeView Items (in Slot Groups mode)

(5) Advanced Group Operations

The following operations will be implemented within the EditSctSlotListPanel (rather than within the QTreeView class).

1. Create Similar Object Groups
2. Apply Order to Similar Groups
3. Sort Into Object Groups
4. Sort Into Account Groups

Some common tools will be developed for these operations to automatically characterize and maintain groups of slot items (defined as slot items under a divider item) as consisting of slots of one particular SimObj or Account instance.

(3.1) Development Estimates

--- (end) ---