
Qt support
==========

Maverik's support for Qt requires that the Qt development environment
(verion 2.3 or above) be installed. This can be downloaded from
http://www.trolltech.com
    
Qt support has be tested on Unix (Linux and Irix) and Windows. Qt is
also available for Macs and so it should work on this platforms. In
fact one the aims of supporting Qt is that it will hopefully provide
Maverik with a platform independent means of opening windows, creating
graphics contexts, handling events etc...

Qt support must be specified at compile time. On Unix this is achieved
by passing the setup script the "--QT" option. On Windows rename the
libmaverik-qt.dsp file in the vc++ sub-directory to be libmaverik.dsp



How it works
============

The mav_windowNew function is used to open windows, either explicitly
or as a part of the initialisation sequence. When Qt support is
enabled this function creates an OpenGL widget to act as Maverik's
rendering window. The mav_windowNew function has the following
prototype:

  MAV_window *mav_windowNew(int x, int y, int w, int h, char *name, char *disp);

The last argument, disp, normally specifies the X server on which to
open the window - something which is not applicable when using Qt. So,
when Qt support is enable this variable is used to define the parent
widget of the Maverik rendering window thus allowing a GUI to be
constructed. For example:

  QVBox *vbox;

  mav_windowNew(0, 0, 100, 100, "name", (char *) vbox);

Note the cast to prevent compilation problems. If the window is opened
automatically as part of the initialisation sequence then the parent
widget is defined thus:

  mav_opt_disp= (char *) vbox;

If no parent widget is specified (mav_windowNew called with disp=NULL
which is the default case) then the Maverik rendering widget is
cerated as a top level widget.

An example of using Qt can be found in examples/misc/Qt. This is
compiled automatically on Unix. On Windows you need to lauch the
qt.dsw workspace file in the vc++ sub-directory to compile the
example.

Note: the current implementation processes one Qt event per frame. If
lots of event are generated and the frame rate is low this could lead
to lag. Ideally Qt processing should be performed as a separate
thread. Furthermore, some functionality, such as fonts and obtaining a
key's status is currently unimplemented.

If you need access to the Maverik rendering widget you can search for
it by name:

 QWidgetList *list= QApplication::allWidgets();
 QWidgetListIt it(*list);         // iterate over the widgets
 QWidget *w, *mavwid;
 while ((w=it.current())!=0) {  // for each widget...
   ++it;
   if (strcmp(w->name(), name)==0) mavwid= w;
 }
 delete list;                      // delete the list, not the widgets
