RiverWare Qt4 Port Status -- January 2010

Status: Initial writing in progress.
Edit: 1-7-2010 (b), Phil Weinstein, CADSWES

(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) RiverWare Qt3 and Qt4 Designer Files
(3) RiverWare uses of Q3Table
(4) RiverWare uses of Q3ListView

(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 cababilities:

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

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 absense 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 Canvans from Q3Canvas to [Qt4] 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].
     
• Recoding all uses of Qt3 List and Table widgets. Aside from the Q3Canvas, these will be the most complex widgets to port. 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. We've noticed that the tool 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 from that original port can just be changed (Qt4) QMenu without further modification.

Progress on the subsequent step will be made easier when all Qt3 compatibilty 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 members 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, 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) RiverWare Qt3 and Qt4 Designer Files

Note [1-6-2009]: 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 three have been found -- but there are probably others).

(3) 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 implmentation for the Run Analysis Dialog "grid" table classes: RunAnalGridQTableView, RunAnalGridQItemDelegate, and RunAnalGridQTableModel.

Q3Table Subclasses:

Q3Table Direct Instances:

(4) 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:

(5) RiverWare uses of (Qt4) QTableView and QTableWidget

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

(Qt4) QTableView and QTableWidget Subclasses:

(Qt4) QTableView and QTableWidget Direct Instances:

(6) RiverWare uses of (Qt4) QTreeView and QTreeWidget

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

(Qt4) QTableView and QTableWidget Subclasses:

(Qt4) QTableView and QTableWidget Direct Instances:

--- (end) ---