Skip to content

Core & Native API Reference

This page provides the API reference for the native frame controller and Win32 ctypes types.

Frame Controller

qtframelesskit.core.frame_controller

Win32 native window frame message controller.

Encapsulates non-client calculations, border resize hit testing, non-client mouse events, DPI changes, and native window drag delegation.

WindowFrameController

Controller managing native Win32 window frame messages and sizing logic.

Parameters:

Name Type Description Default
window QWidget

Target top-level window widget.

required
borderWidth int

Resize border thickness in pixels.

5
resizable bool

Whether window resizing is enabled.

True
pressToMove bool

Whether press-to-move window dragging is enabled.

True
dpiScaling bool

Whether automatic DPI scaling is allowed.

True
Source code in src/qtframelesskit/core/frame_controller.py
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
class WindowFrameController:
    """Controller managing native Win32 window frame messages and sizing logic.

    Parameters
    ----------
    window : QWidget
        Target top-level window widget.
    borderWidth : int, default=5
        Resize border thickness in pixels.
    resizable : bool, default=True
        Whether window resizing is enabled.
    pressToMove : bool, default=True
        Whether press-to-move window dragging is enabled.
    dpiScaling : bool, default=True
        Whether automatic DPI scaling is allowed.
    """

    def __init__(
        self,
        window: QWidget,
        borderWidth: int = 5,
        resizable: bool = True,
        pressToMove: bool = True,
        dpiScaling: bool = True,
    ) -> None:
        self._window = window
        self._borderWidth = borderWidth
        self._border_width = borderWidth
        self._resizable = resizable
        self._pressToMove = pressToMove
        self._dpiScalingFlag = dpiScaling

    def getBorderWidth(self) -> int:
        """Return the resize border thickness in pixels.

        Returns
        -------
        int
            Border width in pixels.
        """
        return self._borderWidth

    def setBorderWidth(self, width: int) -> None:
        """Set the resize border thickness in pixels.

        Parameters
        ----------
        width : int
            New border width in pixels.
        """
        self._borderWidth = width
        self._border_width = width
        if hasattr(self._window, "_borderWidth"):
            self._window._borderWidth = width
            self._window._border_width = width

    def isResizable(self) -> bool:
        """Return whether the window can be resized.

        Returns
        -------
        bool
            True if resizing is allowed.
        """
        return self._resizable

    def setResizable(self, resizable: bool) -> None:
        """Set whether the window is resizable.

        Parameters
        ----------
        resizable : bool
            True to allow resizing.
        """
        self._resizable = resizable

    def isPressToMove(self) -> bool:
        """Return whether press-to-move dragging is enabled.

        Returns
        -------
        bool
            True if press-to-move is enabled.
        """
        return self._pressToMove

    def setPressToMove(self, enabled: bool) -> None:
        """Enable or disable press-to-move window dragging.

        Parameters
        ----------
        enabled : bool
            True to enable press-to-move.
        """
        self._pressToMove = enabled

    def isDpiScalingAllowed(self) -> bool:
        """Return whether automatic DPI scaling is allowed.

        Returns
        -------
        bool
            True if automatic DPI scaling is allowed.
        """
        return self._dpiScalingFlag

    def setDpiScalingAllowed(self, allow: bool) -> None:
        """Enable or disable automatic DPI scaling.

        Parameters
        ----------
        allow : bool
            True to allow automatic DPI scaling.
        """
        self._dpiScalingFlag = allow

    def startSystemMove(self) -> None:
        """Start native system window drag."""
        targetWindow = self._window.window()
        if targetWindow:
            windowHandle = targetWindow.windowHandle()
            if windowHandle:
                windowHandle.startSystemMove()

    def _getTitleBar(self) -> "TitleBar | None":
        """Return title bar instance associated with target window if present.

        Returns
        -------
        TitleBar or None
            Title bar instance or None.
        """
        if hasattr(self._window, "getTitleBar"):
            return self._window.getTitleBar()
        return getattr(self._window, "_titleBar", None)

    def handleNativeEvent(
        self, eventType: QByteArray | bytes, message: int
    ) -> tuple[bool, int] | None:
        """Process native Win32 messages for window framing, sizing, and hit testing.

        Parameters
        ----------
        eventType : QByteArray or bytes
            Native event type identifier.
        message : int
            Pointer address to the native Win32 MSG structure.

        Returns
        -------
        tuple of (bool, int) or None
            Tuple of (True, result_code) when message is handled, or None when unhandled.
        """
        _ = eventType
        msg = MSG.from_address(int(message))
        if not msg.hWnd:
            return None

        msgType = msg.message
        if msgType == win32con.WM_NCHITTEST:
            return self._handleNcHitTest(msg)
        if msgType == win32con.WM_NCMOUSEMOVE:
            return self._handleNcMouseMove(msg)
        if msgType == WM_NCMOUSELEAVE:
            return self._handleNcMouseLeave(msg)
        if msgType == win32con.WM_NCLBUTTONDOWN:
            return self._handleNcLButtonDown(msg)
        if msgType == win32con.WM_NCLBUTTONUP:
            return self._handleNcLButtonUp(msg)
        if msgType == win32con.WM_NCCALCSIZE:
            return self._handleNcCalcSize(msg)
        if msgType == win32con.WM_SETTINGCHANGE:
            return self._handleSettingChange(msg)
        if msgType == win32con.WM_STYLECHANGING:
            return self._handleStyleChanging(msg)
        if msgType == WM_DPICHANGED:
            return self._handleDpiChanged(msg)

        return None

    def _handleNcHitTest(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_NCHITTEST message for window border and title bar hit testing.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int) or None
            Hit test result if handled, or None if in client area / unhandled.
        """
        if self._resizable:
            if not self._window.isMaximized():
                cursorPosition = QCursor.pos()
                x = cursorPosition.x() - self._window.x()
                y = cursorPosition.y() - self._window.y()
                width, height = self._window.width(), self._window.height()

                dpi = getDpiForWindow(msg.hWnd)
                scaledBorderWidth = round(self._borderWidth * dpi / 96)

                left = x < scaledBorderWidth
                top = y < scaledBorderWidth
                right = x > width - scaledBorderWidth
                bottom = y > height - scaledBorderWidth

                if top and left:
                    return True, win32con.HTTOPLEFT
                if top and right:
                    return True, win32con.HTTOPRIGHT
                if bottom and left:
                    return True, win32con.HTBOTTOMLEFT
                if bottom and right:
                    return True, win32con.HTBOTTOMRIGHT
                if left:
                    return True, win32con.HTLEFT
                if top:
                    return True, win32con.HTTOP
                if right:
                    return True, win32con.HTRIGHT
                if bottom:
                    return True, win32con.HTBOTTOM

            titleBar = self._getTitleBar()
            if titleBar is not None:
                maximizeButton = titleBar.getMaximizeButton()
                if maximizeButton is not None and maximizeButton.isVisible():
                    buttonPosition = maximizeButton.mapTo(
                        typeCast(QWidget, self._window), QPoint(0, 0)
                    )
                    buttonRect = QRect(buttonPosition, maximizeButton.size())
                    cursorPosition = QCursor.pos()
                    windowPoint = self._window.mapFromGlobal(cursorPosition)
                    if buttonRect.contains(windowPoint):
                        return True, win32con.HTMAXBUTTON
        return None

    def _handleNcMouseMove(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_NCMOUSEMOVE message for snap layout maximize button hovering.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int) or None
            (True, 0) if handled, or None if unhandled.
        """
        titleBar = self._getTitleBar()
        if titleBar is not None:
            maximizeButton = titleBar.getMaximizeButton()
            if maximizeButton is not None:
                if msg.wParam == win32con.HTMAXBUTTON:
                    maximizeButton.setHoverState(True)
                    trackMouseEvent = TRACKMOUSEEVENT()
                    trackMouseEvent.cbSize = sizeof(TRACKMOUSEEVENT)
                    trackMouseEvent.dwFlags = TME_NONCLIENT | TME_LEAVE
                    trackMouseEvent.hwndTrack = msg.hWnd
                    trackMouseEvent.dwHoverTime = 0
                    windll.user32.TrackMouseEvent(byref(trackMouseEvent))
                    return True, 0
                if maximizeButton.isHovered():
                    maximizeButton.setHoverState(False)
                    maximizeButton.setPressedState(False)
        return None

    def _handleNcMouseLeave(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_NCMOUSELEAVE message to reset maximize button hover state.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int)
            (True, 0) indicating handled event.
        """
        _ = msg
        titleBar = self._getTitleBar()
        if titleBar is not None:
            maximizeButton = titleBar.getMaximizeButton()
            if maximizeButton is not None:
                maximizeButton.setHoverState(False)
                maximizeButton.setPressedState(False)
        return True, 0

    def _handleNcLButtonDown(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_NCLBUTTONDOWN message for maximize button pressing.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int) or None
            (True, 0) if handled, or None if unhandled.
        """
        if msg.wParam == win32con.HTMAXBUTTON:
            titleBar = self._getTitleBar()
            if titleBar is not None:
                maximizeButton = titleBar.getMaximizeButton()
                if maximizeButton is not None:
                    maximizeButton.setPressedState(True)
            return True, 0
        return None

    def _handleNcLButtonUp(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_NCLBUTTONUP message for maximize button clicking and window toggle.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int) or None
            (True, 0) if handled, or None if unhandled.
        """
        titleBar = self._getTitleBar()
        if msg.wParam == win32con.HTMAXBUTTON:
            if titleBar is not None:
                maximizeButton = titleBar.getMaximizeButton()
                if maximizeButton is not None:
                    maximizeButton.setPressedState(False)
            if self._window.isMaximized():
                self._window.showNormal()
            else:
                self._window.showMaximized()
            return True, 0

        if titleBar is not None:
            maximizeButton = titleBar.getMaximizeButton()
            if maximizeButton is not None and maximizeButton.isPressedState():
                maximizeButton.setPressedState(False)
        return None

    def _handleNcCalcSize(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_NCCALCSIZE message for removing standard window frame.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int)
            (True, result_code) calculation result.
        """
        if msg.wParam:
            rect = cast(msg.lParam, LPNCCALCSIZE_PARAMS).contents.rgrc[0]
        else:
            rect = cast(msg.lParam, LPRECT).contents

        maximized = isMaximized(msg.hWnd)
        fullScreen = isFullScreen(msg.hWnd)

        if maximized and not fullScreen:
            thickness = getResizeBorderThickness(msg.hWnd)
            rect.top += thickness
            rect.left += thickness
            rect.right -= thickness
            rect.bottom -= thickness

        if (maximized or fullScreen) and Taskbar.isAutoHide():
            position = Taskbar.getPosition(msg.hWnd)
            if position == Taskbar.TOP:
                rect.top += Taskbar.AUTO_HIDE_THICKNESS
            elif position == Taskbar.BOTTOM:
                rect.bottom -= Taskbar.AUTO_HIDE_THICKNESS
            elif position == Taskbar.LEFT:
                rect.left += Taskbar.AUTO_HIDE_THICKNESS
            elif position == Taskbar.RIGHT:
                rect.right -= Taskbar.AUTO_HIDE_THICKNESS

        result = 0 if not msg.wParam else win32con.WVR_REDRAW
        return True, result

    def _handleSettingChange(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_SETTINGCHANGE message to sync system theme mode if allowed.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int)
            (True, 0) indicating handled event.
        """
        _ = msg
        if getattr(self._window, "isDetectingThemeAllowed", lambda: False)():
            getattr(self._window, "_setCurrentWindowsTheme", lambda: None)()
        return True, 0

    def _handleStyleChanging(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_STYLECHANGING message to update resizable and pressToMove permissions.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int)
            (True, 0) indicating handled event.
        """
        _ = msg
        isFull = self._window.isFullScreen()
        self.setResizable(not isFull)
        self.setPressToMove(not isFull)
        if hasattr(self._window, "_resizable"):
            self._window._resizable = not isFull
        if hasattr(self._window, "_pressToMove"):
            self._window._pressToMove = not isFull
        return True, 0

    def _handleDpiChanged(self, msg: MSG) -> tuple[bool, int] | None:
        """Process WM_DPICHANGED message to rescale title bar and notify DWM.

        Parameters
        ----------
        msg : MSG
            Win32 MSG structure pointer.

        Returns
        -------
        tuple of (bool, int)
            (True, 0) indicating handled event.
        """
        if self._dpiScalingFlag:
            titleBar = self._getTitleBar()
            if titleBar is not None:
                newDpi = msg.wParam & 0xFFFF
                if newDpi <= 0:
                    newDpi = getDpiForWindow(msg.hWnd)
                titleBar.updateDpiScaling(newDpi)
        win32gui.SetWindowPos(
            msg.hWnd,
            None,
            0,
            0,
            0,
            0,
            win32con.SWP_NOMOVE
            | win32con.SWP_NOSIZE
            | win32con.SWP_NOZORDER
            | win32con.SWP_FRAMECHANGED,
        )
        return True, 0

