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.
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.
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 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 );
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:
QString getName() - Return the name of the widget
module. Each module must have a unique name.
bool useToolbar() - Should a toolbar be shown for
adding the widgets. If true, a toolbar will be added on the
dialog window. This should only be set if pixmaps are defined for
the widgets as text labels are used otherwise.
QStrList getWidgetNames() - Return the list of
the names of widgets created by this module.
QPixmap getWidgetPixmap( const QString& theWidgetName )
- Return a pixmap representing the widget specified.
DlgWidget* newWidget(int theWidgetNum) - Return a
new widget based on the number specified. The number corresponds
to the index of the widget in the QStrList returned by
getWidgetNames.
DlgWidget* newWidget( const QString& theWidgetName )
- Return a new widget based on the name specified. The name
will be a name in the QStrList returned by
getWidgetNames.
In module/WidgetModule.h, there are three functions defined which are to be exported from the module. The functions are described below:
void GetModuleVersion(
int& theMajorVersion,
int& theMinorVersion )
- Retrieve the version of the module. The version numbers are
needed to track changes in the module API. The initial
versions should be 1.0.
WidgetModule* GetWidgetModule() - Get a new
WidgetModule object defined by the module.
QApplication* GetQApplication(
int& theArgc,
char** theArgv
)
- If this module was marked as supplying the QApplication for
QtArch, return a new QApplication derived object.
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.
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.