Index: /trunk/doc/src/snippets/code/src_gui_painting_embedded_pm.cpp
===================================================================
--- /trunk/doc/src/snippets/code/src_gui_painting_embedded_pm.cpp	(revision 1013)
+++ /trunk/doc/src/snippets/code/src_gui_painting_embedded_pm.cpp	(revision 1013)
@@ -0,0 +1,76 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+#define INCL_WINWINDOWMGR
+#define INCL_GPIREGIONS
+#include <os2.h>
+
+// although the prototype is available in <QWidget>, external applications
+// may need to declare it manually and link to QtGui4.lib directly, or even
+// query it from QtGui4.dll dynamically at runtime
+LONG APIENTRY qt_WinProcessWindowObstacles(HWND hwnd, RECTL *prcl, HRGN hrgn,
+                                           LONG op, LONG flags);
+
+void externalPaint(HWND hwnd)
+{
+    // hwnd is the value returned by QWidget::winId()
+
+    RECTL rcl;
+    WinQueryWindowRect(hwnd, &rcl);
+    HPS hps = WinGetPS(hwnd);
+
+    HRGN hrgn = GpiCreateRegion(hps, 1L, &rcl);
+    ULONG rc = qt_WinProcessWindowObstacles(hwnd, NULL, hrgn, CRGN_DIFF,
+                                            0 /* PWO_Default */);
+    if (rc == RGN_RECT || rc == RGN_COMPLEX) {
+        HRGN hrgnOld;
+        GpiSetClipRegion (hps, hrgn, &hrgnOld);
+        hrgn = hrgnOld;
+
+        // Paint to hps using regular PM and GPI calls
+    }
+
+    GpiDestroyRegion (hps, hrgn);
+
+    WinReleasePS (hps);
+}
+//! [0]
+
Index: /trunk/src/gui/kernel/qwidget_pm.cpp
===================================================================
--- /trunk/src/gui/kernel/qwidget_pm.cpp	(revision 1012)
+++ /trunk/src/gui/kernel/qwidget_pm.cpp	(revision 1013)
@@ -231,23 +231,65 @@
 
 /*!
-    \internal
-
-    Helper function to collect all relative windows intersecting with the given
-    \a hwnd and placed above it in z-order. The area of interest is limited to
-    the \a prcl rectangle (in window coordinates) which may be NULL to indicate
-    the whole window. If \a hrgn is not NULL, all found obstacles are combined
-    with the given region using the \a op operation (CRGN_*); otherwise they are
+    \enum PWOFlags
+    \relates QWidget
+
+    Flags for qt_WinProcessWindowObstacles() that define which relative windows
+    to process.
+
+    \warning This enum is only available on OS/2.
+
+    \value PWO_Children Child windows.
+    \value PWO_Siblings Sibling windows.
+    \value PWO_Ancestors Siblings of the parent window and all ancestors.
+    \value PWO_Screen Screen area.
+    \value PWO_TopLevel All top level windows.
+    \value PWO_Default Default value suitable for most paint operations
+        (equivalent to specifying all flags except PWO_TopLevel).
+*/
+
+/*!
+    \fn LONG qt_WinProcessWindowObstacles(HWND hwnd, RECTL *prcl, HRGN hrgn,
+                                          LONG op, LONG flags)
+    \relates QWidget
+
+    Collects all relative PM windows intersecting with the given \a hwnd and
+    placed above it in Z-order. The area of interest is limited to the \a prcl
+    rectangle (in window coordinates) which may be \c NULL to indicate the whole
+    window. If \a hrgn is not \c NULL, all found obstacles are combined with
+    the given region using the \a op operation (\c CRGN_*); otherwise they are
     directly validated on the window. The scope of relativeness is defined by
-    the \a flags argument which is one or more PWO_* flags OR-ed together.
+    the \a flags argument which is one or more PWOFlags OR-ed together.
 
     Returns the complexity of the combined region (only when \a hrgn is not
-    NULL). Note that if no combining occurs (e.g. no relatives in the requested
-    scope), the return value is RGN_NULL regardless of the original complexity
-    of \a hrgn.
+    \c NULL). Note that if no combining occurs (e.g. no relatives in the
+    requested scope), the return value is \c RGN_NULL regardless of the original
+    complexity of \a hrgn.
+
+    This function is especially useful for 3rd-party applications that embed
+    themselves into a Qt application by painting directly on a PM window of a Qt
+    widget (that gets created when QWidget::winId() is called), bypassing Qt
+    completely. An example of such an application would be a video player that
+    renders and paints frames in an external non-Qt thread or process.
+
+    Qt does not use the \c WS_CLIPSIBLINGS and \c WS_CLIPCHILDREN flags when
+    creating PM windows for non-top-level widgets (because that would break
+    support for non-rectangular widgets due to a bug in PM) and this function
+    acts as a functional replacement for these flags. Any application that
+    paints on the PM window of the Qt widget directy must call
+    qt_WinProcessWindowObstacles() to correctly clip out portions of the widget
+    covered by other widgets placed above it in Z-order and avoid unexpected
+    painting over these widgets.
+
+    \snippet doc/src/snippets/code/src_gui_painting_embedded_pm.cpp 0
+
+    \warning This function is only available on OS/2.
  */