getBorderWidth()

Return the resize border thickness in pixels.

Returns:

Type Description
int

Border width in pixels.

Source code in src/qtframelesskit/core/frame_controller.py
def getBorderWidth(self) -> int:
    """Return the resize border thickness in pixels.

    Returns
    -------
    int
        Border width in pixels.
    """
    return self._borderWidth

handleNativeEvent(eventType, message)

Process native Win32 messages for window framing, sizing, and hit testing.

Parameters:

Name Type Description Default
eventType QByteArray or bytes

Native event type identifier.

required
message int

Pointer address to the native Win32 MSG structure.

required

Returns:

Type Description
tuple of (bool, int) or None

Tuple of (True, result_code) when message is handled, or None when unhandled.

Source code in src/qtframelesskit/core/frame_controller.py
def handleNativeEvent(
    self, eventType: QByteArray | bytes, message: int
) -> tuple[bool, int] | None:
    """Process native Win32 messages for window framing, sizing, and hit testing.

    Parameters
    ----------
    eventType : QByteArray or bytes
        Native event type identifier.
    message : int
        Pointer address to the native Win32 MSG structure.

    Returns
    -------
    tuple of (bool, int) or None
        Tuple of (True, result_code) when message is handled, or None when unhandled.
    """
    _ = eventType
    msg = MSG.from_address(int(message))
    if not msg.hWnd:
        return None

    msgType = msg.message
    if msgType == win32con.WM_NCHITTEST:
        return self._handleNcHitTest(msg)
    if msgType == win32con.WM_NCMOUSEMOVE:
        return self._handleNcMouseMove(msg)
    if msgType == WM_NCMOUSELEAVE:
        return self._handleNcMouseLeave(msg)
    if msgType == win32con.WM_NCLBUTTONDOWN:
        return self._handleNcLButtonDown(msg)
    if msgType == win32con.WM_NCLBUTTONUP:
        return self._handleNcLButtonUp(msg)
    if msgType == win32con.WM_NCCALCSIZE:
        return self._handleNcCalcSize(msg)
    if msgType == win32con.WM_SETTINGCHANGE:
        return self._handleSettingChange(msg)
    if msgType == win32con.WM_STYLECHANGING:
        return self._handleStyleChanging(msg)
    if msgType == WM_DPICHANGED:
        return self._handleDpiChanged(msg)

    return None

