Author: Phil Weinstein, CADSWES
Status: Ready for review (2).
Edit: 1-9-2010 (b)

Updates:

• 1-7-2010: Patrick suggested adding mention of porting RplFrame. See section 1.2.
• 1-8-2010: Added Sections 2.2, 2.3, and 2.4 enumerating dialogs and the number of their Qt3 widgets ... Added summary count section ... Added note on the limitations of uic3 to convert Qt3 Designer UI files. It seems that that limitation doesn't apply to our use of custom slots.

Sections:

(0) Overview
 
(1) Major High Level Tasks in the Qt4 Port
(1.1) Converting all "Qt Designer" built UI files from Qt3 to Qt4.
(1.2) Replacing all uses of Qt3 classes (widgets, etc) with Qt4 classes.
(1.3) Removing all uses of Qt3-compatibility methods in Qt4 classes.
 
(2) Some RiverWare 5.2 Enumerations
(2.1) RiverWare Qt3 and Qt4 Designer UI Files
(2.2) Dialogs in Qt3 Designer UI Files
(2.3) Dialogs in Qt4 Designer UI Files
(2.4) Dialogs defined in C++ code (not UI files).
(2.5) RiverWare uses of Q3Table
(2.6) RiverWare uses of Q3ListView
(2.7) RiverWare uses of QTableView / QTableWidget (Qt4 Tables)
(2.8) RiverWare uses of QTreeView / QTreeWidget (Qt4 Lists)

(0) Overview

The last few RiverWare releases (5.0, 5.1 and 5.2) have been built with Qt version 4 (4.3 or 4.4) with use of the "Qt3 Compatibility Library". Graphical user interface (GUI) modules in RiverWare are now implemented using a mix of Qt4 widgets and Qt3 widgets (adapted for use with Qt4). To complete the Qt4 port, we need to recode all uses of Qt3 widgets to use instead Qt4 widgets. Benefits of completing the Qt4 port include improved user interface capabilities, performance, and ease of maintenance. Also, it will be important for all Qt3 to be removed from RiverWare before we can move to Qt 5 further down the road. (Plans for Qt 5 have not been announced. Qt is currently at version 4.6).

The major high-level tasks in the Qt4 port completion are:

1. Converting all "Qt Designer" built UI files from Qt3 to Qt4.
2. Replacing all uses of Qt3 classes (widgets, etc.) with Qt4 classes.
3. Removing all uses of Qt3-compatibility methods in Qt4 classes.

(1) Major High Level Tasks in the Qt4 Port

(1.1) Converting all "Qt Designer" built UI files from Qt3 to Qt4.

Qt Designer is a GUI building program supporting the definition and lay out of widgets for Qt dialogs and other GUI components. Designer maintains widget layout definitions in "UI" (.ui) files. Qt3 and Qt4 UI files have incompatible formats, and Qt4 Designer cannot directly read Qt3 Designer UI files. However, Qt4 provides a "uic3" (UI compiler) tool which has these two capabilities:

1. "uic3" can be used as part of the automated "make" process to generate C++ code from Qt3 UI files (using the Qt3 Compatibility Library). This is currently done in the RiverWare "make".
2. "uic3" can be used to convert Qt3 UI files to Qt4 UI files.

The latter capability of "uic3" will be used to convert RiverWare's Qt3 UI files to Qt4 UI files. The process is not entirely automatic. [But see following note]. Hand recoding is required for all custom Qt signal handlers (Qt "slots") defined within the Qt3 UI file. Qt4 Designer doesn't support custom Qt slots. Those Qt slots -- and the signal connections made to them -- need to be written in our C++ code. Also, icons defined in Qt3 UI files need to be handled differently.

• Note [Phil, 1-8-2010]: I don't believe that Qt4 Designer and related tools actually have the limitation described above and in the "Porting .ui Files to Qt 4" document linked below. Our Qt4 UI files DO seem to have custom Qt slots on the client-container QWidget, and the connections to those slots are in the Qt4 uic-generated code! ... See, for example the "slots" and "connections" reprented in this Qt4 UI, and uic-generated file: DbDmi/DbDmiImpExpDlgBase.ui and DbDmi/qt/DbDmiImpExpDlgBase.h, e.g. connection to the "fileTextHandler (const QString&)" custom slot.

