Pie Chart Enhancements / April 2014 / RiverWare 6.5
Phil Weinstein, David Neumann, Edie Zagona, CADSWES, 4-30-2014

This document describes enhancements to RiverWare Pie Charts developed in April 2014 for RiverWare 6.5

Pie Chart Overview

Pie Charts are provided in RiverWare as the "Chart" Output Device. They are configured in a configuration dialog box. Within the Pie Chart dialog (which shows the actual pie chart graphic) a date/time spinner is used to specify the reference timestep for series data displayed in the chart. The chart can be printed or exported as an image file.

With a previously development enhancement for RiverWare 6.5, pie charts can be included in RiverWare model reports.

Developed Feature Summary

The following topics are described in subsequent sections in this document.

1. Timestep Animation / Slide-Show Support
2. New Display Options
3. Other Display Changes
4. Dialog Management and Geometry Improvements
5. Fixes
6. Reusable Software Components and other Software Enhancements
7. Previously developed Pie Chart Enhancements for RiverWare 6.5

(1) Timestep Animation / Slide-Show Support

Pie charts showing series data (various kinds of RiverWare series slots) depict only one timestep at any given time. Timestep animation automatically advances the pie chart's reference timestep at a constant rate. New controls associated with the pie chart's date/time spinner support this type of animation.

Apart from the Pie Chart enhancements described in this document, relevant enhancements were made also to the RiverWare date/time spinner. The forward and backward "step" (triangle arrows icon) buttons were changed from "up and down" to "left and right".   A menu button was added to date/time spinners used for "time navigation" (for various series displays rather than for configuration timesteps, e.g. in the Run Control dialog). Clicking that button shows a menu including the "Global Time Scroll" operation and shortcuts to assign the Run Start and Run Finish timesteps.

A new row of controls below the pie chart's date/time spinner support animation.

1. A slider control indicates where the current reference date/time falls within the series data's time range, and provides another way of moving to different timesteps. In the context of the Pie Chart dialog, this effectively provides a "manual" animation of the chart. During an automated animation, the slider "thumb" advances forward (to the right).
2. A Play/Pause push button starts and stops the animation. When playing, the button image changes to a "pause" icon.
3. An animation speed button graphically indicates the speed selection; (more horizontal bars in the button's icon indicates a faster animation speed). A tooltip on the button indicates the current frame period. Clicking on the button pops up a vertical slider to pick a different speed. (See the image below).

The following frame periods are supported: 0.1 seconds per frame 0.2 seconds per frame 0.5 seconds per frame 1.0 seconds per frame 2.0 seconds per frame 3.0 seconds per frame

(The latter three rates provide the experience of a "slide show" rather than an animation as such, but no technical distinction applies).

The animation stops when any of the following occur:

• The end of the time range is reached.
• The user clicks the play/pause button again.
• The dialog is hidden (minimized or closed).
• The user clicks either of the "step" buttons.
• The user selects "Run Start" or "Run Finish" from the date/time spinner menu.
• The user drags the animation slider thumb.

(2) New Display Options: The Pie Chart configuration dialog supports three new configuration settings. Background Color for Display (on-screen) Background Color for Image Export and Print Bolded Labels (for date label, slice labels and optional summary data). Clicking on the background color buttons brings up a color chooser dialog. (3) Other Display Changes: Numbers shown in the pie chart are conditionally shown with comma separators (depending on RiverWare's global "Show Commas in Numbers" setting). Radial scale circles (25%, 50%, 75%) are now dashed -- not solid lines. Optional summary statistics are now horizontally centered, rather than being shown in the bottom left corner.

(4) Dialog Management and Geometry Improvements:

Only one pie chart dialog is shown for any particular pie chart (output device) instance. Clicking "Generate" or "Apply" from the output manager or a pie chart configuration dialog just updates the corresponding pie chart dialog -- instead of showing a redundant one.

The pie chart dialog's visibility (e.g. "minimized" state) is now independent from the output manager and pie chart configuration dialogs.

The pie chart's auto-sizing and centering has been improved. Better image "stability" was needed especially for the new animation feature.

(5) Fixes:

The Gnats 5483 pie chart crashes have been fixed for RiverWare 6.4.8 and 6.5 (development). These two crashes had been readily reproducible in both builds:

1. In the Output Manager dialog, deleting a Chart Device while it's Configuration Dialog is open caused a crash.
2. Clearing the workspace (including when exiting RiverWare) while a Pie Chart Dialog is open caused a crash.

(6) Reusable Software Components and other Software Enhancements:

The following components and technical enhancements were developed in the course of implementing the pie chart enhancements.

(A) DateTimeSpinSlider is a new composite slider control (with two icon buttons) which can be "attached" to any RiverWare date/time (timestep) spinner.  The slider thumb provides an alternative way of changing the timestep value, and also graphically conveys the timestep value with respect to the full time series range.  This widget is also an "animation generator" which periodically advances the date/time (timestep) spinner. Included is a Play/Pause button and a popup slider control to select the animation speed. The placement of the DateTimeSpinSlider within a widget layout is up to the client (dialog box) -- so it could be next to the date/time spinner instead of below it (as it is in the Pie Chart dialog).

(B) The Pie Chart animation speed control is an example of popping up a QFrame containing a QSlider from a push button.  (The QFrame is helpful for the appearance of the slider, but it is also a place where additional controls could be provided).

(C) Technical: The DEVICE_DELETED callback from objects in the cwOutputDevice class hierarchy (all of the RiverWare output devices) can now be generated from the most-derived class' destructor. This insures that all subclass instance data is intact when that callback is received. This enhancement was helpful in resolving part of the Gnats 5483 dysfunctions described above.

(7) Previously developed Pie Chart Enhancements for RiverWare 6.5

(A) Support for pie charts in RiverWare model reports was developed in November 2013. The "Chart" report item type is a reference to an existing Chart output device (defined within the RiverWare model). This is included in a generated Model Report as a reference to a generated chart dialog image file built from the referenced Chart output device configuration. The width and height of the generated image are specified within the report item's settings.

(B) The pie chart configuration dialog's slot list now supports copy/paste as context menu operations. Slot references can be copied to or from the RiverWare slot clipboard. When copying slot references, their full names are also copied, as text, to the system clipboard.