isDpiScalingAllowed()

Return whether automatic DPI scaling is allowed.

Returns:

Type Description
bool

True if automatic DPI scaling is allowed.

Source code in src/qtframelesskit/core/frame_controller.py
def isDpiScalingAllowed(self) -> bool:
    """Return whether automatic DPI scaling is allowed.

    Returns
    -------
    bool
        True if automatic DPI scaling is allowed.
    """
    return self._dpiScalingFlag

isPressToMove()

Return whether press-to-move dragging is enabled.

Returns:

Type Description
bool

True if press-to-move is enabled.

Source code in src/qtframelesskit/core/frame_controller.py
def isPressToMove(self) -> bool:
    """Return whether press-to-move dragging is enabled.

    Returns
    -------
    bool
        True if press-to-move is enabled.
    """
    return self._pressToMove

isResizable()

Return whether the window can be resized.

Returns:

Type Description
bool

True if resizing is allowed.

Source code in src/qtframelesskit/core/frame_controller.py
def isResizable(self) -> bool:
    """Return whether the window can be resized.

    Returns
    -------
    bool
        True if resizing is allowed.
    """
    return self._resizable

setBorderWidth(width)

Set the resize border thickness in pixels.

Parameters:

Name Type Description Default
width int

New border width in pixels.

required
Source code in src/qtframelesskit/core/frame_controller.py
def setBorderWidth(self, width: int) -> None:
    """Set the resize border thickness in pixels.

    Parameters
    ----------
    width : int
        New border width in pixels.
    """
    self._borderWidth = width
    self._border_width = width
    if hasattr(self._window, "_borderWidth"):
        self._window._borderWidth = width
        self._window._border_width = width