-LONG qt_WinProcessWindowObstacles(HWND hwnd, RECTL *prcl, HRGN hrgn,
-                                  LONG op, LONG flags)
+LONG APIENTRY qt_WinProcessWindowObstacles(HWND hwnd, RECTL *prcl, HRGN hrgn,
+                                           LONG op, LONG flags)
 {
     Q_ASSERT(hwnd);
+
+    if (flags == 0)
+        flags = PWO_Children | PWO_Siblings | PWO_Ancestors | PWO_Screen;
 
     HPS displayPS = qt_display_ps();
@@ -345,5 +387,5 @@
     // but only if they are not top-level windows (that cannot be
     // non-rectangular and thus are always correctly clipped by the system)
-    if ((flags & PWO_Sibings) && parent != desktop) {
+    if ((flags & PWO_Siblings) && parent != desktop) {
         for (relative = swpSelf.hwndInsertBehind;
               relative != HWND_TOP; relative = swp.hwndInsertBehind) {
@@ -698,5 +740,5 @@
                 HRGN hrgnObst = GpiCreateRegion(hps, 0, NULL);
                 qt_WinProcessWindowObstacles(hwnd, &rclAff, hrgnObst, CRGN_OR,
-                                             PWO_Sibings | PWO_Ancestors |
+                                             PWO_Siblings | PWO_Ancestors |
                                              PWO_Screen | PWO_TopLevel);
                 // shift region of obstacles and affected region back to
@@ -1142,5 +1184,5 @@
 #if defined(QT_DEBUGWINCREATEDESTROY)
             qDebug() <<   "|Creating top level window (frame)" << q
-                     << "\n|  owner" << qDebugFmtHex(ownerw)
+                     << "\n|  owner" << qDebugHWND(ownerw)
                      << "\n|  title" << title
                      << "\n|  style" << qDebugFmtHex(fStyle)
@@ -1191,5 +1233,5 @@
 #if defined(QT_DEBUGWINCREATEDESTROY)
             qDebug() <<   "|Creating top level window (client)" << q
-                     << "\n|  owner & parent" << qDebugFmtHex(fId)
+                     << "\n|  owner & parent" << qDebugHWND(fId)
                      << "\n|  class" << className
                      << "\n|  title" << title
@@ -1325,8 +1367,8 @@
 #if defined(QT_DEBUGWINCREATEDESTROY)
         qDebug() <<   "|Creating child window" << q
-                 << "/n|  owner & parent" << qDebugFmtHex(parentw)
-                 << "/n|  class" << className
-                 << "/n|  title" << title
-                 << "/n|  style" << qDebugFmtHex(style);
+                 << "\n|  owner & parent" << qDebugHWND(parentw)
+                 << "\n|  class" << className
+                 << "\n|  title" << title
+                 << "\n|  style" << qDebugFmtHex(style);
 #endif
         id = WinCreateWindow(parentw, className, title, style,
@@ -1395,6 +1437,6 @@
             qDebug() << "|Destroying window" << this
                      << "\n|  hwnd"  << qDebugFmtHex(id);
-            if (id != winId())
-                qDebug() << "(frame) \n|  hwnd" << qDebugFmtHex(winId()) << "(client)";
+            if (id != internalWinId())
+                qDebug() << "|  hwnd" << qDebugFmtHex(internalWinId()) << "(client)";
 #endif
             qt_WinDestroyWindow(id);
@@ -1472,4 +1514,10 @@
     if (old_fid != NULLHANDLE && q->windowType() != Qt::Desktop) {
         // destroy HWND
+#if defined(QT_DEBUGWINCREATEDESTROY)
+            qDebug() << "|Destroying window" << q
+                     << "\n|  hwnd"  << qDebugFmtHex(old_fid);
+            if (old_fid != data.winid)
+                qDebug() << "|  hwnd" << qDebugFmtHex(data.winid) << "(client)";
+#endif
         qt_WinDestroyWindow(old_fid);
     }
@@ -2519,5 +2567,5 @@
         if (updateRcl.xLeft != updateRcl.xRight &&
             updateRcl.yBottom != updateRcl.yTop) {
-            qt_WinProcessWindowObstacles(data.winid, &updateRcl, 0, 0);
+            qt_WinProcessWindowObstacles(data.winid, &updateRcl, 0, 0, PWO_Default);
         }
     }
Index: /trunk/src/gui/kernel/qwindowdefs_pm.h
===================================================================
--- /trunk/src/gui/kernel/qwindowdefs_pm.h	(revision 1012)
+++ /trunk/src/gui/kernel/qwindowdefs_pm.h	(revision 1013)
@@ -76,4 +76,6 @@
 #define NULLHANDLE ((LHANDLE)0)
 
+#define APIENTRY _System
+
 // constants to address extra window data (nothing so far)
 #define QT_EXTRAWINDATASIZE     (sizeof(LONG) * 0)
@@ -90,17 +92,21 @@
 Q_GUI_EXPORT QWidget *qt_widget_from_hwnd(HWND hwnd);
 
-/** \internal flags for qt_WinProcessWindowObstacles() */
-enum {
+enum PWOFlags {
     PWO_Children = 0x01,
-    PWO_Sibings = 0x02,
+    PWO_Siblings = 0x02,
     PWO_Ancestors = 0x04,
     PWO_Screen = 0x08,
     PWO_TopLevel = 0x80000000,
-    // PWO_Default is suitable in most cases (for simple paint operations)
-    PWO_Default = PWO_Children | PWO_Sibings | PWO_Ancestors | PWO_Screen,
+    PWO_Default = 0 /*PWO_Children | PWO_Siblings | PWO_Ancestors | PWO_Screen*/,
 };
 
-Q_GUI_EXPORT LONG qt_WinProcessWindowObstacles(HWND hwnd, RECTL *prcl, HRGN hrgn,
-                                               LONG op, LONG flags = PWO_Default);
+#ifdef Q_QDOC
+LONG qt_WinProcessWindowObstacles(HWND hwnd, RECTL *prcl, HRGN hrgn,
+                                  LONG op, LONG flags);
+#else
+Q_GUI_EXPORT LONG APIENTRY qt_WinProcessWindowObstacles(HWND hwnd, RECTL *prcl,
+                                                        HRGN hrgn, LONG op,
+                                                        LONG flags);
+#endif
 
 // QDebug helpers for debugging various API types
