Workspace Ornaments for RiverWare 6.5 / Initial Feature
Phil Weinstein, CADSWES, 10-30-2013, minor edits: 10-31-2013.

This document describes the initial implementation of a new workspace text and image "ornament" feature in RiverWare. There will almost certainly be revisions to this implementation before the actual RiverWare 6.5 release. (For one thing, we may choose to present this feature in the user interface by a different name).

(1) Functional Description

(1.1) Overview

Workspace Ornaments (WORKING TITLE) are images and multiple-line text objects added to the RiverWare workspace by the user.  Image Ornaments support optional tooltip text.  Workspace Ornaments:

• Are supported on the Simulation and Accounting workspaces. (i.e. not yet on the Geospatial workspace);
• Are saved in the RiverWare model file;
• Are not selectable, but are moveable (by dragging with the mouse pointer);
• Support a context menu with two operations: (1) "Edit..." and (2) "Delete" (with confirmation);
• Can be edited also by double-clicking them;
• Are drawn below all other RiverWare workspace graphics. (See below).
• Show text with the canvas' font and text color (same as simulation object labels), left-aligned.

(1.2) Ornament Creation

Workspace Ornaments are created using the "Add Ornament..." workspace context menu operation. This brings up the Ornament editor. The user may:

• add an image,
• enter text,
• or both. In this case, the text will be a tooltip on the image.

After adding an image or entering text, the Ornament text or image will appear on the workspace the first time the user clicks "Apply" or "OK".

(1.3) Operations on Ornament Objects

An ornament can be moved, edited, or deleted except in the following cases:

1. The workspace lock (in the bottom right corner) is on.
2. The RiverWare Viewer is being used.
3. The model is a Scenario Baseline model.

Except in these cases, the Ornament can be moved by dragging it with the mouse pointer, edited by double-clicking it or through the "Edit ..." context menu operation, and can be deleted with the "Delete" context menu operation (after a confirmation by the user).

Since Ornaments are not selectable, there are no operations on multiple Ornaments. Unlike simulation objects, multiple Ornaments cannot be moved or deleted in a single operation.

(1.4) Ornament Editing

The Ornament Editor dialog supports the editing of a single Ornament instance. Changes appear on the workspace when clicking the "Apply" or "OK" buttons. (The Ornament on the workspace is deleted at that time if no text or image is defined).

To add an image, click the "Add Image" button. This shows the image editor panel. Notice that the "Ornament Text" panel title changes to "Ornament Text (Tooltip"). Clicking "Choose Image ..." brings up a file chooser dialog. Any GIF, PNG or JPG image can be chosen. When a valid image file has been loaded, its width and height (in pixels) and the image file (in bytes) are indicated. Clicking "Clear Images" removes the image from the Ornament.

(Note: The "Test" menu item visible in these screenshots will not be shown in the actual release).

(2) Technical Notes

Image Data stored in RiverWare Model Files.

This is the first time images are saved in the RiverWare model file. The raw image data which was read from the image file picked by the user is precisely maintained, without modification. Transparent pixels and the alpha channel (partial transparency) are preserved and are supported in the RiverWare workspace. This initial implementation places no limits on the dimensions nor size (in bytes) of Ornament images.

The image is encoded for the RiverWare model file in a standard variant of Base64 (RFC 2045) with 64 characters (bytes) per line. This is embedded in an XML element. Base64 encodings are fundamentally 75% efficient (6 bits of binary data in every byte).

The box to the right presents an example of a RiverWare "User Image Data" XML element with Base64-encoded image data.

New Source Code Modules

The following C++ module files were added to support the new Workspace Ornaments feature:

NEW MODULES: DATA MODEL
  Sim\Ornament.cpp
  Sim\Ornament.hpp
  Sim\OrnamentMgr.cpp
  Sim\OrnamentMgr.hpp
  Sim\UserImageData.cpp
  Sim\UserImageData.hpp

NEW MODULE: ORNAMENT EDITOR
  Q3GUI\OrnamentEditorDlg.cpp
  Q3GUI\OrnamentEditorDlg.hpp
  Q3GUI\OrnamentEditorWidgets.ui

NEW MODULE: Qt4 GRAPHICS ITEMS
  QtUtils\OrnamentGfxItem.cpp
  QtUtils\OrnamentGfxItem.hpp

--- (end) ---