setDpiScalingAllowed(allow)

Enable or disable automatic DPI scaling.

Parameters:

Name Type Description Default
allow bool

True to allow automatic DPI scaling.

required
Source code in src/qtframelesskit/core/frame_controller.py
def setDpiScalingAllowed(self, allow: bool) -> None:
    """Enable or disable automatic DPI scaling.

    Parameters
    ----------
    allow : bool
        True to allow automatic DPI scaling.
    """
    self._dpiScalingFlag = allow

setPressToMove(enabled)

Enable or disable press-to-move window dragging.

Parameters:

Name Type Description Default
enabled bool

True to enable press-to-move.

required
Source code in src/qtframelesskit/core/frame_controller.py
def setPressToMove(self, enabled: bool) -> None:
    """Enable or disable press-to-move window dragging.

    Parameters
    ----------
    enabled : bool
        True to enable press-to-move.
    """
    self._pressToMove = enabled

setResizable(resizable)

Set whether the window is resizable.

Parameters:

Name Type Description Default
resizable bool

True to allow resizing.

required
Source code in src/qtframelesskit/core/frame_controller.py
def setResizable(self, resizable: bool) -> None:
    """Set whether the window is resizable.

    Parameters
    ----------
    resizable : bool
        True to allow resizing.
    """
    self._resizable = resizable

