RiverWare 6.6 Output Canvas / 12-23-2014 Merge from 6.7 Development
Phil Weinstein, CADSWES, 12-23-2014

Being that RiverWare 6.6 release is being postponed to early January 2015, we have decided to merge the latest Output Canvas development code to 6.6, but with the Flow Lines not exposed. This document outlines the functional and software engineering additions to 6.6 in this merge. (Flow Line provisions are not covered).

  1. Canvas (free-standing) Text Items
  2. Model Report support for Output Canvases
  3. Config Dialog Selection Synchronization
  4. Item Position Lock Status Persistence
  5. Minor Functional Enhancements
  6. rwSetting Technical Enhancements
  7. General Technical Enhancements

Note: Flow Line creation is disabled in RiverWare 6.6 with this symbol in Sim/OutputCanvasConfig.hpp:
  enum { Create_FlowLines_Enabled = 0 }; // bool, Release 6.6: 0 (false)

(1) Canvas (free-standing) Text Items

There are now two types of "Group" objects to which Text Items can be added.

  1. Teacup Groups. The text items in a teacup group are single-lines of text shown below the teacup label within each teacup object. Most text types of text items within a teacup group make use of one or two slots on the simulation object (or associated data object) associated with the teacup. These items also include a "Legend Text" setting used in the optional teacup legend graphics object.
     
  2. Text Groups (NEW). These are for free-standing ("canvas") text items -- single-lines of text shown on the canvas. Text item visibility (toggle) and text font are defined at the text group level. Text color and text composition (supported with a handful of text types) are defined at the text item level. Unlike slot references in text items under teacup groups, slot references for canvas text items are "complete"; they do not make use of a reference to a simulation object.

The user can now define multiple "Text Groups", each of which can contain multiple Text items. As with all other Output Canvas objects, this is done with the "Add" button in the configuration dialog's content panel.

Text Groups support the following settings:

  1. Name
  2. Show ... Yes or No
  3. Font

A new "Timestep" text item type is now supported. This can be added to only Canvas Text items (not Teacup Text items). This shows the canvas' reference timestep date/time. The user can specify optional Prefix and Suffix text (as with all other text item types except for "Plain Text"). Canvas Text Item types are:

  1. Plain Text
  2. (slot-) Value
  3. (slot-) Value / (slot-) Value
  4. Percent (a slot value divided by another slot value)
  5. Timestep

(2) Model Report support for Output Canvases

Model Reports now support "Output Canvas" items. This is somewhat similar to the model report support for (Pie-) Chart output devices. The Output Canvas Model Report Item supports the following settings:

  1. Output Canvas Name ... reference to an existing Output Canvas (an output device within the current model).
  2. Title ... shown as text in the HTML model report
  3. Date/Time ... optional reference timestep. If this is left blank, the Output Canvas' own reference timestep is used*.
  4. Max Width (pixels)
  5. Max Height (pixels)

An image file is generated for the Model Report (an HTML document) which is either the Output Canvas' natural size or smaller, as a function of the "Max Width" and "Max Height" settings. If the natural size exceeds either of those limits, the image size is reduced to respect those limits, preserving the original Output Canvas' aspect ratio.

*In the current Output Canvas implementation (e.g. in RiverWare 6.6), an Output Canvas' reference timestep is quite ephemeral; it is changed whenever the user operates the date time spinner or slider -- even in the Output Canvas Viewer dialog. In practice, when including an Output Canvas in a model report, a Date/Time should be specified within the model report item's configuration.

(3) Config Dialog Selection Synchronization

  1. Selecting a configuration tree item causes the corresponding graphics item in the preview canvas to become selected (i.e. show selection ornamentation). The selection ornamentation is currently, in all cases, a dotted frame drawn around the item. This applies to Teacups, the Teacup Legend, Text Items, and Images. (Also Flow Lines in 6.7).
     
  2. Graphics items in the configuration preview canvas now have a "Configure..." context menu operation which causes the corresponding configuration tree item to be selected. Note that certain graphics item display attributes are established at the "group" level -- i.e. within the group item containing the configuration item. For example, the font specification for a text item is defined within the containing text group.

