1 files changed, 82 insertions, 0 deletions
diff --git a/examples/opengl/overlay_x11/overlay_x11.doc b/examples/opengl/overlay_x11/overlay_x11.doc
new file mode 100644
index 000000000..6dddc9b9b
--- /dev/null
+++ b/examples/opengl/overlay_x11/overlay_x11.doc
@@ -0,0 +1,82 @@
+/*!   \page opengl-overlay-x11-example.html
+
+  \ingroup opengl-examples
+  \title OpenGL Overlay X11 Example
+
+\warning From version 5.0 onwards, the Qt 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 Qt and Qt OpenGL
+Extension with X11 overlay visuals.
+
+See \c{$QTDIR/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) Qt 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 Qt widgets (your own or standard Qt 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 QColorGroup.} 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 Qt 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
+
+*/