startSystemMove()

Start native system window drag.

Source code in src/qtframelesskit/core/frame_controller.py
def startSystemMove(self) -> None:
    """Start native system window drag."""
    targetWindow = self._window.window()
    if targetWindow:
        windowHandle = targetWindow.windowHandle()
        if windowHandle:
            windowHandle.startSystemMove()

Win32 Types

qtframelesskit.native.win32_types

ctypes mirrors of Win32 structures used by the frameless window machinery.

All types here map 1-to-1 to their C counterparts in the Windows SDK. They are consumed by WM_NCCALCSIZE and DWM attribute handlers in the frameless window implementation.

ACCENT_POLICY

Bases: Structure

ctypes mirror of the Win32 ACCENT_POLICY structure.

Configures window accent attributes such as Acrylic blur behind and tint.

Source code in src/qtframelesskit/native/win32_types.py
class ACCENT_POLICY(Structure):
    """ctypes mirror of the Win32 ``ACCENT_POLICY`` structure.

    Configures window accent attributes such as Acrylic blur behind and tint.
    """

    _fields_ = [
        ("AccentState", DWORD),
        ("AccentFlags", DWORD),
        ("GradientColor", DWORD),
        ("AnimationId", DWORD),
    ]

ACCENT_STATE

Bases: Enum

