RiverWare 6.7 DMI Configuration Script Action Support / May 2015
Phil Weinstein, David Neumann, Patrick Lynn, Bill Oakley, Edie Zagona, CADSWES
Original Draft: 5-28-2015. Updated: 6-04-2015.

Overview

This document describes two related enhancements to RiverWare 6.7, and addresses related implementation topics:

  1. Excel Dataset Configuration: Configurable list of Single Run Names
  2. New Script Action: Set Excel Dataset Run Name
  3. Technical Enhancements
  4. Known Issues

Document Status:

 

     

(1) Excel Dataset Configuration Enhancement

The Excel Dataset Configuration has been enhanced to support a user-configurable "standard" list of Single Run Names. The "Single Run Name" line entry widget has been replaced with an option menu showing those standard names. The user can still directly edit the Single Run Name text without regard to the standard name list.

 

    

An Excel Dataset's standard Run Names list is edited by clicking the new associated ellipsis button. This brings up the Edit Run Name List dialog which supports the following operations:

  1. Add a new Run Name, with the green plus button. This is enabled only if the entered text does not already exist in the list.
  2. Change an existing Run Name element, with the "Apply" button.
  3. Move multiple selected Run Names up or down in the list, with the up and down arrow buttons.
  4. Delete multiple selected Run Names from the list, with the red "X" button.

Additionally, the following operations are provided in a context menu -- (illustrated later in this document):

  1. Copy items to clipboard (all or selected items)
  2. Paste items from clipboard (append or replace all)
  3. Sort and Reverse Order

The clipboard copy/paste operations support copying a standard Run Names list between different Excel Datasets. (This works even between Excel Datasets in different run instances of the RiverWare program).

See the following document for more information about the Edit Run Name List dialog (an instance of our new String List Editor dialog):

Utility Dialog: String List Editor / RiverWare 6.7 / May 2015
R:\doc\guiGeneral\Utilities\StringListEditor-May2015.docx

This list of Run Names shows up in the following places:

  1. In the Excel Dataset Configuration Dialog's Single Run Name option menu
    -- and of course in the associated Edit Run Name List editor (as described and illustrated above).
  2. In the new script action's configuration settings (see below).
  3. In the new script action's item in the Script Dashboard (see below).

    

(2) New Script Action: Set Excel Dataset Run Name

A new DMI configuration-related script action type has been developed for RiverWare 6.7. There are now approximately 38 different script action types. The new "Set Excel Dataset Run Name" action modifies the following two properties of a named Excel Dataset configuration within the current RiverWare model:

  1. Run Name Type, with three options:
    1. Single Run Name
    2. Run with MRM number
    3. Trace with MRM trace number

  2. Single Run Name

The "Set Excel Dataset Run Name" script action supports these five settings:

  1. Show in Dashboard
  2. Display Text
  3. Excel Dataset
  4. Run Name Type
  5. Single Run Name

The first two settings are common to all script actions.

The "Excel Dataset" setting supports an Excel Dataset selection option menu which shows the names of all Excel Datasets in the loaded RiverWare model. The user can either pick one of those dataset names or just enter the desired dataset's name.

The "Run Name Type" setting supports an option menu with the three Run Name Type options enumerated above. When the script action is executed, the specified Excel Dataset's Run Name Type is set to the selection specified by this setting.

The "Single Run Name" setting is shown only if that Run Name Type is selected. It supports an option menu which includes the "standard" run names configured within the selected Excel Dataset (plus the currently entered value, if that's not represented within the list of standard run names). The user can either pick one of those names or just enter the desired run name text. When the script action is executed, if a non-empty run name is provided (and the Run Name Type is "Single Run Name") then the specified Excel Dataset's Run Name is set to this setting's value.

When a script including a "Set Excel Dataset Run Name" action instance is shown in the Script Dashboard dialog, if the action's Run Name Type is "Single Run Name", an editable option menu is provided to allow the Script Dashboard user to enter or select a different run name to be used during action execution:

Operating the Script Dashboard's Edit >> "Reset Values" menu item restores the run name field to the action's configured setting, i.e. what was entered or selected in the Script Editor dialog.

In the current implementation, the Excel Dataset configuration dialog -- for the dataset being affected by this script action -- must be closed during script execution. Otherwise, the script aborts.

(3) Technical Enhancements

In the course of this feature development, the technical and GUI enhancements listed below were implemented.

    Revision [6-4-2015]: The script action's Excel Dataset Single Run Name setting was changed from an rwEnumSetting to an rwTextSetting with the new EXCEL_DATASET_RUNNAME value type. Also, new general provisions to support the required dynamic generation of the original rwEnumSetting implementation have been removed. That rwSetting subclass should support only constant, static enumerations; its prior support for dynamic RPL Set enumerations should also be moved to rwTextSetting.

  1. rwTextSetting "EXCEL_DATASET_NAME" value type. Editor QComboBoxes are populated with the names of the existing ExcelDatasets in the currently loaded RiverWare model.
     
  2. rwTextSetting "EXCEL_DATASET_RUNNAME" value type. Editor QComboBoxes are populated with the "Common Run Names" from a named ExcelDataset, based on a sibling or inherited EXCEL_DATASET_NAME reference rwTextSetting.
     
  3. New Script Dashboard Action Control (widget) -- a QComboBox for Enums (enumerations) displayed in the dashboard. Both rwEnumSettings and rwTextSettings are supported. However rwTextSetting support is currently limited to the EXCEL_DATASET_RUNNAME value type (see the next item). [class rwScriptDashboard::EnumControl (an ActionControl)]. This Action Control is used by having rwScript::Action return (in the reference parameter) the relevant a rwEnumSetting or rwTextSetting from one of these two methods:
     
  4. Prototype "rwTextSetting::options()" method for the generation of dynamic enumerations -- intended for editable QComboBoxes in both the Script Dashboard and the Script Editor. The method is given a list of "reference" rwSettings to parameterize the option list generation. That list potentially consists of both sibling and inherited rwSettings.

    5. NOTE: The only rwTextItem value type currently supported is EXCEL_DATASET_RUNNAME. The idea is that we will soon MOVE the enumeration generation implemenations from the rwSettingTree::Delegate::createEditor() [GUI] method to this rwTextItem method for all relevant rwTextSetting value types.

  5. Support for asynchronous changes to special DMI objects. In RiverWare the edit state of DMI objects is very tightly managed, in order to prevent conflicting configuration changes initiated from different places in the DMI GUI. Before this enhancement, it was not possible for some other agent (e.g. a running Script Action) to change a DMI Dataset configuration.
     
  6. Two general support dialogs were developed (as two modes of a single GUI dialog class) for editing or (only-) reordering items in a string list. See the new QtUtils/StringListEditDlg class. Below are sample uses of these two support dialogs:
            

As previously noted, these utility dialogs are described in this document:

Utility Dialog: String List Editor / RiverWare 6.7 / May 2015
R:\doc\guiGeneral\Utilities\StringListEditor-May2015.docx

(4) Known Issues

As previously mentioned, the new Set Excel Dataset Run Name script action will abort if the referenced Excel Dataset's configuration dialog is open. (The abort message clearly describes the need to close that dialog).

[As of 5-28-2015] there was a little instability in the DMI's edit state management mechanism. This includes issues documented in the following two bug records:

Update [6-04-2015]: Some other edit state fixes have been applied which seem to address the instability problems encountered specifically in the course of operating these new Excel Dataset and Script Action features.

--- (end) ---