Changeset 1013 for trunk/src

Timestamp:

Aug 20, 2011, 8:26:35 PM (14 years ago)

Author:

Dmitry A. Kuminov

Message:

OS/2: Export qt_WinProcessWindowObstacles() as APIENTRY and document it.

This routine is necessary when 3rd-party applications paint directly to a HWND
of a Qt Widget bypassing Qt.

Location:

trunk/src/gui/kernel

Files:

• qwidget_pm.cpp (modified) (9 diffs)
• qwindowdefs_pm.h (modified) (2 diffs)

trunk/src/gui/kernel/qwidget_pm.cpp

@@ -231 +231 @@
 
 /*!
-    \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 +387 @@
     // 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 +740 @@
                 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 +1184 @@
 #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 +1233 @@
 #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 +1367 @@
 #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 +1437 @@
             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 +1514 @@
     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 +2567 @@
         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);
         }
     }

trunk/src/gui/kernel/qwindowdefs_pm.h

@@ -76 +76 @@
 #define NULLHANDLE ((LHANDLE)0)
 
+#define APIENTRY _System
+
 // constants to address extra window data (nothing so far)
 #define QT_EXTRAWINDATASIZE     (sizeof(LONG) * 0)
@@ -90 +92 @@
 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