Win32 SetWindowCompositionAttribute accent policy states.

Attributes:

Name Type Description
ACCENT_DISABLED int

Disables composition accent policy.

ACCENT_ENABLE_GRADIENT int

Enables solid gradient fill.

ACCENT_ENABLE_TRANSPARENTGRADIENT int

Enables translucent gradient fill.

ACCENT_ENABLE_BLURBEHIND int

Enables classic Aero blur behind.

ACCENT_ENABLE_ACRYLICBLURBEHIND int

Enables modern Fluent Acrylic blur behind.

ACCENT_ENABLE_HOSTBACKDROP int

Enables host backdrop blur.

ACCENT_INVALID_STATE int

Invalid accent state boundary.

Source code in src/qtframelesskit/native/win32_types.py
class ACCENT_STATE(Enum):
    """Win32 SetWindowCompositionAttribute accent policy states.

    Attributes
    ----------
    ACCENT_DISABLED : int
        Disables composition accent policy.
    ACCENT_ENABLE_GRADIENT : int
        Enables solid gradient fill.
    ACCENT_ENABLE_TRANSPARENTGRADIENT : int
        Enables translucent gradient fill.
    ACCENT_ENABLE_BLURBEHIND : int
        Enables classic Aero blur behind.
    ACCENT_ENABLE_ACRYLICBLURBEHIND : int
        Enables modern Fluent Acrylic blur behind.
    ACCENT_ENABLE_HOSTBACKDROP : int
        Enables host backdrop blur.
    ACCENT_INVALID_STATE : int
        Invalid accent state boundary.
    """

    ACCENT_DISABLED = 0
    ACCENT_ENABLE_GRADIENT = 1
    ACCENT_ENABLE_TRANSPARENTGRADIENT = 2
    ACCENT_ENABLE_BLURBEHIND = 3
    ACCENT_ENABLE_ACRYLICBLURBEHIND = 4
    ACCENT_ENABLE_HOSTBACKDROP = 5
    ACCENT_INVALID_STATE = 6

DWMWINDOWATTRIBUTE

Bases: Enum

Subset of the Win32 DWMWINDOWATTRIBUTE enum used by this library.

Passed to DwmSetWindowAttribute to toggle immersive dark mode, corner rounding preference, border color, and system backdrop materials.

Source code in src/qtframelesskit/native/win32_types.py
class DWMWINDOWATTRIBUTE(Enum):
    """Subset of the Win32 ``DWMWINDOWATTRIBUTE`` enum used by this library.

    Passed to ``DwmSetWindowAttribute`` to toggle immersive dark mode, corner
    rounding preference, border color, and system backdrop materials.
    """

    DWMWA_USE_IMMERSIVE_DARK_MODE = 20
    DWMWA_WINDOW_CORNER_PREFERENCE = 33
    DWMWA_BORDER_COLOR = 34
    DWMWA_CAPTION_COLOR = 35
    DWMWA_TEXT_COLOR = 36
    DWMWA_SYSTEMBACKDROP_TYPE = 38
    DWMWA_MICA_EFFECT = 1029

DWM_BLURBEHIND

Bases: Structure

ctypes mirror of the Win32 DWM_BLURBEHIND structure.

Passed to DwmEnableBlurBehindWindow to enable desktop window manager blur-behind.

Source code in src/qtframelesskit/native/win32_types.py
class DWM_BLURBEHIND(Structure):
    """ctypes mirror of the Win32 ``DWM_BLURBEHIND`` structure.

    Passed to ``DwmEnableBlurBehindWindow`` to enable desktop window manager blur-behind.
    """

    _fields_ = [
        ("dwFlags", DWORD),
        ("fEnable", BOOL),
        ("hRgnBlur", c_void_p),
        ("fTransitionOnMaximized", BOOL),
    ]

