Widget Module HOWTO

This document explains how modules are used in QtArch and how they can be written for third party widgets.

Using Widget Modules

Widget Modules are plugins for QtArch. They can be added via the Edit|Preferences dialog from the main window. Any number of widget modules can be added.

Adding the Modules

In the Edit|Preferences dialog, the modules page allows the user to add and remove modules from QtArch. The Add button will allow the user to browse for the module to add.

Besides containing widgets, modules can specify the QApplication class used by QtArch. This feature is needed to support KDE because the KDE widgets require a KApplication, not a standard QApplication. The module which is to supply the QApplication is indicated by checking the check box next to the name. Only one module should be checked as there can be only one QApplication. The first one checked will be used.

Using the Widgets

To add a widget, goto the Module menu of the main dialog window. A list of available modules is displayed. The widgets for each module are contained in sub menus. Select one to add it to the dialog. If the module author has created pixmap images of the widgets, a toolbar will be built with the pixmaps. Simply click on the button to add the widget.

Once a widget is added, it can be manipulated exactly the same as the Qt widgets. If the author of the module has added property pages for the widget, they will appear in the property dialog along with the Qt widget pages.

Saving, loading, and code generation are also seamlessly integrated. Nothing special has to be done by the dialog designer. All that is required to build the generated code is to include the include paths for the widget headers and link with the appropriate libraries for the widgets.

Writing Widget Modules

Widget modules are shared objects on unix and dlls on Windows. They contain abstraction classes used by QtArch to perform saving, loading, code generation, and other utility functions. Also, they contain the property pages which will be desplayed in the property dialogs for the widgets.

QtArch Abstraction Classes

In order for QtArch to use the widgets for saving, code generation, etc., a class hierarchy which parallels the Qt widget hierarchy has been developed. The base class is DlgWidget which contains a QWidget object and provides the base functionality for all widgets in QtArch. Derived from DlgWidget are classes like DlgFrame which points to a QFrame. The following diagram tries to show how the hierarchies work for a QLabel:

		-------------                  -----------
		| DlgWidget |o---------------- | QWidget |
		-------------                  -----------
		      |                             |
		     / \                           / \
		-------------                  -----------
		| DlgFrame  |                  | QFrame  |
		-------------                  -----------
		      |                             |
		     / \                           / \
		-------------                  -----------
		| DlgLabel  |                  | QLabel  |
		-------------                  -----------
	

For a DlgLabel, the QWidget pointer held by DlgWidget will actually be a QLabel object.

For user widgets, classes derived from DlgWidget, or one of it's derived classes, will have to be written. If user widget Foo is derived from QLabel, then the class hierarchy will look like:

		-------------                  -----------
		| DlgWidget |o---------------- | QWidget |
		-------------                  -----------
		      |                             |
		     / \                           / \
		-------------                  -----------
		| DlgFrame  |                  | QFrame  |
		-------------                  -----------
		      |                             |
		     / \                           / \
		-------------                  -----------
		| DlgLabel  |                  | QLabel  |
		-------------                  -----------
		      |                             |
		     / \                           / \
		-------------                  -----------
		| DlgFoo    |                  | Foo     |
		-------------                  -----------
	

The advantage of deriving DlgFoo from DlgLabel instead of DlgWidget is that all of the properties from QFrame and QLabel, which are present in Foo, will automatically be handled by the base classes.

Property Pages

Property pages for widgets are simply classes derived from QWidget which are stuck in a QTabDialog.

The constructor normally takes a pointer to the DlgFoo class in order to set the properties from the widget.

One slot has to be added so that the changes to the properties can be applied to the widget. This slot should take the properties from the screen and set them into the widget The format of the slot is:

void Apply( DlgWidget* widget );
	

Module Widget Factories

The interface between QtArch and the modules is accomplished by a module factory which QtArch retrieves from the modules. The file module/WidgetModule.h from the QtArch source contains the interface class from which the module factory must be derived. The methods defined in the interface are described below:

Module Functions

In module/WidgetModule.h, there are three functions defined which are to be exported from the module. The functions are described below:

Compiling and Linking

In order to compile the module, the QtArch source will be needed. Since you're module needs to use DlgWidget derived classes, you need their header files. Also, the module/WidgetModule.h file is needed for the factory class.

On unix, the module should be compiled with -Fpic and built as a shared object, .so file.

On unix, linking should not need to include the DlgWidget object files. They will be found when the module is loaded. A shared object should be produced.

Help

The KDE module supplied with QtArch is a good place to start for other modules. The factory class, especially, is quite reusable. Also, there is a template directory with a shell script that creates skeleton DlgFoo and Foo property pages.


Back
Last modified: Sun Apr 4 00:09:40 MST 1999