Proposal: Workspace Barebones Ornaments for RiverWare 6.5
Phil Weinstein, CADSWES

This document describes the development of a minimal capability to show text and small images ("ornaments") in the RiverWare Simulation and Accounting workspaces.

(0.1) Document History

• 10-22-2013: Initial design submitted for review, but put aside (see below).
• 10-23-2013: Ready for Review

(0.2) Note about prior proposal

See this document:

• R:\doc\workspace\ornaments\WsOrnamentsProposal.docx

We are initially going to complete a "barebones" implementation of the prior proposal. The differences are summarized here. As time permits, we may be able to add back in a few of the removed features.

(A) Additions:

• This will be available on the Similation and Accounting workspaces. (Not just the Simulation workspace).
• Image Ornaments will support user-supplied "tool tip" text -- that is, text in a popup window that is momentarily displayed when hovering the mouse pointer over the image.

(B) General Omissions:

• No central hiding of ornaments.  If they are created, they appear, until deleted.
• No involvement with the SimObj Palette.  We'll just use workspace context menus for ornament creation.
  
• No application selected state / no operations on multiple ornaments. Ornaments can be individually deleted with a context menu operation.
  

(C)  Text Ornament Omissions:

• No "minimized" state.
• No custom font settings.  We'll just use each workspace's configured font and text (/label) color.
• No text alignment or anchor settings.
• No rich text.  I won't take time to ensure that enabling rich text in the QTextEdit has no problems.

(D) Image Ornament Changes:

• No rescaling of images.  They will be displayed at their natural size.  But of course they will automatically scale when zooming in or out (as are SimObj icons).
• Images WILL be saved in the model. This has a lot fewer "moving parts" than dealing with file paths, as outlined in the original proposal.  Also will be more convenient for users. For an efficiency concern, transparency won't be supported.  It will be prudent to limit the dimensions of the supported images.  We wouldn't have to fix both dimensions; the imposed limit could be defined as either the sum or product of the two dimensions

(0.3) Open Issues

1. Since text is now associated with both Text Ornaments and Image Ornaments, we might instead present this feature in the user interface as a single feature, "Workspace Ornaments" with an optional image. If the ornament has an image, the image is displayed on the workspace instead of the text -- and the text is shown only as a tooltip (if text is provided for that ornament). Note: Regardless of this decision, I'm planning on implementing this as a single "Ornament" class at the data model level and a single OrnamentGfxItem (graphics item) class for the workspace GUI.
    
2. Especially since we are saving Ornament images within the model file, but also for usability considerations, we'll want to enforce an image size constrant. Technically, the most relevant criteria would be the image's area (product of width and height). But the size consideration isn't that precise. I propose we limit images to those with a width plus height of no more than 240 pixels. (So, both 120x120 and 60x180 pixel images would be acceptable). [Note that our standard SimObj icons are 40x40].

(1) Requirements Overview

Users will be able to add multiple-line text blocks and images to specific locations within the RiverWare Simulation Workspace. The following requirements are for the initial version of this feature; future enhancements are possible.

(1.1) General Ornament Requirements:

1. Each ornament has either text or an image optionally with a text tooltip.
2. Ornaments are automatically scaled with the workspace -- as are, for example, simulation object icons.
3. Creating, editing, moving, and deleting ornaments is disabled:
   1. when the workspace icon lock is on.
   2. in RiverWare Viewer mode or in a Baseline model (for Scenario users).
4. When enabled, ornaments can be positioned by the user by dragging them with the mouse.
5. Ornament editors for multiple ornaments can simultaneously be shown.

(1.2) Text Ornament Requirements:

1. Text ornaments are edited in a separate dialog (not "inline" directly on the workspace). The text ornament editor is shown by double-clicking an ornament and with an "Edit..." context menu operation.

(1.3) Image Ornament Requirements:

1. An Image Ornament's image is loaded from an image model file, and is saved in the model file.
2. Supported image formats include PNG, JPG, GIF.
   

(2) Functional Description

(2.1) Creating a New Text or Image Ornament

In models where model editing is enabled (see Requirements) and when workspace icons are not locked, controls for adding the two types of workspace ornaments will be available in the Simulation and Accounting Workspace context menus:

• Add Text Ornament ...
• Add Image Ornament ...

These actions bring up the editor dialog for the type of ornament. Clicking "OK" or "Apply" creates the Ornament instance. Clicking "Cancel" before having clicked the "Apply" button will effectivly abort the Ornament creation operation.

(2.2) Operations on Selected Text and Image Ornaments

Because neither an application-level selection nor a "selected" Ornament appearance will initially be implemented, Ornaments will not be selectable. (They could be made to be selectable in the future). But they can be moved (by dragging them with a mouse pointer), and they will support a context menu. This will include:

• Edit ...
• Delete

Deletions will be confirmed with a confirmation dialog box.

(2.3) Editing Text Ornaments

A text ornament can be edited by double-clicking and with the "Edit..." context menu operation. This brings up a "Text Ornament Editor" dialog box. This dialog box includes:

