RPL Display Settings in Model File / USACE SWD 14 (part)
Bug Number: n/a
Release notes (y/n): Yes
For Release Nums: 7.1

This is a squash commit of the CoeSwd14-DispSettDev2 branch 
(8 commits; 4-25-2017) onto the RiverWare 7.1 master branch.

Full Document for this work (4-25-2017):
R:\doc\RPL\RplDialogs\2017\RplDispSett-InRwModel.docx
http://cadswes2.colorado.edu/~philw/2017/CoeSwd14/RplDispSett-InRwModel.html

Screenshots:
http://cadswes2.colorado.edu/~philw/2017/CoeSwd14/docRef1/RplDispSettDlg.png
http://cadswes2.colorado.edu/~philw/2017/CoeSwd14/docRef1/RplDispSettDlg-FileMenu1.png
http://cadswes2.colorado.edu/~philw/2017/CoeSwd14/docRef1/RplDispSettDlg-FileMenu2.png

Serialization Examples:
http://cadswes2.colorado.edu/~philw/2017/CoeSwd14/docRef1/ExpRplDispSettXml.txt
http://cadswes2.colorado.edu/~philw/2017/CoeSwd14/docRef1/OneReach.mdl

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) explicitly invoking a "Load User Defaults"
operation under the RPL Display Setting dialog's File menu.

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; such settings will be 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 with more
space needed to present the color configuration items.

Previously, in RiverWare 7.0, any change to the RPL Display Settings made 
by the user were 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:

  (1) Load RiverWare Default Colors
  (2) Load RiverWare Default Line Breaks

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, as 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 integers 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 now 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 has 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 instance of that class
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_CUSTOM_ORDER_CHANGED callback generated 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).

--- (end) ---