Workspace Text and Images for RiverWare 6.5 / Bake 2
Phil Weinstein, CADSWES, 11-6-2013

This document describes a revised implementation of the new workspace text and image feature in RiverWare.

The initial (prior) development version presented workspace text and images as a single type of graphical object. Workspace "ornaments" were capable of either having an image or not.

(1) Functional Description

(1.1) Overview

Workspace images and text objects are added to the RiverWare workspace by the user. These new types of graphical workspace objects ...

• 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).
• Workspace text objects show text with the canvas' font and text color (same as simulation object labels), left-aligned.
• Workspace images support optional tooltip text.

(1.2) Workspace Text and Image Creation

Workspace text objects and images are created using the "Add Text..." and "Add Image..." workspace context menu operations. This brings up the corresponding editor to give the text object or image its initial content.

After entering text or picking an image, the text or image will appear on the workspace the first time the user clicks "Apply" or "OK". Clicking "Cancel" before clicking "Apply" will effectively abort the text or image creation operation.

Unlike simulation objects which appear on all three workspaces (albeit at different locations), workspace text objects and images appear only on the workpace in which they were created.

(1.3) Operations on Workspace Text Objects and Images

A workspace text object or image 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.

Otherwise, the text object or image 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 workspace text objects and images are not selectable in this initial implementation, there are no operations on multiple instances. Unlike simulation objects, multiple text objects and images cannot be moved or deleted in a single operation.

(1.4) Workspace Text Editing

The Workspace Text Editor dialog supports the editing of a single Workspace Text instance. Changes appear on the workspace when clicking the "Apply" or "OK" buttons.

(1.5) Workspace Image Editing

The Workspace Image Editor dialog supports an image file import operation for a single Worksace Image -- plus the editing of an optional tooltip to be presented with the image on the workspace. Changes appear on the workspace when clicking the "Apply" or "OK" buttons.

To pick an image, click the "Choose Image..." button. This brings up a file chooser dialog. Any GIF, PNG or JPG image can be chosen. Transparency (transparent pixels or a full alpha channel) are supported on the workspace. However, the animation in GIF image files is not supported.

Note that Workspace Images are distinct from the Workspace's background image. One important functional difference is that the background image cannot be repositioned by dragging it with the mouse pointer. Also, background images are not saved inside the model file (as are the new workspace images); only a reference to an external image file is currently supported for background images. (The following "Technical Notes" section provides more information about the saving of images in model files).

(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 Workspace 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 Text and Image features. Note that all provisions for these two new features (text and images) use common "Ornament" classes for all levels of implementation: data model, editor dialog, and graphics item.

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) ---