• A multiple-line text editor (a QTextEdit widget).
• Bottom buttons: OK, Apply and Close/Cancel. (The latter button shows "Cancel" only if un-applied changes have been made to the item's text).

(2.4) Editing Image Ornaments

An image ornament can be edited by double-clicking and with the "Edit..." context menu operation. This brings up a "Image Ornament Editor" dialog box. This dialog box includes:

• An image display, with image width and height indications, in pixels.
• A "Choose Image..." button which brings up an image file chooser dialog.
• A multiple-line text editor (a QTextEdit widget) for the image's optional tooltip.
• Bottom buttons: OK, Apply and Close/Cancel. (The latter button shows "Cancel" only if un-applied changes have been made to the item's text).

A splitter control will exist (albeit, invisibly) between the image controls and the tooltip text editor.

(3) Development Tasks

1. Proposal and Development Planning (this and prior document).
2. Data Model: implementation, with basic data serialization (excluding image serialization).
3. New Dialog: Ornament Editor
4. Data Model: Image Serialization
5. Ornament Graphics Items
6. Completion Testing, including Print and Image Export Testing
7. Developed Feature Documentation
   

(3.1) Proposal and Development Planning

This task accounts for the writing of this, and the prior design document. See:

• R:\doc\workspace\ornaments\WsOrnamentsProposal.docx

(3.2) Data Model: implementation with basic data persistence (excluding image serialization).

An "Ornament" class will be defined in the RiverWare Sim library. It holds all of the persistent data for one text or image ornament. The set of Ornaments defined in the model will be managed the SimWorkspace. Ornament supports an XML-based serialization, which will be embedded in the Tcl-encoded model file serialization.

Unlike simulation objects (SimObj), Ornaments are associated with one particular workspace, e.g. "Simulation" or "Accounting". However, distinct coordinate fields will be maintained for each of the canvases to reduce potential confusion.

The Ornament data includes:

• workspace canvas ID (CanvasID)
• simulation canvas coordinates
• accounting canvas coordinates
• primary text
• tooltip text
• image (QPixmap)

Ornament and the Workspace support callback-based model change notifications for Ornaments. Initially defined callbacks include:

• ORNAMENT_DELETED
• ORNAMENT_CHANGED
• ORNAMENT_MOVED_SIM  (repositioning within the Simulation workspace).
• ORNAMENT_MOVED_ACC  (repositioning within the Accounting workspace).

(3.3) New Dialog: Ornament Editor

The Ornament Editor dialog edits a single Ornament instance. Regardless of whether we present a single type of Ornament Editor Dialog or distinct dialogs for the two types of Ornaments (See "Open Issues"), they will be implemented within a single C++ dialog class.

See also Section 2.3: Editing Text Ornaments and section 2.4: Editing Image Ornaments.

The unapplied edit states will be represented within the dialog widgets. "Applying" edits causes those states to be set on the underlying Ornament instance.

When picking an image file with a file chooser dialog, we will want to enforce an image size limit (TBD). This is a feature usability issue (it wouldn't make sense to allow users to display huge images in an ornament), but also a practical matter of excessive size (in bytes) for saving the image within model files. Aside from this enforced size constraint, it may make sense to not require the Ornament Editor dialog to be large enough to show the entire image -- we'll show the image in a QScrollArea, with scrollbars visible only when necessary.

Subtasks include:

• Providing a "hook" from the Simulation and Accounting Workspaces' context menus.
• Widget layout using Qt Designer.
• Setting the state of the edit controls (widgets) from an Ornament instance.
• Saving the state of the edit controls (widgets) to an Ornament instance.
• Conditioning of the "Apply" and "Cancel/Close" states.
• Registration for, and handling of the Ornament's ORNAMENT_DELETED callback. (This will just close the dialog box).
• Semi-persistent editor dialog size and location implementation (just within a single RiverWare session).
• Picking an image file with a file chooser, confirming size constraint.

(3.4) Data Model: Image Serialization

The Image associated with an Ornament is saved with the Ornament in the model file. The image is saved in a "base64" encoded serialization. We have not actually done this before, but this is a pretty common thing to do. (Examples of how to do this are readily available). We'll want to experiment with this particularly with an eye towards image size (in serialized bytes). Probably the serialized image will use the PNG format with 85% resolution; this seems to enable normal loss-less compression which is possible for images having solid blocks of color.

(3.5) Ornament Graphics Items

Ornaments (both Text and Image Ornaments) are implemented as custom Qt4 QGraphicsItems within a QGraphicsScene subclass (and displayed within a QGraphicsView subclass). These will be implemented in parallel with the QGraphicsItems for simulation objects. (We'll actually use our RwGraphicsItem as a base class). The implementation is similar to that of the SimObjGfxItem class (i.e. the part of this class' implementation for the simulation workspace).

An OrnamentGfxItem will manage text and image child graphics items. In the initial implementation, only one will be deployed at any given time. The text component is implemented with a QGraphicsTextItem. The image component is implemented with a QGraphicsPixmapItem.

In this initial implementation, a "selected" state will not be supported. No special appearance for that state will be provided.

Subtasks include:

• Definition of a OrnamentGfxItem (a RwGraphicsItem subclass).
• Composition of a child QGraphicsTextItem and a QGraphicsPixmapItem.
• Computation of the OrnamentGfxItem's bounding rectangle and shape (these are similar, but play different roles in the appearance and behavior of the graphics item).
• Registration for, and handling of callbacks generated by the Ornament instance, including for geometry recomputation, updating and deletion.
• Handling of QGraphicsItem events, such as mouse move and click events.
• Context Menu: Initially just "Edit..." and "Delete".

Related general tasks include:

• General workspace provision for insuring that all Ornaments are within the Workspace's coordinates.

(3.6) Completion Testing, including Print and Image Export Testing

Code changes are not anticipated for correct Print and Image Export operations. But this will need to be tested, and any problems found will need to be addressed.

(3.7) Developed Feature Documentation

Preparation of a feature document with screenshots.

(4) Development Estimates

Phil's development estimates -- 10-23-2013

---