path: root/src
diff options
authorFabien Freling <>2011-05-06 13:31:43 +0200
committerFabien Freling <>2011-05-10 11:45:42 +0200
commita35b2d58d921ee944d48dadbebe871df0c5c6986 (patch)
tree017a4d3d76d9c132fb1052c60a979daf1bfcbebb /src
parent4367928b5e39987c890ee42d1db533e581d9e5cf (diff)
Add internal documentation for QUnifiedToolbarSurface.
This document is aimed for developers. This is why it is directly written in the header file. This is not part of the public API. Reviewed-by: Richard Moe Gustavsen (cherry picked from commit 891b6ac7236d21b69bdb54b00051422cee004059)
Diffstat (limited to 'src')
1 files changed, 33 insertions, 0 deletions
diff --git a/src/gui/painting/qunifiedtoolbarsurface_mac_p.h b/src/gui/painting/qunifiedtoolbarsurface_mac_p.h
index 0a7ebf1759..6b1243e790 100644
--- a/src/gui/painting/qunifiedtoolbarsurface_mac_p.h
+++ b/src/gui/painting/qunifiedtoolbarsurface_mac_p.h
@@ -65,6 +65,39 @@ QT_BEGIN_NAMESPACE
class QNativeImage;
+// This is the implementation of the unified toolbar on Mac OS X
+// with the graphics system raster.
+// General idea:
+// -------------
+// We redirect the painting of widgets inside the unified toolbar
+// to a special window surface, the QUnifiedToolbarSurface.
+// We need a separate window surface because the unified toolbar
+// is out of the content view.
+// The input system is the same as for the unified toolbar with the
+// native (CoreGraphics) engine.
+// Execution flow:
+// ---------------
+// The unified toolbar is triggered by QMainWindow::setUnifiedTitleAndToolBarOnMac().
+// It calls QMainWindowLayout::insertIntoMacToolbar() which will
+// set all the appropriate variables (offsets, redirection, ...).
+// When Qt tells a widget to repaint, QWidgetPrivate::drawWidget()
+// checks if the widget is inside the unified toolbar and exits without
+// painting is that is the case.
+// We trigger the rendering of the unified toolbar in QWidget::repaint()
+// and QWidget::update().
+// We keep track of flush requests via "flushRequested" variable. That
+// allow flush() to be a no-op if no repaint occured for a widget.
+// We rely on the needsDisplay: and drawRect: mecanism for drawing our
+// content into the graphics context.
+// Notes:
+// ------
+// The painting of items inside the unified toolbar is expensive.
+// Too many repaints will drastically slow down the whole application.
class QUnifiedToolbarSurfacePrivate