RiverWare 6.6 Output Canvas / 12-23-2014 Merge from 6.7 Development
Phil Weinstein, David Neumann, Edie Zagona, CADSWES, edit 12-24-2014 (d)

Document History:

• 12-23-2014: Original draft.
• 12-24-2014: Writing revisions. Also minor functional change:
  • The new "Timestep" text item type will be allowed for both teacup and canvas text items. There is no fundamental reason to disallow that for teacup text items.

Overview:

Being that the RiverWare 6.6 release is postponed to early January 2015, we have decided to merge the latest Output Canvas development code to 6.6, but with 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. Text items in teacup groups are single-lines of text shown below the teacup label of each teacup. Most teacup text item types make use of one or two slots on the simulation object (or related data object) associated with the teacup. Teacup text items also include a "Legend Text" setting shown 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 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 teacup text item slot references, canvas text item slot references are "complete"; they do not make use of a simulation object reference.

As with all other Output Canvas objects, adding text groups and text items is done with the "Add" button in the configuration dialog's content panel.

• A text group can be added when the "General Settings" (topmost) configuration object tree item is selected.
• A canvas text item can be added when a text group is selected.

Text groups have these settings:

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

A new Timestep text item type was added. This shows the canvas' reference timestep date/time. As with all text item types (with the exception of plain text), timestep text items support optional prefix and suffix text.

Canvas text items support these text item types:

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

Slot values are displayed with units.

Teacup text items support one additional text item type: Percent of Maximum.

(2) Model Report support for Output Canvases

Model Reports now support Output Canvas items. This is similar to the model report support for (Pie-) Chart output devices. Output Canvas Model Report Items have these settings:

1. Output Canvas Name ... the name of 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, 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 readily changed with operation of the date time spinner or slider -- even in the Output Canvas Viewer dialog. When including an Output Canvas in a model report, a Date/Time should be specified in that 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 to Flow Lines in RiverWare 6.7).
    
• Selected Teacups are now shown with a dashed frame. Note that other Output Canvas graphics items -- for text, images and flow lines -- automatically show a similar selection ornament provided by the higher-level Qt4 QGraphicsItem subclasses used for those items. Unlike these other graphics item types, Teacups have custom-implemented drawing.
   
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 teacup group or text group.

(4) Item Position Lock Status Persistence

The configuration dialog presents 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 are meaningful for only 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 date/time.
    
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 "hidden" tree items (except on 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 with a 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 limited use in RiverWare) now supports a "model timestep" mode. This presents a date/time spinner using the "abridged / abbreviated" format omitting date/time components more precise than needed for the model timestep size, and with months displayed 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_EDIT 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:
   • Override background color
   • Override reference timestep date/time
      
5. Simplification of the Output Canvas configuration record's XML-generation functions. Those functions, to which there are many calls, were receiving the indentation size (number of spaces) 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:
    
   • static double slotValue (const Slot*, const Date_Time&, bool forMax, const ScaledUnitPtr);

--- (end) ---