[If custom-slots IS actually a problem in Qt4 UI files -- which it doesn't seem to be -- see prior note] ... a reasonable initial step in the Qt3 to Qt4 UI file porting process is the removal of all Qt slots (signal handlers) and signal/slot "connections" from the Qt3 UI files, and recoding them in the each module's C++ code. Careful testing will be necessary for this step because "missing connections" will result in the absence of a feature rather than an observable bug. (Solaris is a preferable platform for this particular work because run-time Qt signal/slot connection errors are reported to the system console -- and we don't see those on Windows).

Note that both uses of Qt4 "uic3" generate both Qt3 and Qt4 widgets. Additional porting described in the next section will be required for most Qt3 to Qt4 translated UI files. That work can make use of Qt4 Designer to replace the remaining Qt3 widgets with Qt4 widgets. (And of course, supporting C++ code will also need to be changed to use the new Qt4 widgets).

Read more in this Trolltech document:

• Porting .ui Files to Qt 4  [http://doc.trolltech.com/4.4/porting4-designer.html]

Section (2.0) lists all of the Qt3 and Qt4 UI files in RiverWare 5.2.

(1.2) Replacing all uses of Qt3 classes (widgets, etc) with Qt4 classes.

All uses of the Qt3 Compatibility Library in Qt 4 need to be removed. This applies to both converted UI files and to our own C++ code. In UI files, this can be done mostly in Qt4 Designer -- though it is sometimes convenient to (carefully) directly edit the UI files (which are XML). Conveniently, the names of all Qt3 classes (in the Qt3 Compatibility Library) start with "Q3", e.g. Q3PopupMenu or Q3ListView.

Major tasks include:

• Porting the Accounting Canvas from Q3Canvas to [Qt4] QGrahpicsView and QGraphicsScene. This has been done for the Simulation Canvas. See documents:
  • "RiverWare Workspace port to Qt4 Graphics View" (January 2009). [/projects/riverware/doc/guiRework/workspace/Qt4GraphicsViewWorkspace.fm and .pdf].
  • "RiverWare 5.1 Simulation Workspace Enhancements" (May 2009). [/projects/riverware/doc/guiRework/workspace/Rw51SimWorkspaceEnhance.fm and .pdf].
  • [Trolltech] "Porting to Graphics View" [http://doc.trolltech.com/4.4/graphicsview-porting.html].
     
• Porting RplFrame (a Q3ScrollView with custom painting) probably to [Qt4] ScrollArea. RplFrame supports the display and editing of RPL Expressions. I don't think we seriously need to consider reimplementing RplFrame using Qt's "managed graphics" capabilities (i.e. the Qt4 "Graphics View" architecture) -- the current application-level implementation for rendering, selecting, and editing nested expressions works well and is good code.
   
• Recoding all uses of Qt3 List and Table widgets. After the prior two items, these will be the next most complex widgets to port. The "life-cycle" and state of list and table items need to be dynamically updated generally without causing changes in the horizontal or vertical scroll positions or other causes of "flicker". The simpler lists and tables having a relatively small number of rows and columns can be ported to the simpler "item-based" widgets: QTreeWidget (for lists) and QTableWidget. (List applications can be based on QtUtils/RwQListView, a QTreeWidget. And utilities in RwQt4Utils will be useful). Lists and Tables which may have a very large number of rows or columns (e.g. for series data) should be ported to the more-complicated "itemless, model-based" widgets, generally QTreeView (for lists) and QTableView. (i.e. "-View" instead of "-Widget"). For lists and tables in UI files, a good approach is having only a "container widget" in the UI file, and placing the actual list or table widget into that container in our own C++ code.
   
• Recoding all uses other Qt3 Compatibility Library classes. This applies to our own C++ code as well as the widgets originally in Qt3 UI files not ported automatically by the uic3 tool, notably Q3ButtonGroup, Q3GroupBox, Q3MainWindow and Q3WidgetStack. (See Qt3 widget lists in sections 2.2 and 2.4). We've noticed that the tools used to port to Qt4 with the Qt3 Compatibility Library (in the preparation of RiverWare 5.0) were overly conservative. For example, generally all Q3PopupMenus created during that original port can just be changed to (Qt4) QMenu without further modification.

Progress on the subsequent step will be made easier when all Qt3 compatibility classes (whose names start with "Q3") have been removed from all C++ header files. But the goal, of course, is to remove references to those classes in all RiverWare code.

(1.3) Removing all uses of Qt3-compatibility methods in Qt4 classes.

Many of the Qt4 classes include also "Qt3 support members" (generally, C++ methods). (See, for example, the Qt4 QMenu class). Many of these are overridden methods, e.g. constructors with many initialization parameters -- those have generally been removed from Qt4. Once the prior step of removing all Qt3 classes form RiverWare header files has been completed, it will be useful to enable or disable availability of the Qt3 Compatibility Library for individual source files -- instead of having that library enabled for the entire build. [This is controlled with the QT3_SUPPORT symbol].

(2) Some RiverWare 5.2 Enumerations

Summary Counts:

Other Sections Below:

(2.5) RiverWare uses of Q3Table
(2.6) RiverWare uses of Q3ListView
(2.7) RiverWare uses of QTableView / QTableWidget (Qt4 Tables)
(2.8) RiverWare uses of QTreeView / QTreeWidget (Qt4 Lists)

(2.1) RiverWare Qt3 and Qt4 Designer UI Files

Note [1-6-2010]: Not all of these are used in the RiverWare build. Some of these modules were ported to Qt4 (w/ Qt3 compatibility support) by dropping the UI file. Those UI files are currently indicated with a strikeout. (So far, just four have been found -- but there are probably others).

(2.2) Dialogs in Qt3 Designer UI Files

Note: [Q3] column = number of Q3 widgets, after translation with Qt 4.4 uic3. The counts don't include the dialog box itself (in the case of dialog boxes derived from Q3MainWindow).
Eight (8) orange rows are for UI files which are not part of the build.

(2.3) Dialogs in Qt4 Designer UI Files

This section shows two tables:

• Dialogs defined in Qt4 Designer UI Files
• Other widgets defined in Qt4 Designer UI Files

With the exception of one anomaly which will be addressed, these dialogs and other widgets don't contain Qt3 widgets. (They contain only Qt4 widgets).

The following table lists QWidgets defined in Qt4 Designer UI files other than dialogs. These are either "panels" used within possibly-multiple dialogs or the majority of the widget content of a single dialog. In the latter case, the distinction of these not being "dialogs" is not very significant -- that is, they are essentially "dialogs".

(2.4) Dialogs defined in C++ code (not UI files).

Note: [Q3] column = number of Q3 widgets, after translation with Qt 4.4 uic3. The counts don't include the dialog box itself (in the case of dialog boxes derived from Q3MainWindow).

(2.5) RiverWare uses of Q3Table

There are far fewer Q3Tables in RiverWare than Q3ListViews (see next section). See the tables below.

The Q3Tables for the Open Slot Dialogs (for Series and Table Slots) and for the SCT have a common base class (SlotDataQTable), and are quite complicated. These should be ported to the model-based QTableView (not QTableWidget) with a QAbstractTableModel subclass (to support an item-less implementation) and QItemDelegate (to support custom cell drawing). See our implementation for the Qt4 Run Analysis Dialog "grid" table classes: RunAnalGridQTableView, RunAnalGridQItemDelegate, and RunAnalGridQTableModel.

Q3Table Subclasses:

Q3Table Direct Instances:

(2.6) RiverWare uses of Q3ListView

See the two tables in this section: (1) Q3ListView Subclasses, and (2) Q3ListView Direct Instances. Generally, each of the subclasses have only one or two clients, with one or two instances each, so both of these types of items (subclasses and direct instances) have about the same level of complexity in porting. Those that implement flat lists (not multiple-level treeviews), and which have a relatively small number of items (e.g. not rows for series timesteps) can be replaced with either of these two widgets:

1. Our new general Qt4 list widget: RwQListView (a Qt4 QTreeWidget) -- used by either subclassing or instantiating.
2. For Slots, our new SlotListPanel, containing an RwQListView instance.

Also, our general Qt4 widget utilities module may be useful: RwQt4Utils.

Q3ListView Subclasses:

Q3ListView Direct Instances:

(2.7) RiverWare uses of QTableView / QTableWidget (Qt4 Tables)

The following tables list the Qt4 QTableViews and QTableWidgets currently implemented in RiverWare (5.2).

QTableView / QTableWidget Subclasses (Qt4 Tables):

QTableView / QTableWidget Direct Instances (Qt4 Tables):

(2.8) RiverWare uses of QTreeView / QTreeWidget (Qt4 Lists)

The following tables list the Qt4 QTreeViews and QTreeWidgets currently implemented in RiverWare (5.2).

QTreeView / QTreeWidget Subclasses (Qt4 Lists):

QTreeView / QTreeWidget Direct Instances (Qt4 Lists):

--- (end) ---