Add CascadeWindows wrapper

CHANGES.txt

@@ -13,6 +13,8 @@ https://mhammond.github.io/pywin32_installers.html.
 
 Coming in build 306, as yet unreleased
 --------------------------------------
+* Add CascadeWindows (#1999, @CristiFati)
+
 * Fix for service registration code updated in build 305 (#1985)
 
 * Support for Python 3.6 was dropped, support for later versions was improved.
@@ -33,7 +35,7 @@ Build 305, released 2022-11-06
   indicating whether the username should be returned, and related constants
   added. (@kxrob, #1946)
 
-* Added win32gui.GetTopWindow() and win32gui.GetAncestor() (@CristiFati, #1928)
+* Add win32gui.GetTopWindow() and win32gui.GetAncestor() (#1928, @CristiFati)
 
 * Tweaks to how pywintypes searches for DLLs to better support virtualenvs
   created with --system-site-packages. (@saaketp, #1933)

win32/Lib/win32con.py

@@ -1818,6 +1818,7 @@
 MDITILE_VERTICAL = 0
 MDITILE_HORIZONTAL = 1
 MDITILE_SKIPDISABLED = 2
+MDITILE_ZORDER = 4
 
 IMC_GETCANDIDATEPOS = 7
 IMC_SETCANDIDATEPOS = 8

win32/src/win32gui.i

@@ -3027,6 +3027,73 @@ BOOLAPI GetCaretPos(POINT *OUTPUT);
 // @pyswig |ShowCaret|Shows the caret at its current position
 BOOLAPI ShowCaret(HWND hWnd);	// @pyparm <o PyHANDLE>|hWnd||Window that owns the caret, can be 0.
 
+%{
+// @pyswig WORD|CascadeWindows|Cascade windows
+static PyObject *PyCascadeWindows(PyObject *self, PyObject *args)
+{
+    PyObject *hwndObject, *rectObject = Py_None, *childrenObject = Py_None;
+    UINT how = 0, childCount = 0;
+    RECT rect, *rectPtr = NULL;
+    HWND hwnd, *children = NULL;
+    WORD res = 0;
+    if (!PyArg_ParseTuple(args, "OI|OO:CascadeWindows",
+        &hwndObject,  //@pyparm <o PyHANDLE>|hwnd||Window handle
+        &how,  //@pyparm int|wHow||Cascade flag (win32con)
+        &rectObject,  //@pyparm <o PyHANDLE>|rect||Rectangle area (can be None)
+        &childrenObject)  //@pyparm <o PyHANDLE>|children||Tuple of child windows (can be None)
+    )
+        return NULL;
+    if (!PyWinObject_AsHANDLE(hwndObject, (HANDLE*)&hwnd))
+        return NULL;
+    // Parse out rectangle object
+    if (rectObject != Py_None) {
+        if (!PyArg_ParseTuple(rectObject, "llll",
+            &rect.left, &rect.top, &rect.right, &rect.bottom)
+        )
+            return NULL;
+        rectPtr = &rect;
+    }
+
+    if (PyTuple_Check(childrenObject)) {
+        childCount = (UINT)(PyTuple_GET_SIZE(childrenObject));
+        if (childCount) {
+            children = (HWND*)(malloc(sizeof(HWND) * childCount));
+            if (!children) {
+                PyErr_NoMemory();
+                return NULL;
+            }
+            for (UINT i = 0; i < childCount; ++i) {
+                if (!PyWinObject_AsHANDLE(PyTuple_GetItem(childrenObject, i), (HANDLE*)(&children[i]))) {
+                    free(children);
+                    return NULL;
+                }
+            }
+        }
+    } else if (childrenObject != Py_None) {
+        PyErr_SetString(PyExc_TypeError, "The child windows object is neither a tuple nor None");
+        return NULL;
+    }
+    Py_BEGIN_ALLOW_THREADS;
+    res = CascadeWindows(hwnd, how, rectPtr, childCount, children);
+    Py_END_ALLOW_THREADS;
+    if (children) {
+        free(children);
+    }
+    if (!res) {
+        DWORD gle = GetLastError();
+        // Only fail if GetLastError() != 0. In theory, there could be cases when function returns 0,
+        //   but it's not a failure (there are no windows to cascade).
+        if (gle) {
+            PyWin_SetAPIError("CascadeWindows", gle);
+            return NULL;
+        }
+    }
+    return PyLong_FromLong(res);
+}
+%}
+%native (CascadeWindows) PyCascadeWindows;
+
+
 // @pyswig boolean|ShowWindow|Shows or hides a window and changes its state
 BOOL ShowWindow(
 	HWND hWnd,		// @pyparm int|hWnd||The handle to the window