RiverWare 6.1: Supporting
User-Descriptions on Non-Data Objects and Slots
Phil Weinstein -- CADSWES
User-supplied descriptions -- multiple-line comments -- are currently supported on Data Objects and their Slots. We would like to extend this support to all types of Simulation Objects and their Slots. Also, it is desirable to make the descriptions more accessible, with an indication that a user-defined description actually exists on the particular Object or Slot.
The Open Object dialog shows a "Description" tab when showing a Data Object. This could also be shown for all the other types of Simulation Objects. Also, an Icon could be added to that tab to indicate that a description is defined for the object. See more below.
There are two precedents for description-related controls (other than the existing View-menu operations) in the Slot dialogs.
Ideally, we would consistently apply new "Description" controls to all the varieties of Open Slot dialogs. But we importantly need to refrain from cluttering these dialogs with GUI controls for the less important features. The "RowOToggles" panel may not be appropriate for dialogs which don't already have important checkboxes deployed in that panel. It's unlikely that a "Description" toggle will be important enough to warrant the addition of a whole new control row -- but it does look good in the Open Slot dialogs with RPL expressions, which are already sufficiently complex to warrant that additional user interface complexity. There are other view options for which a checkbox would be considered -- but on close analysis, none of them are really important enough to actually display in a "RowOToggles". Having them "tucked away" under the View menu is very appropriate.
In devising a consistent way of providing this feature on all Slot dialogs (to the extent to which we choose to do that), we could also consider consistently adding the "Configure Slot" (gear) icon button and the Plot icon button. The "Configure Slots" (gear) icon is currently supported only on the Scalar Slot dialogs. And the dialogs for Table-like Slots are all lacking the Plot icon button.
These current screenshots from RiverWare 6.1 development show that the Open Object dialog only for Data Objects has the Description tab.
We will show this tab on all Open Object dialogs. We can consider putting a special "Description" icon on the tab when there is a description defined on the object:
MOCKUP
|
Slot dialogs for Slots on Data Objects currently include either an "Add Description..." or "Show Description" menu item under the View menu -- depending on whether the Slot has a description. (BTW, I'm now seeing that only one of these show an ellipsis. Maybe there's a rationale for that, but that should be reconsidered). These menu items would, of course, be available in all Open Slot dialogs -- not just for slots on Data Objects.
If we do standardize on use of the icon button currently used in the Scalar Slot dialogs (see below), that icon should probably be added to the "Add Description" and "Show Description" menu items.
As mentioned above, the Scalar Slot dialogs also currently support an icon button to show the Description panel. This supports a tooltip showing the description text, but there is no other indication that the Slot actually has, or doesn't have, a description. See the button in the bottom-right. The "gear" icon button in the bottom-left is also unique to the Scalar slot dialogs. Clicking that icon brings up the Scalar Slot Configuration dialog -- in which the display format is set -- relevant for of the Scalar display value shown next to that button -- e.g. the units and the number of fractional digits displayed.
Notice the "Show: [X] Comments" checkbox in the RPL-related Slot dialogs above and below. This is the "RowOToggles" recently introduced by Patrick. (Its drawn frame indicates that Slot's RPL expression actually has comments).
The TableSlot, Periodic Slot, and Statistical Slot Dialogs don't really support controls similar to the new one we're wanting to add. They lack "Plot" (and also "Configure") buttons -- so maybe this is an opportunity to add those as well.
 |
 |
Looking just at the Open Series Slot dialogs, it would seem reasonable to add a "Description" icon button -- possibly shown only when a description actually exists on the Slot. The thing is, the button row is already crowded. In general, we don't want to widen, nor overly complicate these dialogs. Here are current screenshots, the one on the right showing the conditionally-shown Series Note menu button -- used to navigate to the individual note timesteps defined on the Slot. (Also see the similar Series Slot with RPL-expression dialog above).
Here is a mockup showing a possible "Description" icon button. As suggested above, perhaps it would be shown only if a description is defined on the Slot.
MOCKUP
|
I haven't proposed a particular recommendation. I do worry that adding a whole row of controls (the "RowOToggles") may be too prominent an addition for this particular feature in most of these Slot dialogs. And adding that to the Scalar Slot with RPL Expression dialog would be redundant with the currently implemented "Description" icon button. There doesn't seem to be an obvious elegant approach which would be consistent across all Slot dialogs. This needs some more consideration.
A motivation for adding the user-supplied description capability to all slots -- and a visible indication in slot dialogs that a user-supplied description for the slot is defined -- is a desire to flag certain slots as having mockup data (in a current project at CADSWES).
It might be very useful to generalize the "Find Series Slots with Inputs" dialog as a "Slot Finder" to also support enumerating slots with user-supplied descriptions. It would support these different modes:
The "Find Slots with User-Descriptions" mode could support a text filter, to limit the enumerated slots to those having a description containing filter text (specified in a line edit widget).
In the "Find Slots with User-Descriptions" mode, a list column could be shown having the description text -- possibly limited to the first 80-or-so characters.
Of course, the new User-Description mode wouldn't be limited to Series Slots (as the current "find inputs" capability is).
With this feature, it would be reasonable to implement User-Description control on slots only through slot dialog menu items (which are already implemented, but currently made available only for Data Object slots). We wouldn't have to add any icon buttons -- or the "RowOToggles" panel -- to the various slot dialogs. This avoids the need to work out a design change across all the different slot dialogs.
Technical: The "Find Series Slots with Inputs" makes use of a Slot "RootFilter" -- part of the RootSelection architecture. The most direct way of implementing filtering based on User-Description text would be to add another RootFilter to support that. So, basically for "free", this new filtering capability would be available also in the "GUS" (grand unified selector) Slot Selector.
---