DWM_SYSTEMBACKDROP_TYPE

Bases: Enum

Win32 DWM_SYSTEMBACKDROP_TYPE enum values for Windows 11 Build 22621+.

Attributes:

Name Type Description
AUTO int

System determines backdrop type automatically.

NONE int

No backdrop material.

MAINWINDOW int

Mica material for main application window.

TRANSIENTWINDOW int

Acrylic backdrop material.

TABBEDWINDOW int

Mica Alt material for tabbed windows.

Source code in src/qtframelesskit/native/win32_types.py
class DWM_SYSTEMBACKDROP_TYPE(Enum):
    """Win32 DWM_SYSTEMBACKDROP_TYPE enum values for Windows 11 Build 22621+.

    Attributes
    ----------
    AUTO : int
        System determines backdrop type automatically.
    NONE : int
        No backdrop material.
    MAINWINDOW : int
        Mica material for main application window.
    TRANSIENTWINDOW : int
        Acrylic backdrop material.
    TABBEDWINDOW : int
        Mica Alt material for tabbed windows.
    """

    AUTO = 0
    NONE = 1
    MAINWINDOW = 2
    TRANSIENTWINDOW = 3
    TABBEDWINDOW = 4

MARGINS

Bases: Structure

ctypes mirror of the Win32 MARGINS structure.

Passed to DwmExtendFrameIntoClientArea to control the DWM glass frame extension on each edge of the window.

Source code in src/qtframelesskit/native/win32_types.py
class MARGINS(Structure):
    """ctypes mirror of the Win32 ``MARGINS`` structure.

    Passed to ``DwmExtendFrameIntoClientArea`` to control the DWM glass
    frame extension on each edge of the window.
    """

    _fields_ = [
        ("cxLeftWidth", c_int),
        ("cxRightWidth", c_int),
        ("cyTopHeight", c_int),
        ("cyBottomHeight", c_int),
    ]

NCCALCSIZE_PARAMS

Bases: Structure

ctypes mirror of the Win32 NCCALCSIZE_PARAMS structure.

Passed via lParam in WM_NCCALCSIZE when wParam is non-zero. rgrc[0] holds the proposed new client rect that we adjust to remove the native title bar from the non-client area calculation.

Source code in src/qtframelesskit/native/win32_types.py
class NCCALCSIZE_PARAMS(Structure):
    """ctypes mirror of the Win32 ``NCCALCSIZE_PARAMS`` structure.

    Passed via ``lParam`` in ``WM_NCCALCSIZE`` when ``wParam`` is non-zero.
    ``rgrc[0]`` holds the proposed new client rect that we adjust to remove
    the native title bar from the non-client area calculation.
    """

    _fields_ = [
        ("rgrc", RECT * 3),
        ("lppos", POINTER(PWINDOWPOS)),
    ]

PWINDOWPOS

Bases: Structure

ctypes mirror of the Win32 WINDOWPOS structure.

Embedded inside :class:NCCALCSIZE_PARAMS and passed to WM_NCCALCSIZE to describe the new window position and size.

Source code in src/qtframelesskit/native/win32_types.py
class PWINDOWPOS(Structure):
    """ctypes mirror of the Win32 ``WINDOWPOS`` structure.

    Embedded inside :class:`NCCALCSIZE_PARAMS` and passed to
    ``WM_NCCALCSIZE`` to describe the new window position and size.
    """

    _fields_ = [
        ("hWnd", HWND),
        ("hwndInsertAfter", HWND),
        ("x", c_int),
        ("y", c_int),
        ("cx", c_int),
        ("cy", c_int),
        ("flags", UINT),
    ]

TRACKMOUSEEVENT

Bases: Structure

ctypes mirror of the Win32 TRACKMOUSEEVENT structure.

Passed to TrackMouseEvent to request non-client mouse leave notifications.

