tqt3/examples/opengl/overlay_x11/overlay_x11.doc

/*!   \page opengl-overlay-x11-example.html

  \ingroup opengl-examples
  \title OpenGL Overlay X11 Example

\warning From version 5.0 onwards, the TQt OpenGL Extension includes
direct support for use of OpenGL overlays. For many uses of overlays,
this makes the technique described below redundant. See the \link
opengl-overlay-example.html overlay\endlink example program. The
following is a discussion on how to use non-QGL widgets in overlay
planes.

Overlayrubber: An example program showing how to use TQt and TQt OpenGL
Extension with X11 overlay visuals.

See \c{$TQTDIR/examples/opengl/overlay_x11} for the source code.

Background information for this example can be found in the
information on \link opengl-x11-overlays.html overlays\endlink. 

The example program has three main parts:

\list 1
\i \e GearWidget - a normal, simple QGLWidget. This renders the usual
gears. It has been modified to print a debug message every time it
redraws (renders) itself. Thus, you can easily confirm that drawing in
the overlay plane does not cause redrawings in the main plane where
the QGLWidget resides.

\i \e RubberbandWidget - Very simple standard (non-GL) TQt widget that
implements rubberband drawing. Designed for use in an overlay plane.
It takes the plane's transparent color as a constructor argument and
uses that for its background color. Thus, the widget itself will be
invisible, only the rubberbands it draws will be visible.

\i \e{main.cpp} Creates a GearWidget and a Rubberbandwidget and puts the
latter on top of the former. Contains a routine that checks that the
default visual is in an overlay plane, and returns the transparent
color of that plane.
\endlist

\section1 Running the Example

Start the \c overlayrubber executable. Click and drag with the left
mouse button to see rubberband drawing. Observe that the QGLWidget
does not redraw itself (no redraw debug messages are output), and yet
the image is not destroyed. Marvel at the coolness of X11 overlays!


\section1 Using this technique in a real application

For clarity, this example program has been kept very simple. Here are
some hints for real application usage:

\list

\i \e{All normal widgets are in the overlay plane.} This means that you
can put all kinds of TQt widgets (your own or standard TQt widgets) on
top of the OpenGL image (widget), e.g. pushbuttons etc., and they can
be moved, resized, or removed without destroying the OpenGL image.

\i \e{Using with geometry management.} The QLayout classes don't permit
putting one widget (the overlay) on top of another (the OpenGL
widget); that would defy the whole purpose of the automatic layout.
The solution is to add just one of them to the QLayout object. Have it
keep a pointer to the other (i.e. the QGLWidget knows about its
overlay widget or vice versa). Implement the resizeEvent() method of
the widget you put in the layout, and make it call setGeometry() on
the other widget with its own geometry as parameters, thus keeping the
two widgets' geometries synchronized.

\i \e{Using together with QPalette and TQColorGroup.} Instead of the
simplistic setBackgroundColor( transparentColor ), you can
use Qt's QPalette system to make your overlay widgets use
transparent color for what you want. This way, the normal TQt widgets
can be used as overlays for fancy effects. Just create a palette for
them with the transparent color for the relevant color roles, e.g.
Background and Base, in the Normal and/or Active modes. This way, you
can create see-through QPushButtons etc.
\endlist

*/