Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

[Next: Getting Started]

# Qt Motif Extension - A Migration Walkthrough

This walkthrough covers a complete migration of a Motif based program to the Qt toolkit using the Qt Motif Extension.

It is rarely practical for a large project with hundreds of thousands or even millions of lines of code to be migrated all at once; such an endeavor would require too many development resources and would incur significant risks. Every line of code would have to be rewritten, every user interface redesigned, and quality assurance tests and procedures all rewritten. The Qt Motif Extension provides a complete and working solution for incremental migration that can be paced to suit each individual project and the available resources. The user interface and related code can be migrated in steps while the rest of the project need not be changed at all.

This walkthrough is intended for programmers who will be migrating an existing Motif based project to the Qt toolkit. We assume that they have experience with C/C++ and Xt/Motif. Some experience with the Qt toolkit is also necessary. For developers completely new to Qt we recommend following the learning plan outlined in How to Learn Qt; or to go on a Qt training course. (See http://www.trolltech.com/ for details of training courses.)

## Goals for the Walkthrough

The goal of this walkthrough is to provide the reader with enough knowledge to migrate Motif applications to the Qt toolkit. We will do this by example: We will convert a real-world Motif based program step-by-step. This walkthrough will discuss both techniques and their rationales throughout the process. This walkthrough is broken down into individual chapters which cover a specific topic:

1. Getting Started
2. Preparing to Migrate the User Interface
3. Using Qt Standard Dialogs
4. Using Custom QDialogs
5. Using Existing Dialogs with QMotifDialog
6. Using Qt Main Window Classes
7. Refactoring Existing Code
8. Replacing the View Widget
9. Replacing the Print Dialog
10. Continuing Development

We will use the todo demo program included with the Motif 2.x distribution as our migration project. This walkthrough contains references to the source code, which is included in the `extensions/motif/examples/walkthrough` subdirectory.

## Prerequisites

Before we can start using the Qt Motif Extension, we must satisfy these requirements:

1. We are using the X11R6.x and Motif 2.x libraries.
2. The project is compilable by a C++ compiler.
3. We have built and installed the Qt Motif Extension.
4. We have built and linked the project with the Qt toolkit and the Qt Motif Extension

### X11R6.x and Motif 2.x Libraries

The mechanisms used by the Qt Motif Extension require development headers and libraries from the X11R6 release and the Motif 2.0 release. Newer versions of these can also be used.

### C++ Compiler

Since Qt is a C++ toolkit, all new code will be written in C++. In order for existing code to coexist with new code, a C++ compiler must be able to compile the existing code.

It is possible to keep existing code and new code separate, and only convert or rewrite existing code as needed. This is a normal part of the migration process, and does not need to be done before the migration process begins. This is the most common scenario, and we will demonstrate it by migrating existing C code to C++ as needed in this walkthrough.

### Build and Install the Qt Motif Extension

The Qt Motif Extension is not built and installed along with the Qt toolkit. The extension resides in the `extensions/motif` subdirectory. Run make in this directory to build the extension and the examples. Once the extension has been built, run make install.

        $ cd extensions/motif
        $ make
        $ make install

The Qt Motif Extension is now installed and ready to use.

### Build and Link the Project with the Qt Toolkit and the Qt Motif Extension

For simplicity, we use qmake to create the `Makefile`. The `-project` option causes qmake to automatically generate a project file. After qmake -project has generated our project file, we run qmake again to generate a `Makefile`. Now, we can just run make to build our project.

        $ qmake -project
        $ qmake
        $ make

Everything builds correctly, but fails to link because we don't link with the Motif library. We tell qmake to do this by adding the `-lXm` to the `LIBS` variable in our project file. Since we are planning to use the Qt Motif Extension in this project as well, we should also add `-lqmotif` to the list of libraries.

        LIBS += -lXm -lqmotif

Now we regenerate our `Makefile` by running `qmake` again, and rebuild using `make`. This time, our project successfully links, and the application runs as expected.

We are now ready to start using the Qt Motif Extension.

[Next: Getting Started]