Source code in src/qtframelesskit/native/win32_types.py
class TRACKMOUSEEVENT(Structure):
    """ctypes mirror of the Win32 ``TRACKMOUSEEVENT`` structure.

    Passed to ``TrackMouseEvent`` to request non-client mouse leave notifications.
    """

    _fields_ = [
        ("cbSize", DWORD),
        ("dwFlags", DWORD),
        ("hwndTrack", HWND),
        ("dwHoverTime", DWORD),
    ]

WINDOWCOMPOSITIONATTRIBDATA

Bases: Structure

ctypes mirror of the Win32 WINDOWCOMPOSITIONATTRIBDATA structure.

Passed to SetWindowCompositionAttribute to apply accent policies.

Source code in src/qtframelesskit/native/win32_types.py
class WINDOWCOMPOSITIONATTRIBDATA(Structure):
    """ctypes mirror of the Win32 ``WINDOWCOMPOSITIONATTRIBDATA`` structure.

    Passed to ``SetWindowCompositionAttribute`` to apply accent policies.
    """

    _fields_ = [
        ("Attrib", DWORD),
        ("pvData", c_void_p),
        ("cbData", c_size_t),
    ]

WindowCornerPreference

Bases: IntEnum

Windows 11 window corner rounding preferences.

Values correspond directly to DWM_WINDOW_CORNER_PREFERENCE constants.

Source code in src/qtframelesskit/native/win32_types.py
class WindowCornerPreference(IntEnum):
    """Windows 11 window corner rounding preferences.

    Values correspond directly to ``DWM_WINDOW_CORNER_PREFERENCE`` constants.
    """

    DEFAULT = 0
    DO_NOT_ROUND = 1
    ROUND = 2
    ROUND_SMALL = 3

WindowEffect

Bases: Enum

Supported native Windows backdrop materials and effects.

Attributes:

Name Type Description
NONE int

Default solid window background with no backdrop material.

MICA int

Windows 11 Mica material matching system theme and desktop wallpaper.

ACRYLIC int

Windows 10/11 Acrylic blur-behind material with custom tint.

MICA_ALT int

Windows 11 Mica Alt (tabbed) material for secondary surfaces.

Source code in src/qtframelesskit/native/win32_types.py
class WindowEffect(Enum):
    """Supported native Windows backdrop materials and effects.

    Attributes
    ----------
    NONE : int
        Default solid window background with no backdrop material.
    MICA : int
        Windows 11 Mica material matching system theme and desktop wallpaper.
    ACRYLIC : int
        Windows 10/11 Acrylic blur-behind material with custom tint.
    MICA_ALT : int
        Windows 11 Mica Alt (tabbed) material for secondary surfaces.
    """

    NONE = 0
    MICA = 1
    ACRYLIC = 2
    MICA_ALT = 3

colorToColorRef(color)

Convert a QColor or hex string into a Win32 COLORREF integer (0x00BBGGRR).

Parameters:

Name Type Description Default
color QColor or str

Color representation to convert.

required

Returns:

Type Description
int

Win32 COLORREF representation (0x00BBGGRR), or 0xFFFFFFFE (default) if invalid.

Source code in src/qtframelesskit/native/win32_types.py
def colorToColorRef(color: object) -> int:
    """Convert a QColor or hex string into a Win32 COLORREF integer (0x00BBGGRR).

    Parameters
    ----------
    color : QColor or str
        Color representation to convert.

    Returns
    -------
    int
        Win32 COLORREF representation (0x00BBGGRR), or 0xFFFFFFFE (default) if invalid.
    """
    from qtpy.QtGui import QColor

    qcolor: QColor
    if isinstance(color, str):
        qcolor = QColor(color)
    elif isinstance(color, QColor):
        qcolor = color
    else:
        return 0xFFFFFFFE

    if not qcolor.isValid():
        return 0xFFFFFFFE

    return (qcolor.blue() << 16) | (qcolor.green() << 8) | qcolor.red()