(4) Item Position Lock Status Persistence

The configuration dialog dialog shows these two checkboxes below the preview canvas:

Lock Positions:  [x] Background Images  [x] Other Items

The states of these checkboxes are now persistent; they are saved in the Output Canvas output device configuration -- independently for each instance.

(5) Minor Functional Enhancements

  1. The delay before updating the configuration dialog's settings panel was significantly reduced. (That delay is used to condense multiple rapidly generated update requests into a single update operation). The delay was reduced from 250 milliseconds to 20 milliseconds. So now, item position and reference timestep changes -- made by dragging a graphics object or date/time slider -- result in rapid and virtually immediate updates to the corresponding settings fields.
     
  2. The Teacup Legend had mistakenly shown "Open Object..." and "Plot Slots..." context menu operations. Those were meaningful only on actual Teacup objects.
     
  3. An output canvases' Reference Timestep setting is now shown in a more natural format taking into account the model timestep size. This is consistent with the display of that value in the date/time spinner and in output canvas text items showing that reference timestep.
     
  4. Simplification of the presentation of certain items within the configuration object tree. We eliminated "(shown)" and "(hidden)" on certain hideable item types. This is mostly redundant with the cross-hatch pattern drawn on those tree items (except for the single selected item).

(6) rwSetting Technical Enhancements

  1. "Model Date/Time" rwSettings (e.g. the reference timestep date/time in pie charts and output canvases in model reports) are no longer editable only with an unconstrained text editor. There is now also an ellipses button which brings up a date/time editor popup dialog which presents the date/time spinner configured for model timesteps.
     
  2. rwSettingTree Fix: The output device selector popup window (for output device reference settings) was including among the existing output devices the "_RWSAVED" temporary edit copies which exist when an output device's configuration dialog box is shown.
     
  3. rwSlotValSettings (slot value settings) were significantly enhanced to support acquiring display attributes (units and precision) from a sibling unit type rwSetting instance instead of from a sibling slot reference rwSetting instance. (This was done to support a particular Flow Line provision, but could be used for specifying maximum teacup values within in each teacup configuration -- as an alternative to using a slot reference).

(7) General Technical Enhancements

  1. The date/time entry popup dialog (which has very limited use in RiverWare) now supports a "for model timestep" mode which presents the spinner using the "abridged / abbreviated" format which omits date/time components which are more precise than what it needed for the model timestep size, and presents months as three letter abbreviations. [See static method: DateTimeQtSpinner:: getDateUsingModalDlg()]. This is now used for the reference date time in:
     
    1. Model Reports: (Pie-) Chart reference timestep.
    2. Model Reports: Output Canvas reference timestep (NEW).
    3. Output Canvas configuration reference timestep (NEW).
       
  2. The Output Canvas configuration dialog now registers for callbacks from the SimWorkspace, and updates the setting panel in response to the WS_ACT_USCHEME_SWITCH and WS_ACT_USCHEME_SWITCH callbacks. This is important for rwSettings which present real values with unit scheme-based display attributes (units and precision).
     
  3. All Output Canvas graphics items now have a working context menu. (They all have at least the new "Configure..." context menu operation).
     
  4. The OutputCanvasScene's "generate pixmap" (image) function now has the following optional parameters:
  5. Simplification of the Output Canvas configuration record's XML-generation functions. Those functions, to which there were many calls, were receiving the number of spaces to be used for indentation as a parameter. That value is now defined as a symbolic constant.
     
  6. The slot-value lookup algorithm previously used in only teacups was made more generally available within the Output Canvas configuration code, in a static method defined at the OutputCanvasNode level:
     

--- (end) ---