USACE SWD 14 (Part): Save RPL Display Settings in RiverWare Model File / RW 7.1
Document Home: R:\doc\RPL\RplDialogs\2017\RplDispSett-InRwModel.docx
Phil Weinstein, David Neumann, Edie Zagona, CADSWES, 4-25-2017

    

One part of the USACE SWD 14 task is moving the RPL Display Settings from the User Configuration (Windows Registry) into the RiverWare Model File. This has been done for RiverWare 7.1.

The User Configuration (Windows Registry) is still used, but now only for "User Defaults" which are loaded when: (a) starting RiverWare, (b) clearing the RiverWare workspace, or (c) invoking a "Load User Defaults" operation under the RPL Display Setting dialog's File menu; (see the File menu screenshot below).

After those points in time, the effective RPL Display Settings are modified in the following ways: (a) loading a model file which had been saved from a version of RiverWare having this model-file enhancement, (b) operating any of the other "Load ..." operations in the File menu, or (c) direct edits to those settings. Any such changes to RPL Display Settings are saved in the model file the next time the model file is written (saved) within the same RiverWare session.

The only changes to the RPL Display Settings GUI are: (a) the addition of the new operations in the dialog's "File" menu, and (b) a vertical geometry improvement to the Colors panel -- it no longer expands vertically to more space than needed to present the color configuration items.

The following screenshot shows the RPL Display Settings dialog's new File menu:

Previously, in RiverWare 7.0, any change to the RPL Display Settings made by the user was immediately saved in the User Settings (Windows Registry). Now, this configuration data is written to User Settings only when the user explicitly selects the new "Save as User Defaults" operation. (That "save" operation is confirmed with a popup dialog).

Also, the following operations have been added:

The RPL Display Settings data is written to the RiverWare model file using a new XML format. That new format is now also used for exporting these settings to a text (XML) file. This new format replaces the old non-XML text format which had two deficiencies, described below. RiverWare can still import old exported text files saved with the old non-XML format -- detection of that format is automatic.

The deficiencies of the old export format -- fixed with use of the new XML export format -- are as follows:

  1. The old export format did not include color configurations (for RPL text and backgrounds). It contained only the font specification and the RPL "Line Break" configuration.
     
  2. The properties to which both color and line break specifications corresponded were encoded as just integer representations of internal C++ enumerated types. This is very fragile, as the addition of a value of those enumerated types not added to the end would invalidate the saved data. (This actually had occurred in an early RiverWare release supporting RPL Display Settings). The new XML format uses symbolic character strings to identify color and line break properties.

Note however that the User Settings (Windows Registry) color and line break data -- now used for "User Defaults" -- still uses integer representations of internal C++ enumerated types. (We didn't take time to revise that now).

Internal Software Enhancements

The three parts of the RPL Display Settings information -- Font, Colors, and Line Breaks -- had "lived" in some pretty strange places within RiverWare C++ code. The GUI was directly important and exporting this data on its own, without any coherent data model encapsulation. The Font and Colors existed in the QtRpl/RplDlgMgr class (a singleton). The Line Break data had existed in a live dialog object -- QtRpl/RplDisplaySettingsDlg -- not fundamentally a singleton (!), but effectively a singleton in actual use.

All of these pieces are now encapsulated in a RplDisplaySettings class. This is still defined in the QtRpl (GUI) library, as it depends on some definitions up in the GUI classes in that library, but the only RplDisplaySettings instance lives in Sim/SimWS (the Sim-library workspace data singleton). The RPL Display Setting dialog makes direct edits to that single RplDisplaySettings instance. Changes to that instance are following by the generation of a new WS_RPL_DISP_SETT_CHANGED callback from Sim/SimWS.

The new QtRpl/RplDisplaySettings encapsulates its own serialization, of all three types:

  1. User Settings (Windows Registry), now used for "User Defaults",
  2. The new XML serialization, used in the RiverWare model and new export files,
  3. The old non-XML text serialization, no longer generated, but supported for Import (with automatic format detection during import).

Serialization Examples

Sample XML export files and a trivial (tiny) RiverWare model containing RPL Display Setting data are put aside at the URLs below. (For the latter, that data is near the end of the file):

--- (end) ---