Skip to content

Title Bar API Reference

This page provides the API reference for the custom title bar and button controls in qtframelesskit.windows.title_bar.

qtframelesskit.windows.title_bar

Modular title bar package providing custom title bars, buttons, and drag handling.

Exposes the main TitleBar widget, vector control buttons, MenuStyler for Fluent styling, and TitleBarDragHandler for system drag and maximize interactions.

CloseButton

Bases: VectorButton

Window close button with diagonal cross vector glyph and red highlight.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
class CloseButton(VectorButton):
    """Window close button with diagonal cross vector glyph and red highlight."""

    def _getHoverColor(self) -> QColor:
        """Return target red hover background color.

        Returns
        -------
        QColor
            Red hover highlight color.
        """
        if self._customHoverColor is not None:
            return self._customHoverColor
        return QColor("#e81123")

    def _getPressedColor(self) -> QColor:
        """Return target light red pressed background color.

        Returns
        -------
        QColor
            Light red pressed highlight color.
        """
        if self._customPressedColor is not None:
            return self._customPressedColor
        return QColor("#f1707a")

    def paintEvent(self, event: QPaintEvent) -> None:
        """Paint vector diagonal cross glyph with white stroke on hover/press.

        Parameters
        ----------
        event : QPaintEvent
            The paint event.
        """
        super().paintEvent(event)
        painter = QPainter(self)
        painter.setRenderHint(QPainter.RenderHint.Antialiasing)

        # White glyph on hover/pressed red background, normal color otherwise
        isHighlighted = self.isHovered() or self.isPressedState()
        strokeColor = QColor("#ffffff") if isHighlighted else self._glyphColor
        scaleFactor = self.getGlyphScaleFactor()
        pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
        painter.setPen(pen)

        centerX = self.width() / 2.0
        centerY = self.height() / 2.0
        crossOffset = 4.5 * scaleFactor

        painter.drawLine(
            QPointF(centerX - crossOffset, centerY - crossOffset),
            QPointF(centerX + crossOffset, centerY + crossOffset),
        )
        painter.drawLine(
            QPointF(centerX - crossOffset, centerY + crossOffset),
            QPointF(centerX + crossOffset, centerY - crossOffset),
        )
        painter.end()

paintEvent(event)

Paint vector diagonal cross glyph with white stroke on hover/press.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def paintEvent(self, event: QPaintEvent) -> None:
    """Paint vector diagonal cross glyph with white stroke on hover/press.

    Parameters
    ----------
    event : QPaintEvent
        The paint event.
    """
    super().paintEvent(event)
    painter = QPainter(self)
    painter.setRenderHint(QPainter.RenderHint.Antialiasing)

    # White glyph on hover/pressed red background, normal color otherwise
    isHighlighted = self.isHovered() or self.isPressedState()
    strokeColor = QColor("#ffffff") if isHighlighted else self._glyphColor
    scaleFactor = self.getGlyphScaleFactor()
    pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
    painter.setPen(pen)

    centerX = self.width() / 2.0
    centerY = self.height() / 2.0
    crossOffset = 4.5 * scaleFactor

    painter.drawLine(
        QPointF(centerX - crossOffset, centerY - crossOffset),
        QPointF(centerX + crossOffset, centerY + crossOffset),
    )
    painter.drawLine(
        QPointF(centerX - crossOffset, centerY + crossOffset),
        QPointF(centerX + crossOffset, centerY - crossOffset),
    )
    painter.end()

FullScreenButton

Bases: VectorButton

Window fullscreen toggle button rendering vector frame glyph.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
class FullScreenButton(VectorButton):
    """Window fullscreen toggle button rendering vector frame glyph."""

    def paintEvent(self, event: QPaintEvent) -> None:
        """Paint vector fullscreen glyph.

        Parameters
        ----------
        event : QPaintEvent
            The paint event.
        """
        super().paintEvent(event)
        painter = QPainter(self)
        painter.setRenderHint(QPainter.RenderHint.Antialiasing)

        scaleFactor = self.getGlyphScaleFactor()
        strokeColor = self._hoverGlyphColor if self.isHovered() else self._glyphColor
        pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
        painter.setPen(pen)
        painter.setBrush(Qt.BrushStyle.NoBrush)

        centerX = self.width() / 2.0
        centerY = self.height() / 2.0
        frameSize = 10.0 * scaleFactor
        frameRect = QRectF(
            centerX - (frameSize / 2.0), centerY - (frameSize / 2.0), frameSize, frameSize
        )
        painter.drawRect(frameRect)
        painter.end()

paintEvent(event)

Paint vector fullscreen glyph.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def paintEvent(self, event: QPaintEvent) -> None:
    """Paint vector fullscreen glyph.

    Parameters
    ----------
    event : QPaintEvent
        The paint event.
    """
    super().paintEvent(event)
    painter = QPainter(self)
    painter.setRenderHint(QPainter.RenderHint.Antialiasing)

    scaleFactor = self.getGlyphScaleFactor()
    strokeColor = self._hoverGlyphColor if self.isHovered() else self._glyphColor
    pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
    painter.setPen(pen)
    painter.setBrush(Qt.BrushStyle.NoBrush)

    centerX = self.width() / 2.0
    centerY = self.height() / 2.0
    frameSize = 10.0 * scaleFactor
    frameRect = QRectF(
        centerX - (frameSize / 2.0), centerY - (frameSize / 2.0), frameSize, frameSize
    )
    painter.drawRect(frameRect)
    painter.end()

MaximizeButton

Bases: VectorButton

Window maximize and restore button rendering vector rectangles.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
class MaximizeButton(VectorButton):
    """Window maximize and restore button rendering vector rectangles."""

    def __init__(self, parent: QWidget | None = None) -> None:
        super().__init__(parent)
        self._isMaximized = False

    def isMaximizedState(self) -> bool:
        """Return whether the button displays the restored or maximized glyph.

        Returns
        -------
        bool
            True if currently displaying restored glyph for a maximized window.
        """
        return self._isMaximized

    def setMaximizedState(self, isMaximized: bool) -> None:
        """Update button glyph state to reflect window maximize status.

        Parameters
        ----------
        isMaximized : bool
            True if the parent window is maximized.
        """
        if self._isMaximized != isMaximized:
            self._isMaximized = isMaximized
            self.update()

    def paintEvent(self, event: QPaintEvent) -> None:
        """Paint vector rectangle or overlapping restore rectangles.

        Parameters
        ----------
        event : QPaintEvent
            The paint event.
        """
        super().paintEvent(event)
        painter = QPainter(self)
        painter.setRenderHint(QPainter.RenderHint.Antialiasing)

        isHovered = self.isHovered()

        scaleFactor = self.getGlyphScaleFactor()
        strokeColor = self._hoverGlyphColor if isHovered else self._glyphColor
        pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
        painter.setPen(pen)
        painter.setBrush(Qt.BrushStyle.NoBrush)

        centerX = self.width() / 2.0
        centerY = self.height() / 2.0

        if self._isMaximized:
            # Draw background offset rectangle
            backRectPoints = [
                QPointF(centerX - 3.0 * scaleFactor, centerY - 3.0 * scaleFactor),
                QPointF(centerX - 3.0 * scaleFactor, centerY - 5.5 * scaleFactor),
                QPointF(centerX + 4.5 * scaleFactor, centerY - 5.5 * scaleFactor),
                QPointF(centerX + 4.5 * scaleFactor, centerY + 2.0 * scaleFactor),
                QPointF(centerX + 2.5 * scaleFactor, centerY + 2.0 * scaleFactor),
            ]
            painter.drawPolyline(backRectPoints)
            # Draw foreground rectangle
            frontRect = QRectF(
                centerX - 5.5 * scaleFactor,
                centerY - 3.0 * scaleFactor,
                8.0 * scaleFactor,
                8.0 * scaleFactor,
            )
            painter.drawRect(frontRect)
        else:
            # Draw single maximize square
            squareRect = QRectF(
                centerX - 4.5 * scaleFactor,
                centerY - 4.5 * scaleFactor,
                9.0 * scaleFactor,
                9.0 * scaleFactor,
            )
            painter.drawRect(squareRect)

        painter.end()

isMaximizedState()

Return whether the button displays the restored or maximized glyph.

Returns:

Type Description
bool

True if currently displaying restored glyph for a maximized window.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def isMaximizedState(self) -> bool:
    """Return whether the button displays the restored or maximized glyph.

    Returns
    -------
    bool
        True if currently displaying restored glyph for a maximized window.
    """
    return self._isMaximized

paintEvent(event)

Paint vector rectangle or overlapping restore rectangles.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def paintEvent(self, event: QPaintEvent) -> None:
    """Paint vector rectangle or overlapping restore rectangles.

    Parameters
    ----------
    event : QPaintEvent
        The paint event.
    """
    super().paintEvent(event)
    painter = QPainter(self)
    painter.setRenderHint(QPainter.RenderHint.Antialiasing)

    isHovered = self.isHovered()

    scaleFactor = self.getGlyphScaleFactor()
    strokeColor = self._hoverGlyphColor if isHovered else self._glyphColor
    pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
    painter.setPen(pen)
    painter.setBrush(Qt.BrushStyle.NoBrush)

    centerX = self.width() / 2.0
    centerY = self.height() / 2.0

    if self._isMaximized:
        # Draw background offset rectangle
        backRectPoints = [
            QPointF(centerX - 3.0 * scaleFactor, centerY - 3.0 * scaleFactor),
            QPointF(centerX - 3.0 * scaleFactor, centerY - 5.5 * scaleFactor),
            QPointF(centerX + 4.5 * scaleFactor, centerY - 5.5 * scaleFactor),
            QPointF(centerX + 4.5 * scaleFactor, centerY + 2.0 * scaleFactor),
            QPointF(centerX + 2.5 * scaleFactor, centerY + 2.0 * scaleFactor),
        ]
        painter.drawPolyline(backRectPoints)
        # Draw foreground rectangle
        frontRect = QRectF(
            centerX - 5.5 * scaleFactor,
            centerY - 3.0 * scaleFactor,
            8.0 * scaleFactor,
            8.0 * scaleFactor,
        )
        painter.drawRect(frontRect)
    else:
        # Draw single maximize square
        squareRect = QRectF(
            centerX - 4.5 * scaleFactor,
            centerY - 4.5 * scaleFactor,
            9.0 * scaleFactor,
            9.0 * scaleFactor,
        )
        painter.drawRect(squareRect)

    painter.end()

setMaximizedState(isMaximized)

Update button glyph state to reflect window maximize status.

Parameters:

Name Type Description Default
isMaximized bool

True if the parent window is maximized.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def setMaximizedState(self, isMaximized: bool) -> None:
    """Update button glyph state to reflect window maximize status.

    Parameters
    ----------
    isMaximized : bool
        True if the parent window is maximized.
    """
    if self._isMaximized != isMaximized:
        self._isMaximized = isMaximized
        self.update()

MenuStyler

Styler utility providing Windows 11 Fluent QSS themes for menu bars and popup menus.

Source code in src/qtframelesskit/windows/title_bar/menu_styler.py
class MenuStyler:
    """Styler utility providing Windows 11 Fluent QSS themes for menu bars and popup menus."""

    @staticmethod
    def applyFluentMenuStyle(menuBar: QMenuBar, isDark: bool = False, dpi: int = 96) -> None:
        """Apply Fluent design transparent styles and popup menu styling to a menu bar.

        Parameters
        ----------
        menuBar : QMenuBar
            Target menu bar instance to style.
        isDark : bool, optional
            True for dark theme palette, False for light theme. Defaults to False.
        dpi : int, optional
            Screen dots-per-inch used to scale layout padding. Defaults to 96.
        """
        if dpi <= 0:
            dpi = 96
        scaleFactor = dpi / 96.0
        scaledPaddingLeft = max(4, round(8 * scaleFactor))

        menuBarRule = (
            f"QMenuBar {{\n"
            f"    background: transparent;\n"
            f"    border: none;\n"
            f"    padding: 0px 0px 0px {scaledPaddingLeft}px;\n"
            f"    margin: 0px;\n"
            f"    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;\n"
            f"    font-size: 13px;\n"
            f"}}\n"
        )

        if isDark:
            styleSheet = (
                menuBarRule
                + """QMenuBar::item {
    background: transparent;
    color: #ffffff;
    padding: 5px 10px;
    border-radius: 4px;
}
QMenuBar::item:selected {
    background-color: rgba(255, 255, 255, 0.1);
}
QMenuBar::item:pressed {
    background-color: rgba(255, 255, 255, 0.15);
}
QMenu {
    background-color: #2c2c2c;
    color: #ffffff;
    border: 1px solid rgba(255, 255, 255, 0.15);
    border-radius: 8px;
    padding: 6px;
    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
    font-size: 13px;
}
QMenu::item {
    background: transparent;
    color: #ffffff;
    padding: 6px 28px 6px 14px;
    border-radius: 4px;
}
QMenu::item:selected {
    background-color: #0078d4;
    color: #ffffff;
}
QMenu::item:disabled {
    color: rgba(255, 255, 255, 0.4);
}
QMenu::separator {
    height: 1px;
    background: rgba(255, 255, 255, 0.12);
    margin: 4px 8px;
}
"""
            )
        else:
            styleSheet = (
                menuBarRule
                + """QMenuBar::item {
    background: transparent;
    color: #000000;
    padding: 5px 10px;
    border-radius: 4px;
}
QMenuBar::item:selected {
    background-color: rgba(0, 0, 0, 0.08);
}
QMenuBar::item:pressed {
    background-color: rgba(0, 0, 0, 0.12);
}
QMenu {
    background-color: #f9f9f9;
    color: #000000;
    border: 1px solid rgba(0, 0, 0, 0.12);
    border-radius: 8px;
    padding: 6px;
    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
    font-size: 13px;
}
QMenu::item {
    background: transparent;
    color: #000000;
    padding: 6px 28px 6px 14px;
    border-radius: 4px;
}
QMenu::item:selected {
    background-color: rgba(0, 0, 0, 0.08);
    color: #000000;
}
QMenu::item:disabled {
    color: rgba(0, 0, 0, 0.35);
}
QMenu::separator {
    height: 1px;
    background: rgba(0, 0, 0, 0.1);
    margin: 4px 8px;
}
"""
            )
        menuBar.setStyleSheet(styleSheet)

applyFluentMenuStyle(menuBar, isDark=False, dpi=96) staticmethod

Apply Fluent design transparent styles and popup menu styling to a menu bar.

Parameters:

Name Type Description Default
menuBar QMenuBar

Target menu bar instance to style.

required
isDark bool

True for dark theme palette, False for light theme. Defaults to False.

False
dpi int

Screen dots-per-inch used to scale layout padding. Defaults to 96.

96
Source code in src/qtframelesskit/windows/title_bar/menu_styler.py
    @staticmethod
    def applyFluentMenuStyle(menuBar: QMenuBar, isDark: bool = False, dpi: int = 96) -> None:
        """Apply Fluent design transparent styles and popup menu styling to a menu bar.

        Parameters
        ----------
        menuBar : QMenuBar
            Target menu bar instance to style.
        isDark : bool, optional
            True for dark theme palette, False for light theme. Defaults to False.
        dpi : int, optional
            Screen dots-per-inch used to scale layout padding. Defaults to 96.
        """
        if dpi <= 0:
            dpi = 96
        scaleFactor = dpi / 96.0
        scaledPaddingLeft = max(4, round(8 * scaleFactor))

        menuBarRule = (
            f"QMenuBar {{\n"
            f"    background: transparent;\n"
            f"    border: none;\n"
            f"    padding: 0px 0px 0px {scaledPaddingLeft}px;\n"
            f"    margin: 0px;\n"
            f"    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;\n"
            f"    font-size: 13px;\n"
            f"}}\n"
        )

        if isDark:
            styleSheet = (
                menuBarRule
                + """QMenuBar::item {
    background: transparent;
    color: #ffffff;
    padding: 5px 10px;
    border-radius: 4px;
}
QMenuBar::item:selected {
    background-color: rgba(255, 255, 255, 0.1);
}
QMenuBar::item:pressed {
    background-color: rgba(255, 255, 255, 0.15);
}
QMenu {
    background-color: #2c2c2c;
    color: #ffffff;
    border: 1px solid rgba(255, 255, 255, 0.15);
    border-radius: 8px;
    padding: 6px;
    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
    font-size: 13px;
}
QMenu::item {
    background: transparent;
    color: #ffffff;
    padding: 6px 28px 6px 14px;
    border-radius: 4px;
}
QMenu::item:selected {
    background-color: #0078d4;
    color: #ffffff;
}
QMenu::item:disabled {
    color: rgba(255, 255, 255, 0.4);
}
QMenu::separator {
    height: 1px;
    background: rgba(255, 255, 255, 0.12);
    margin: 4px 8px;
}
"""
            )
        else:
            styleSheet = (
                menuBarRule
                + """QMenuBar::item {
    background: transparent;
    color: #000000;
    padding: 5px 10px;
    border-radius: 4px;
}
QMenuBar::item:selected {
    background-color: rgba(0, 0, 0, 0.08);
}
QMenuBar::item:pressed {
    background-color: rgba(0, 0, 0, 0.12);
}
QMenu {
    background-color: #f9f9f9;
    color: #000000;
    border: 1px solid rgba(0, 0, 0, 0.12);
    border-radius: 8px;
    padding: 6px;
    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
    font-size: 13px;
}
QMenu::item {
    background: transparent;
    color: #000000;
    padding: 6px 28px 6px 14px;
    border-radius: 4px;
}
QMenu::item:selected {
    background-color: rgba(0, 0, 0, 0.08);
    color: #000000;
}
QMenu::item:disabled {
    color: rgba(0, 0, 0, 0.35);
}
QMenu::separator {
    height: 1px;
    background: rgba(0, 0, 0, 0.1);
    margin: 4px 8px;
}
"""
            )
        menuBar.setStyleSheet(styleSheet)

MinimizeButton

Bases: VectorButton

Window minimize button rendering a vector horizontal line glyph.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
class MinimizeButton(VectorButton):
    """Window minimize button rendering a vector horizontal line glyph."""

    def paintEvent(self, event: QPaintEvent) -> None:
        """Paint vector minimize horizontal line.

        Parameters
        ----------
        event : QPaintEvent
            The paint event.
        """
        super().paintEvent(event)
        painter = QPainter(self)
        painter.setRenderHint(QPainter.RenderHint.Antialiasing)

        scaleFactor = self.getGlyphScaleFactor()
        strokeColor = self._hoverGlyphColor if self.isHovered() else self._glyphColor
        pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
        painter.setPen(pen)

        centerX = self.width() / 2.0
        centerY = self.height() / 2.0
        halfWidth = 5.0 * scaleFactor
        painter.drawLine(
            QPointF(centerX - halfWidth, centerY),
            QPointF(centerX + halfWidth, centerY),
        )
        painter.end()

paintEvent(event)

Paint vector minimize horizontal line.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def paintEvent(self, event: QPaintEvent) -> None:
    """Paint vector minimize horizontal line.

    Parameters
    ----------
    event : QPaintEvent
        The paint event.
    """
    super().paintEvent(event)
    painter = QPainter(self)
    painter.setRenderHint(QPainter.RenderHint.Antialiasing)

    scaleFactor = self.getGlyphScaleFactor()
    strokeColor = self._hoverGlyphColor if self.isHovered() else self._glyphColor
    pen = QPen(strokeColor, max(1.0, round(1.2 * scaleFactor, 1)))
    painter.setPen(pen)

    centerX = self.width() / 2.0
    centerY = self.height() / 2.0
    halfWidth = 5.0 * scaleFactor
    painter.drawLine(
        QPointF(centerX - halfWidth, centerY),
        QPointF(centerX + halfWidth, centerY),
    )
    painter.end()

TitleBar

Bases: QWidget

Custom title bar widget with vector control buttons and event filtering.

Parameters:

Name Type Description Default
parentWidget QWidget

Parent window owning this title bar.

None
hint list of str

Button hints controlling which control buttons to display.

None
base_widget QWidget

Legacy alias for parentWidget.

None
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
 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
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
class TitleBar(QWidget):
    """Custom title bar widget with vector control buttons and event filtering.

    Parameters
    ----------
    parentWidget : QWidget, optional
        Parent window owning this title bar.
    hint : list of str, optional
        Button hints controlling which control buttons to display.
    base_widget : QWidget, optional
        Legacy alias for parentWidget.
    """

    def __init__(
        self,
        parentWidget: QWidget | None = None,
        hint: list[str] | None = None,
        base_widget: QWidget | None = None,
    ) -> None:
        resolvedParent = parentWidget if parentWidget is not None else base_widget
        super().__init__(resolvedParent)
        self._isDarkTheme = False
        self._pressToMove = True
        self._baseWindowResizable = True
        self._currentDpi = 96
        self._baseIconWidth = 18
        self._baseIconHeight = 18
        self._baseButtonHeight = 30
        self._backgroundColor: QColor | None = None
        self._menuBar: QMenuBar | None = None
        self._titleAlignment: Qt.AlignmentFlag = Qt.AlignmentFlag.AlignLeft
        self._autoStyleMenuBar: bool = True
        self._dragHandler = TitleBarDragHandler(self)

        self._iconLabel = QLabel()
        self._titleLabel = QLabel()
        self._baseFont = QFont(self._titleLabel.font())
        self._centerContainer = QWidget(self)
        centerLayout = QHBoxLayout()
        centerLayout.setContentsMargins(0, 0, 0, 0)
        centerLayout.setSpacing(0)
        self._centerContainer.setLayout(centerLayout)
        self._centerContainer.setSizePolicy(
            QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred
        )
        self._centerWidget: QWidget | None = None
        self._cornerWidget = QWidget(self)
        self._cornerWidget.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, True)

        self._fullScreenButton = FullScreenButton(self)
        self._minimizeButton = MinimizeButton(self)
        self._maximizeButton = MaximizeButton(self)
        self._closeButton = CloseButton(self)

        self._fullScreenButton.setCheckable(True)
        self._buttonDict = {
            "full_screen": self._fullScreenButton,
            "min": self._minimizeButton,
            "max": self._maximizeButton,
            "close": self._closeButton,
        }

        self._connectButtonSignals()
        self._initUi(hint)

        targetWindow = self.window()
        if targetWindow and targetWindow is not self:
            targetWindow.installEventFilter(self)

        for candidate in (resolvedParent, targetWindow):
            if candidate is not None and candidate is not self:
                try:
                    themeSignal = getattr(candidate, "darkThemeChanged", None)
                    if themeSignal is not None and hasattr(themeSignal, "connect"):
                        themeSignal.connect(self._handleThemeChanged)
                        if hasattr(candidate, "isDarkTheme") and callable(candidate.isDarkTheme):
                            if candidate.isDarkTheme():
                                self.setDarkTheme(True)
                        break
                except Exception:
                    pass

    def _connectButtonSignals(self) -> None:
        """Connect button click signals to parent window action slots."""
        self._fullScreenButton.clicked.connect(self._handleFullScreenClicked)
        self._minimizeButton.clicked.connect(self._handleMinimizeClicked)
        self._maximizeButton.clicked.connect(self._handleMaximizeClicked)
        self._closeButton.clicked.connect(self._handleCloseClicked)

    def _initUi(self, hint: list[str] | None) -> None:
        """Build title bar layout, setting icon, title, and button controls."""
        mainLayout = QHBoxLayout()
        mainLayout.setContentsMargins(8, 0, 0, 0)
        mainLayout.setSpacing(0)
        mainLayout.setAlignment(Qt.AlignmentFlag.AlignRight)

        self._iconLabel.setContentsMargins(4, 4, 4, 4)
        self._titleLabel.setContentsMargins(4, 4, 4, 4)
        textColor = "#ffffff" if self._isDarkTheme else "#000000"
        titlePalette = self._titleLabel.palette()
        titlePalette.setColor(QPalette.ColorRole.WindowText, QColor(textColor))
        self._titleLabel.setPalette(titlePalette)

        mainLayout.addWidget(self._iconLabel)
        mainLayout.addWidget(self._titleLabel)
        mainLayout.addWidget(self._centerContainer)

        cornerLayout = QHBoxLayout()
        cornerLayout.setContentsMargins(0, 0, 0, 0)
        cornerLayout.setSpacing(0)
        cornerLayout.setAlignment(Qt.AlignmentFlag.AlignTop)
        for button in self._buttonDict.values():
            cornerLayout.addWidget(button)
        self._cornerWidget.setLayout(cornerLayout)

        self.setTitleBarHint(hint)
        mainLayout.addWidget(self._cornerWidget)
        self.setLayout(mainLayout)
        self._updateTitleAlignment()

    def _handleMinimizeClicked(self) -> None:
        """Minimize the top-level parent window."""
        targetWindow = self.window()
        if targetWindow:
            targetWindow.showMinimized()

    def _handleMaximizeClicked(self) -> None:
        """Toggle normal and maximized state of the parent window."""
        targetWindow = self.window()
        if not targetWindow:
            return
        if targetWindow.isMaximized():
            targetWindow.showNormal()
        else:
            targetWindow.showMaximized()

    def _handleFullScreenClicked(self) -> None:
        """Toggle fullscreen state of the parent window."""
        targetWindow = self.window()
        if not targetWindow:
            return
        if targetWindow.isFullScreen():
            targetWindow.showNormal()
        else:
            targetWindow.showFullScreen()

    def _handleCloseClicked(self) -> None:
        """Close the parent window."""
        targetWindow = self.window()
        if targetWindow:
            targetWindow.close()

    def _handleThemeChanged(self, isDark: bool) -> None:
        """Update label text colors and vector button themes for dark mode.

        Parameters
        ----------
        isDark : bool
            True if dark mode is active, False for light mode.
        """
        self._isDarkTheme = isDark
        textColor = "#ffffff" if isDark else "#000000"
        titlePalette = self._titleLabel.palette()
        titlePalette.setColor(QPalette.ColorRole.WindowText, QColor(textColor))
        self._titleLabel.setPalette(titlePalette)

        for button in self._buttonDict.values():
            if isinstance(button, VectorButton):
                button.setDarkTheme(isDark)

        self._updateMenuBarStyle()

    def setDarkTheme(self, isDark: bool) -> None:
        """Configure dark or light theme styling on labels and vector buttons.

        Parameters
        ----------
        isDark : bool
            True to apply dark theme styles, False for light theme.
        """
        self._handleThemeChanged(isDark)

    def isDarkTheme(self) -> bool:
        """Return whether the title bar is currently configured with dark theme.

        Returns
        -------
        bool
            True if dark theme is active, False otherwise.
        """
        return self._isDarkTheme

    def mouseDoubleClickEvent(self, event: QMouseEvent) -> None:
        """Toggle maximize state upon double-clicking the title bar.

        Parameters
        ----------
        event : QMouseEvent
            Mouse double-click event.
        """
        if self._dragHandler.handleMouseDoubleClick(event):
            return
        super().mouseDoubleClickEvent(event)

    def mousePressEvent(self, event: QMouseEvent) -> None:
        """Start native system window drag when left clicking the title bar.

        Parameters
        ----------
        event : QMouseEvent
            Mouse press event.
        """
        if self._dragHandler.handleMousePress(event):
            return
        super().mousePressEvent(event)

    def eventFilter(self, watchedObject: object, event: QEvent) -> bool:
        """Filter parent window state change and layout request events.

        Parameters
        ----------
        watchedObject : object
            The watched Qt object.
        event : QEvent
            The incoming Qt event.

        Returns
        -------
        bool
            True if event was handled, False to pass along.
        """
        if watchedObject is self.window():
            eventType = event.type()
            if eventType == QEvent.Type.WindowStateChange:
                targetWindow = self.window()
                isFullScreen = targetWindow.isFullScreen()
                isMaximized = targetWindow.isMaximized()

                self._fullScreenButton.setChecked(isFullScreen)
                self._maximizeButton.setChecked(isMaximized)
                self._maximizeButton.setMaximizedState(isMaximized)

                if isFullScreen:
                    self.hide()
                else:
                    self.show()
            elif eventType == QEvent.Type.LayoutRequest:
                self.setMaximumHeight(self.sizeHint().height())

        return super().eventFilter(watchedObject, event)

    def setIcon(self, icon: QIcon) -> None:
        """Set the window icon on the title bar with default 18x18 size.

        Parameters
        ----------
        icon : QIcon
            Icon to display.
        """
        self._windowIcon = icon
        self.setIconSize(18, 18)

    def setIconSize(self, width: int, height: int) -> None:
        """Set the icon pixel dimensions and adjust button heights.

        Parameters
        ----------
        width : int
            Target icon width in pixels.
        height : int
            Target icon height in pixels.
        """
        self._baseIconWidth = width
        self._baseIconHeight = height
        self._baseButtonHeight = height * 2
        scaledWidth = round(width * getattr(self, "_currentDpi", 96) / 96)
        scaledHeight = round(height * getattr(self, "_currentDpi", 96) / 96)
        if hasattr(self, "_windowIcon") and not self._windowIcon.isNull():
            self._iconLabel.setPixmap(self._windowIcon.pixmap(scaledWidth, scaledHeight))
        scaledButtonHeight = round(self._baseButtonHeight * getattr(self, "_currentDpi", 96) / 96)
        for button in self._buttonDict.values():
            if isinstance(button, VectorButton):
                button.updateButtonHeight(scaledButtonHeight)

    def setTitle(self, title: str) -> None:
        """Set the window title text.

        Parameters
        ----------
        title : str
            Title string to display.
        """
        self._titleLabel.setText(title)

    def setTitleBarFont(self, font: QFont) -> None:
        """Set the title label font and scale button heights proportionally.

        Parameters
        ----------
        font : QFont
            Font to apply to the title text.
        """
        self._baseFont = QFont(font)
        currentDpi = getattr(self, "_currentDpi", 96)
        scaleFactor = currentDpi / 96.0

        scaledFont = QFont(self._baseFont)
        basePoints = self._baseFont.pointSizeF()
        if basePoints > 0:
            scaledFont.setPointSizeF(basePoints * scaleFactor)
        else:
            basePixels = self._baseFont.pixelSize()
            if basePixels > 0:
                scaledFont.setPixelSize(round(basePixels * scaleFactor))
        self._titleLabel.setFont(scaledFont)

        self._baseButtonHeight = font.pointSize() * 2
        newButtonHeight = round(self._baseButtonHeight * scaleFactor)
        for button in self._buttonDict.values():
            if isinstance(button, VectorButton):
                button.updateButtonHeight(newButtonHeight)

    def updateDpiScaling(self, dpi: int) -> None:
        """Recalculate layout margins, button bounds, icon, and title font for new DPI.

        Parameters
        ----------
        dpi : int
            Active dots-per-inch scaling factor (e.g. 96 for 100%, 144 for 150%).
        """
        if dpi <= 0:
            dpi = 96
        self._currentDpi = dpi
        scaleFactor = dpi / 96.0

        if hasattr(self, "_baseFont"):
            scaledFont = QFont(self._baseFont)
            basePoints = self._baseFont.pointSizeF()
            if basePoints > 0:
                scaledFont.setPointSizeF(basePoints * scaleFactor)
            else:
                basePixels = self._baseFont.pixelSize()
                if basePixels > 0:
                    scaledFont.setPixelSize(round(basePixels * scaleFactor))
            self._titleLabel.setFont(scaledFont)

        scaledButtonHeight = max(24, round(self._baseButtonHeight * scaleFactor))
        for button in self._buttonDict.values():
            if isinstance(button, VectorButton):
                button.updateButtonHeight(scaledButtonHeight)

        if hasattr(self, "_windowIcon") and not self._windowIcon.isNull():
            scaledWidth = round(self._baseIconWidth * scaleFactor)
            scaledHeight = round(self._baseIconHeight * scaleFactor)
            self._iconLabel.setPixmap(self._windowIcon.pixmap(scaledWidth, scaledHeight))

        scaledMargin = max(2, round(4 * scaleFactor))
        self._iconLabel.setContentsMargins(scaledMargin, scaledMargin, scaledMargin, scaledMargin)
        self._titleLabel.setContentsMargins(scaledMargin, scaledMargin, scaledMargin, scaledMargin)

        scaledLayoutLeft = max(4, round(8 * scaleFactor))
        if self.layout() is not None:
            self.layout().setContentsMargins(scaledLayoutLeft, 0, 0, 0)

        self.updateGeometry()
        self.setMaximumHeight(self.sizeHint().height())

    def getCurrentDpi(self) -> int:
        """Return the active DPI scaling factor configured for the title bar.

        Returns
        -------
        int
            Active DPI value (e.g. 96 for 100%, 144 for 150%).
        """
        return getattr(self, "_currentDpi", 96)

    def setTitleBarHint(self, hint: list[str] | None) -> None:
        """Show only the control buttons specified in hint list.

        Parameters
        ----------
        hint : list of str or None
            Button keys to display ('min', 'max', 'close', 'full_screen').
            Defaults to standard set ('min', 'max', 'close') when None.
        """
        if hint is None:
            hint = ["min", "max", "close"]

        visibleSet = set(hint)
        for key, button in self._buttonDict.items():
            button.setVisible(key in visibleSet)

    def setPressToMove(self, enabled: bool) -> None:
        """Enable or disable dragging window from title bar.

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

    def isPressToMove(self) -> bool:
        """Return whether pressing title bar initiates window movement.

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

    def setBaseWindowResizable(self, resizable: bool) -> None:
        """Configure whether maximize button is enabled based on resizability.

        Parameters
        ----------
        resizable : bool
            True if the base window can be resized/maximized.
        """
        self._baseWindowResizable = resizable
        self._maximizeButton.setVisible(resizable)

    def getTitle(self) -> QLabel:
        """Return the QLabel widget displaying window title.

        Returns
        -------
        QLabel
            The title label widget.
        """
        return self._titleLabel

    def getIcon(self) -> QLabel:
        """Return the QLabel widget displaying window icon.

        Returns
        -------
        QLabel
            The icon label widget.
        """
        return self._iconLabel

    def getButtons(self) -> dict[str, QPushButton]:
        """Return mapping of button keys to QPushButton instances.

        Returns
        -------
        dict of str to QPushButton
            Dictionary of control buttons.
        """
        return self._buttonDict

    def getMaximizeButton(self) -> MaximizeButton | None:
        """Return the maximize button instance if present and not hidden.

        Returns
        -------
        MaximizeButton or None
            The maximize button instance, or None if omitted or hidden.
        """
        button = getattr(self, "_maximizeButton", None)
        if button is not None and not button.isHidden():
            return button
        return None

    def setCenterWidget(self, widget: QWidget | None) -> None:
        """Install or replace the custom widget hosted in the center area.

        Parameters
        ----------
        widget : QWidget or None
            Custom widget to place inside the center area, or None to clear.
        """
        if self._centerWidget is not None:
            self.removeCenterWidget()

        if widget is not None:
            self._centerContainer.setSizePolicy(
                QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred
            )
            widget.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
            containerLayout = self._centerContainer.layout()
            if containerLayout is not None:
                containerLayout.addWidget(widget)
            self._centerWidget = widget

    def getCenterWidget(self) -> QWidget | None:
        """Return the custom widget currently hosted in the center area.

        Returns
        -------
        QWidget or None
            The installed center widget, or None if no widget is installed.
        """
        return self._centerWidget

    def removeCenterWidget(self) -> QWidget | None:
        """Remove and return the hosted center widget without destroying it.

        Returns
        -------
        QWidget or None
            The removed widget, or None if no center widget was installed.
        """
        if self._centerWidget is not None:
            detachedWidget = self._centerWidget
            containerLayout = self._centerContainer.layout()
            if containerLayout is not None:
                containerLayout.removeWidget(detachedWidget)
            detachedWidget.setParent(None)
            self._centerWidget = None
            self._updateTitleAlignment()
            return detachedWidget
        return None

    def setMenuBar(self, menuBar: QMenuBar | None) -> None:
        """Install or replace the QMenuBar inside the title bar right after the icon.

        Parameters
        ----------
        menuBar : QMenuBar or None
            Menu bar instance to install, or None to remove the existing one.
        """
        if self._menuBar is not None:
            self.removeMenuBar()

        if menuBar is None:
            return

        self._menuBar = menuBar
        menuBar.setSizePolicy(QSizePolicy.Policy.Maximum, QSizePolicy.Policy.Preferred)
        menuBar.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, True)
        menuBar.setAutoFillBackground(False)
        if bool(menuBar.styleSheet().strip()):
            self._autoStyleMenuBar = False

        layout = self.layout()
        if layout is not None:
            iconIndex = layout.indexOf(self._iconLabel)
            insertIndex = iconIndex + 1 if iconIndex >= 0 else 0
            layout.insertWidget(
                insertIndex,
                menuBar,
                0,
                Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter,
            )

        self._updateMenuBarStyle()

    def getMenuBar(self) -> QMenuBar | None:
        """Return the installed QMenuBar widget.

        Returns
        -------
        QMenuBar or None
            The installed menu bar widget, or None if omitted.
        """
        return self._menuBar

    def removeMenuBar(self) -> QMenuBar | None:
        """Detach from layout, reparent to None, and return the menu bar.

        Returns
        -------
        QMenuBar or None
            The detached menu bar widget, or None if no menu bar was installed.
        """
        if self._menuBar is not None:
            detachedMenuBar = self._menuBar
            layout = self.layout()
            if layout is not None:
                layout.removeWidget(detachedMenuBar)
            detachedMenuBar.setParent(None)
            self._menuBar = None
            return detachedMenuBar
        return None

    def setTitleAlignment(self, alignment: Qt.AlignmentFlag) -> None:
        """Set the horizontal alignment of the window title.

        Parameters
        ----------
        alignment : Qt.AlignmentFlag
            Target alignment flag (e.g. Qt.AlignmentFlag.AlignCenter or Qt.AlignmentFlag.AlignLeft).
        """
        self._titleAlignment = alignment
        self._updateTitleAlignment()

    def getTitleAlignment(self) -> Qt.AlignmentFlag:
        """Return the current horizontal alignment flag of the window title.

        Returns
        -------
        Qt.AlignmentFlag
            Active title alignment flag.
        """
        return self._titleAlignment

    def _updateTitleAlignment(self) -> None:
        """Update title label alignment and layout size policies matching configured alignment."""
        if self._titleAlignment in (Qt.AlignmentFlag.AlignCenter, Qt.AlignmentFlag.AlignHCenter):
            self._titleLabel.setAlignment(
                Qt.AlignmentFlag.AlignCenter | Qt.AlignmentFlag.AlignVCenter
            )
            self._titleLabel.setSizePolicy(
                QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred
            )
            if self._centerWidget is None:
                self._centerContainer.setSizePolicy(
                    QSizePolicy.Policy.Minimum, QSizePolicy.Policy.Preferred
                )
        else:
            self._titleLabel.setAlignment(
                Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter
            )
            self._titleLabel.setSizePolicy(
                QSizePolicy.Policy.Preferred, QSizePolicy.Policy.Preferred
            )
            if self._centerWidget is None:
                self._centerContainer.setSizePolicy(
                    QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred
                )

    def isAutoStyleMenuBar(self) -> bool:
        """Return whether automatic theme styling is applied to the menu bar.

        Returns
        -------
        bool
            True if auto-styling is enabled, False otherwise.
        """
        return self._autoStyleMenuBar

    def setAutoStyleMenuBar(self, autoStyle: bool) -> None:
        """Configure whether automatic theme styling is applied to the menu bar.

        Parameters
        ----------
        autoStyle : bool
            True to automatically update menu bar styling on theme changes.
        """
        self._autoStyleMenuBar = autoStyle
        if autoStyle and self._menuBar is not None:
            self._updateMenuBarStyle()

    @staticmethod
    def applyFluentMenuStyle(menuBar: QMenuBar, isDark: bool = False, dpi: int = 96) -> None:
        """Apply Fluent design transparent styles and popup menu styling to a menu bar.

        Parameters
        ----------
        menuBar : QMenuBar
            Target menu bar instance to style.
        isDark : bool, optional
            True for dark theme palette, False for light theme. Defaults to False.
        dpi : int, optional
            Screen dots-per-inch used to scale layout padding. Defaults to 96.
        """
        MenuStyler.applyFluentMenuStyle(menuBar, isDark=isDark, dpi=dpi)

    def _updateMenuBarStyle(self) -> None:
        """Apply Fluent transparent QMenuBar and QMenu popup styles matching theme."""
        if self._autoStyleMenuBar and self._menuBar is not None:
            MenuStyler.applyFluentMenuStyle(self._menuBar, self._isDarkTheme, self.getCurrentDpi())

    def getBackgroundColor(self) -> QColor | None:
        """Return the current background color of the title bar.

        Returns
        -------
        QColor or None
            Current background color, or None if using default window background.
        """
        return self._backgroundColor

    def setBackgroundColor(self, color: QColor | str | None) -> None:
        """Set the background color of the title bar and request a repaint.

        Parameters
        ----------
        color : QColor, str, or None
            New background color representation, or None to use default window background.
        """
        if color is None:
            self._backgroundColor = None
        elif isinstance(color, QColor):
            self._backgroundColor = QColor(color)
        else:
            self._backgroundColor = QColor(color)
        self.update()

    def paintEvent(self, event: QPaintEvent) -> None:
        """Paint title bar background directly using QPainter without stylesheets.

        Uses CompositionMode_Source so transparent or custom background
        colors overwrite the backing store buffer cleanly without alpha-blending
        over previous frames.

        Parameters
        ----------
        event : QPaintEvent
            The paint event.
        """
        super().paintEvent(event)
        if self._backgroundColor is not None:
            painter = QPainter(self)
            painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_Source)
            painter.fillRect(self.rect(), self._backgroundColor)
            painter.end()

applyFluentMenuStyle(menuBar, isDark=False, dpi=96) staticmethod

Apply Fluent design transparent styles and popup menu styling to a menu bar.

Parameters:

Name Type Description Default
menuBar QMenuBar

Target menu bar instance to style.

required
isDark bool

True for dark theme palette, False for light theme. Defaults to False.

False
dpi int

Screen dots-per-inch used to scale layout padding. Defaults to 96.

96
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
@staticmethod
def applyFluentMenuStyle(menuBar: QMenuBar, isDark: bool = False, dpi: int = 96) -> None:
    """Apply Fluent design transparent styles and popup menu styling to a menu bar.

    Parameters
    ----------
    menuBar : QMenuBar
        Target menu bar instance to style.
    isDark : bool, optional
        True for dark theme palette, False for light theme. Defaults to False.
    dpi : int, optional
        Screen dots-per-inch used to scale layout padding. Defaults to 96.
    """
    MenuStyler.applyFluentMenuStyle(menuBar, isDark=isDark, dpi=dpi)

eventFilter(watchedObject, event)

Filter parent window state change and layout request events.

Parameters:

Name Type Description Default
watchedObject object

The watched Qt object.

required
event QEvent

The incoming Qt event.

required

Returns:

Type Description
bool

True if event was handled, False to pass along.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def eventFilter(self, watchedObject: object, event: QEvent) -> bool:
    """Filter parent window state change and layout request events.

    Parameters
    ----------
    watchedObject : object
        The watched Qt object.
    event : QEvent
        The incoming Qt event.

    Returns
    -------
    bool
        True if event was handled, False to pass along.
    """
    if watchedObject is self.window():
        eventType = event.type()
        if eventType == QEvent.Type.WindowStateChange:
            targetWindow = self.window()
            isFullScreen = targetWindow.isFullScreen()
            isMaximized = targetWindow.isMaximized()

            self._fullScreenButton.setChecked(isFullScreen)
            self._maximizeButton.setChecked(isMaximized)
            self._maximizeButton.setMaximizedState(isMaximized)

            if isFullScreen:
                self.hide()
            else:
                self.show()
        elif eventType == QEvent.Type.LayoutRequest:
            self.setMaximumHeight(self.sizeHint().height())

    return super().eventFilter(watchedObject, event)

getBackgroundColor()

Return the current background color of the title bar.

Returns:

Type Description
QColor or None

Current background color, or None if using default window background.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getBackgroundColor(self) -> QColor | None:
    """Return the current background color of the title bar.

    Returns
    -------
    QColor or None
        Current background color, or None if using default window background.
    """
    return self._backgroundColor

getButtons()

Return mapping of button keys to QPushButton instances.

Returns:

Type Description
dict of str to QPushButton

Dictionary of control buttons.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getButtons(self) -> dict[str, QPushButton]:
    """Return mapping of button keys to QPushButton instances.

    Returns
    -------
    dict of str to QPushButton
        Dictionary of control buttons.
    """
    return self._buttonDict

getCenterWidget()

Return the custom widget currently hosted in the center area.

Returns:

Type Description
QWidget or None

The installed center widget, or None if no widget is installed.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getCenterWidget(self) -> QWidget | None:
    """Return the custom widget currently hosted in the center area.

    Returns
    -------
    QWidget or None
        The installed center widget, or None if no widget is installed.
    """
    return self._centerWidget

getCurrentDpi()

Return the active DPI scaling factor configured for the title bar.

Returns:

Type Description
int

Active DPI value (e.g. 96 for 100%, 144 for 150%).

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getCurrentDpi(self) -> int:
    """Return the active DPI scaling factor configured for the title bar.

    Returns
    -------
    int
        Active DPI value (e.g. 96 for 100%, 144 for 150%).
    """
    return getattr(self, "_currentDpi", 96)

getIcon()

Return the QLabel widget displaying window icon.

Returns:

Type Description
QLabel

The icon label widget.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getIcon(self) -> QLabel:
    """Return the QLabel widget displaying window icon.

    Returns
    -------
    QLabel
        The icon label widget.
    """
    return self._iconLabel

getMaximizeButton()

Return the maximize button instance if present and not hidden.

Returns:

Type Description
MaximizeButton or None

The maximize button instance, or None if omitted or hidden.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getMaximizeButton(self) -> MaximizeButton | None:
    """Return the maximize button instance if present and not hidden.

    Returns
    -------
    MaximizeButton or None
        The maximize button instance, or None if omitted or hidden.
    """
    button = getattr(self, "_maximizeButton", None)
    if button is not None and not button.isHidden():
        return button
    return None

getMenuBar()

Return the installed QMenuBar widget.

Returns:

Type Description
QMenuBar or None

The installed menu bar widget, or None if omitted.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getMenuBar(self) -> QMenuBar | None:
    """Return the installed QMenuBar widget.

    Returns
    -------
    QMenuBar or None
        The installed menu bar widget, or None if omitted.
    """
    return self._menuBar

getTitle()

Return the QLabel widget displaying window title.

Returns:

Type Description
QLabel

The title label widget.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getTitle(self) -> QLabel:
    """Return the QLabel widget displaying window title.

    Returns
    -------
    QLabel
        The title label widget.
    """
    return self._titleLabel

getTitleAlignment()

Return the current horizontal alignment flag of the window title.

Returns:

Type Description
AlignmentFlag

Active title alignment flag.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def getTitleAlignment(self) -> Qt.AlignmentFlag:
    """Return the current horizontal alignment flag of the window title.

    Returns
    -------
    Qt.AlignmentFlag
        Active title alignment flag.
    """
    return self._titleAlignment

isAutoStyleMenuBar()

Return whether automatic theme styling is applied to the menu bar.

Returns:

Type Description
bool

True if auto-styling is enabled, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def isAutoStyleMenuBar(self) -> bool:
    """Return whether automatic theme styling is applied to the menu bar.

    Returns
    -------
    bool
        True if auto-styling is enabled, False otherwise.
    """
    return self._autoStyleMenuBar

isDarkTheme()

Return whether the title bar is currently configured with dark theme.

Returns:

Type Description
bool

True if dark theme is active, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def isDarkTheme(self) -> bool:
    """Return whether the title bar is currently configured with dark theme.

    Returns
    -------
    bool
        True if dark theme is active, False otherwise.
    """
    return self._isDarkTheme

isPressToMove()

Return whether pressing title bar initiates window movement.

Returns:

Type Description
bool

True if press to move is enabled.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def isPressToMove(self) -> bool:
    """Return whether pressing title bar initiates window movement.

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

mouseDoubleClickEvent(event)

Toggle maximize state upon double-clicking the title bar.

Parameters:

Name Type Description Default
event QMouseEvent

Mouse double-click event.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def mouseDoubleClickEvent(self, event: QMouseEvent) -> None:
    """Toggle maximize state upon double-clicking the title bar.

    Parameters
    ----------
    event : QMouseEvent
        Mouse double-click event.
    """
    if self._dragHandler.handleMouseDoubleClick(event):
        return
    super().mouseDoubleClickEvent(event)

mousePressEvent(event)

Start native system window drag when left clicking the title bar.

Parameters:

Name Type Description Default
event QMouseEvent

Mouse press event.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def mousePressEvent(self, event: QMouseEvent) -> None:
    """Start native system window drag when left clicking the title bar.

    Parameters
    ----------
    event : QMouseEvent
        Mouse press event.
    """
    if self._dragHandler.handleMousePress(event):
        return
    super().mousePressEvent(event)

paintEvent(event)

Paint title bar background directly using QPainter without stylesheets.

Uses CompositionMode_Source so transparent or custom background colors overwrite the backing store buffer cleanly without alpha-blending over previous frames.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def paintEvent(self, event: QPaintEvent) -> None:
    """Paint title bar background directly using QPainter without stylesheets.

    Uses CompositionMode_Source so transparent or custom background
    colors overwrite the backing store buffer cleanly without alpha-blending
    over previous frames.

    Parameters
    ----------
    event : QPaintEvent
        The paint event.
    """
    super().paintEvent(event)
    if self._backgroundColor is not None:
        painter = QPainter(self)
        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_Source)
        painter.fillRect(self.rect(), self._backgroundColor)
        painter.end()

removeCenterWidget()

Remove and return the hosted center widget without destroying it.

Returns:

Type Description
QWidget or None

The removed widget, or None if no center widget was installed.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def removeCenterWidget(self) -> QWidget | None:
    """Remove and return the hosted center widget without destroying it.

    Returns
    -------
    QWidget or None
        The removed widget, or None if no center widget was installed.
    """
    if self._centerWidget is not None:
        detachedWidget = self._centerWidget
        containerLayout = self._centerContainer.layout()
        if containerLayout is not None:
            containerLayout.removeWidget(detachedWidget)
        detachedWidget.setParent(None)
        self._centerWidget = None
        self._updateTitleAlignment()
        return detachedWidget
    return None

removeMenuBar()

Detach from layout, reparent to None, and return the menu bar.

Returns:

Type Description
QMenuBar or None

The detached menu bar widget, or None if no menu bar was installed.

Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def removeMenuBar(self) -> QMenuBar | None:
    """Detach from layout, reparent to None, and return the menu bar.

    Returns
    -------
    QMenuBar or None
        The detached menu bar widget, or None if no menu bar was installed.
    """
    if self._menuBar is not None:
        detachedMenuBar = self._menuBar
        layout = self.layout()
        if layout is not None:
            layout.removeWidget(detachedMenuBar)
        detachedMenuBar.setParent(None)
        self._menuBar = None
        return detachedMenuBar
    return None

setAutoStyleMenuBar(autoStyle)

Configure whether automatic theme styling is applied to the menu bar.

Parameters:

Name Type Description Default
autoStyle bool

True to automatically update menu bar styling on theme changes.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setAutoStyleMenuBar(self, autoStyle: bool) -> None:
    """Configure whether automatic theme styling is applied to the menu bar.

    Parameters
    ----------
    autoStyle : bool
        True to automatically update menu bar styling on theme changes.
    """
    self._autoStyleMenuBar = autoStyle
    if autoStyle and self._menuBar is not None:
        self._updateMenuBarStyle()

setBackgroundColor(color)

Set the background color of the title bar and request a repaint.

Parameters:

Name Type Description Default
color QColor, str, or None

New background color representation, or None to use default window background.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setBackgroundColor(self, color: QColor | str | None) -> None:
    """Set the background color of the title bar and request a repaint.

    Parameters
    ----------
    color : QColor, str, or None
        New background color representation, or None to use default window background.
    """
    if color is None:
        self._backgroundColor = None
    elif isinstance(color, QColor):
        self._backgroundColor = QColor(color)
    else:
        self._backgroundColor = QColor(color)
    self.update()

setBaseWindowResizable(resizable)

Configure whether maximize button is enabled based on resizability.

Parameters:

Name Type Description Default
resizable bool

True if the base window can be resized/maximized.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setBaseWindowResizable(self, resizable: bool) -> None:
    """Configure whether maximize button is enabled based on resizability.

    Parameters
    ----------
    resizable : bool
        True if the base window can be resized/maximized.
    """
    self._baseWindowResizable = resizable
    self._maximizeButton.setVisible(resizable)

setCenterWidget(widget)

Install or replace the custom widget hosted in the center area.

Parameters:

Name Type Description Default
widget QWidget or None

Custom widget to place inside the center area, or None to clear.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setCenterWidget(self, widget: QWidget | None) -> None:
    """Install or replace the custom widget hosted in the center area.

    Parameters
    ----------
    widget : QWidget or None
        Custom widget to place inside the center area, or None to clear.
    """
    if self._centerWidget is not None:
        self.removeCenterWidget()

    if widget is not None:
        self._centerContainer.setSizePolicy(
            QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred
        )
        widget.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
        containerLayout = self._centerContainer.layout()
        if containerLayout is not None:
            containerLayout.addWidget(widget)
        self._centerWidget = widget

setDarkTheme(isDark)

Configure dark or light theme styling on labels and vector buttons.

Parameters:

Name Type Description Default
isDark bool

True to apply dark theme styles, False for light theme.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setDarkTheme(self, isDark: bool) -> None:
    """Configure dark or light theme styling on labels and vector buttons.

    Parameters
    ----------
    isDark : bool
        True to apply dark theme styles, False for light theme.
    """
    self._handleThemeChanged(isDark)

setIcon(icon)

Set the window icon on the title bar with default 18x18 size.

Parameters:

Name Type Description Default
icon QIcon

Icon to display.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setIcon(self, icon: QIcon) -> None:
    """Set the window icon on the title bar with default 18x18 size.

    Parameters
    ----------
    icon : QIcon
        Icon to display.
    """
    self._windowIcon = icon
    self.setIconSize(18, 18)

setIconSize(width, height)

Set the icon pixel dimensions and adjust button heights.

Parameters:

Name Type Description Default
width int

Target icon width in pixels.

required
height int

Target icon height in pixels.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setIconSize(self, width: int, height: int) -> None:
    """Set the icon pixel dimensions and adjust button heights.

    Parameters
    ----------
    width : int
        Target icon width in pixels.
    height : int
        Target icon height in pixels.
    """
    self._baseIconWidth = width
    self._baseIconHeight = height
    self._baseButtonHeight = height * 2
    scaledWidth = round(width * getattr(self, "_currentDpi", 96) / 96)
    scaledHeight = round(height * getattr(self, "_currentDpi", 96) / 96)
    if hasattr(self, "_windowIcon") and not self._windowIcon.isNull():
        self._iconLabel.setPixmap(self._windowIcon.pixmap(scaledWidth, scaledHeight))
    scaledButtonHeight = round(self._baseButtonHeight * getattr(self, "_currentDpi", 96) / 96)
    for button in self._buttonDict.values():
        if isinstance(button, VectorButton):
            button.updateButtonHeight(scaledButtonHeight)

setMenuBar(menuBar)

Install or replace the QMenuBar inside the title bar right after the icon.

Parameters:

Name Type Description Default
menuBar QMenuBar or None

Menu bar instance to install, or None to remove the existing one.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setMenuBar(self, menuBar: QMenuBar | None) -> None:
    """Install or replace the QMenuBar inside the title bar right after the icon.

    Parameters
    ----------
    menuBar : QMenuBar or None
        Menu bar instance to install, or None to remove the existing one.
    """
    if self._menuBar is not None:
        self.removeMenuBar()

    if menuBar is None:
        return

    self._menuBar = menuBar
    menuBar.setSizePolicy(QSizePolicy.Policy.Maximum, QSizePolicy.Policy.Preferred)
    menuBar.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, True)
    menuBar.setAutoFillBackground(False)
    if bool(menuBar.styleSheet().strip()):
        self._autoStyleMenuBar = False

    layout = self.layout()
    if layout is not None:
        iconIndex = layout.indexOf(self._iconLabel)
        insertIndex = iconIndex + 1 if iconIndex >= 0 else 0
        layout.insertWidget(
            insertIndex,
            menuBar,
            0,
            Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter,
        )

    self._updateMenuBarStyle()

setPressToMove(enabled)

Enable or disable dragging window from title bar.

Parameters:

Name Type Description Default
enabled bool

True to enable press-to-move dragging.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setPressToMove(self, enabled: bool) -> None:
    """Enable or disable dragging window from title bar.

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

setTitle(title)

Set the window title text.

Parameters:

Name Type Description Default
title str

Title string to display.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setTitle(self, title: str) -> None:
    """Set the window title text.

    Parameters
    ----------
    title : str
        Title string to display.
    """
    self._titleLabel.setText(title)

setTitleAlignment(alignment)

Set the horizontal alignment of the window title.

Parameters:

Name Type Description Default
alignment AlignmentFlag

Target alignment flag (e.g. Qt.AlignmentFlag.AlignCenter or Qt.AlignmentFlag.AlignLeft).

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setTitleAlignment(self, alignment: Qt.AlignmentFlag) -> None:
    """Set the horizontal alignment of the window title.

    Parameters
    ----------
    alignment : Qt.AlignmentFlag
        Target alignment flag (e.g. Qt.AlignmentFlag.AlignCenter or Qt.AlignmentFlag.AlignLeft).
    """
    self._titleAlignment = alignment
    self._updateTitleAlignment()

setTitleBarFont(font)

Set the title label font and scale button heights proportionally.

Parameters:

Name Type Description Default
font QFont

Font to apply to the title text.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setTitleBarFont(self, font: QFont) -> None:
    """Set the title label font and scale button heights proportionally.

    Parameters
    ----------
    font : QFont
        Font to apply to the title text.
    """
    self._baseFont = QFont(font)
    currentDpi = getattr(self, "_currentDpi", 96)
    scaleFactor = currentDpi / 96.0

    scaledFont = QFont(self._baseFont)
    basePoints = self._baseFont.pointSizeF()
    if basePoints > 0:
        scaledFont.setPointSizeF(basePoints * scaleFactor)
    else:
        basePixels = self._baseFont.pixelSize()
        if basePixels > 0:
            scaledFont.setPixelSize(round(basePixels * scaleFactor))
    self._titleLabel.setFont(scaledFont)

    self._baseButtonHeight = font.pointSize() * 2
    newButtonHeight = round(self._baseButtonHeight * scaleFactor)
    for button in self._buttonDict.values():
        if isinstance(button, VectorButton):
            button.updateButtonHeight(newButtonHeight)

setTitleBarHint(hint)

Show only the control buttons specified in hint list.

Parameters:

Name Type Description Default
hint list of str or None

Button keys to display ('min', 'max', 'close', 'full_screen'). Defaults to standard set ('min', 'max', 'close') when None.

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def setTitleBarHint(self, hint: list[str] | None) -> None:
    """Show only the control buttons specified in hint list.

    Parameters
    ----------
    hint : list of str or None
        Button keys to display ('min', 'max', 'close', 'full_screen').
        Defaults to standard set ('min', 'max', 'close') when None.
    """
    if hint is None:
        hint = ["min", "max", "close"]

    visibleSet = set(hint)
    for key, button in self._buttonDict.items():
        button.setVisible(key in visibleSet)

updateDpiScaling(dpi)

Recalculate layout margins, button bounds, icon, and title font for new DPI.

Parameters:

Name Type Description Default
dpi int

Active dots-per-inch scaling factor (e.g. 96 for 100%, 144 for 150%).

required
Source code in src/qtframelesskit/windows/title_bar/title_bar.py
def updateDpiScaling(self, dpi: int) -> None:
    """Recalculate layout margins, button bounds, icon, and title font for new DPI.

    Parameters
    ----------
    dpi : int
        Active dots-per-inch scaling factor (e.g. 96 for 100%, 144 for 150%).
    """
    if dpi <= 0:
        dpi = 96
    self._currentDpi = dpi
    scaleFactor = dpi / 96.0

    if hasattr(self, "_baseFont"):
        scaledFont = QFont(self._baseFont)
        basePoints = self._baseFont.pointSizeF()
        if basePoints > 0:
            scaledFont.setPointSizeF(basePoints * scaleFactor)
        else:
            basePixels = self._baseFont.pixelSize()
            if basePixels > 0:
                scaledFont.setPixelSize(round(basePixels * scaleFactor))
        self._titleLabel.setFont(scaledFont)

    scaledButtonHeight = max(24, round(self._baseButtonHeight * scaleFactor))
    for button in self._buttonDict.values():
        if isinstance(button, VectorButton):
            button.updateButtonHeight(scaledButtonHeight)

    if hasattr(self, "_windowIcon") and not self._windowIcon.isNull():
        scaledWidth = round(self._baseIconWidth * scaleFactor)
        scaledHeight = round(self._baseIconHeight * scaleFactor)
        self._iconLabel.setPixmap(self._windowIcon.pixmap(scaledWidth, scaledHeight))

    scaledMargin = max(2, round(4 * scaleFactor))
    self._iconLabel.setContentsMargins(scaledMargin, scaledMargin, scaledMargin, scaledMargin)
    self._titleLabel.setContentsMargins(scaledMargin, scaledMargin, scaledMargin, scaledMargin)

    scaledLayoutLeft = max(4, round(8 * scaleFactor))
    if self.layout() is not None:
        self.layout().setContentsMargins(scaledLayoutLeft, 0, 0, 0)

    self.updateGeometry()
    self.setMaximumHeight(self.sizeHint().height())

TitleBarDragHandler

Handles native window dragging and maximize toggling via mouse interactions.

Source code in src/qtframelesskit/windows/title_bar/drag_handler.py
class TitleBarDragHandler:
    """Handles native window dragging and maximize toggling via mouse interactions."""

    def __init__(self, titleBar: TitleBar) -> None:
        """Initialize drag handler associated with a title bar instance.

        Parameters
        ----------
        titleBar : TitleBar
            The parent TitleBar instance to manage mouse dragging and double clicks for.
        """
        self._titleBar = titleBar

    def isMenuBarClick(self, clickPosition: QPoint, targetChild: QWidget | None) -> bool:
        """Determine whether a click position or child widget belongs to the integrated menu bar.

        Parameters
        ----------
        clickPosition : QPoint
            The position of the mouse click in title bar coordinates.
        targetChild : QWidget or None
            The child widget located at the click position, or None if none.

        Returns
        -------
        bool
            True if the click targets the menu bar or one of its child widgets, False otherwise.
        """
        menuBar = self._titleBar.getMenuBar()
        if menuBar is None:
            return False
        isChildOfMenuBar = targetChild is not None and (
            targetChild is menuBar or menuBar.isAncestorOf(targetChild)
        )
        resolvedPoint = (
            clickPosition.toPoint() if hasattr(clickPosition, "toPoint") else clickPosition
        )
        return isChildOfMenuBar or menuBar.geometry().contains(resolvedPoint)

    def isInteractiveChild(self, childWidget: QWidget | None, clickPosition: QPoint) -> bool:
        """Determine whether a child widget or click position represents an interactive element.

        Parameters
        ----------
        childWidget : QWidget or None
            The child widget at the interaction position.
        clickPosition : QPoint
            The position of the mouse interaction in title bar coordinates.

        Returns
        -------
        bool
            True if the child widget is an interactive center widget or menu bar, False otherwise.
        """
        centerWidget = self._titleBar.getCenterWidget()
        isCenterInteractive = (
            centerWidget is not None
            and childWidget is not None
            and (childWidget is centerWidget or centerWidget.isAncestorOf(childWidget))
        )
        isMenuBarInteractive = self.isMenuBarClick(clickPosition, childWidget)
        return isCenterInteractive or isMenuBarInteractive

    def handleMousePress(self, event: QMouseEvent) -> bool:
        """Handle mouse press event on title bar to initiate system window drag.

        Parameters
        ----------
        event : QMouseEvent
            The mouse press event.

        Returns
        -------
        bool
            True if system move was initiated and the event accepted, False otherwise.
        """
        if event.button() == Qt.MouseButton.LeftButton and self._titleBar.isPressToMove():
            clickPosition = (
                event.position().toPoint() if hasattr(event, "position") else event.pos()
            )
            targetChild = self._titleBar.childAt(clickPosition)
            isMenuBar = self.isMenuBarClick(clickPosition, targetChild)
            isDraggableWidget = not isMenuBar and targetChild in (
                None,
                self._titleBar.getTitle(),
                self._titleBar.getIcon(),
                self._titleBar._centerContainer,
                self._titleBar._cornerWidget,
            )
            if isDraggableWidget:
                targetWindow = self._titleBar.window()
                if targetWindow:
                    windowHandle = targetWindow.windowHandle()
                    if windowHandle:
                        windowHandle.startSystemMove()
                        event.accept()
                        return True
        return False

    def handleMouseDoubleClick(self, event: QMouseEvent) -> bool:
        """Handle mouse double-click event to toggle window maximized state.

        Parameters
        ----------
        event : QMouseEvent
            The mouse double-click event.

        Returns
        -------
        bool
            True if double click was handled and window maximized or restored, False otherwise.
        """
        if getattr(self._titleBar, "_baseWindowResizable", True) and (
            event.button() == Qt.MouseButton.LeftButton
        ):
            clickPosition = (
                event.position().toPoint() if hasattr(event, "position") else event.pos()
            )
            targetChild = self._titleBar.childAt(clickPosition)
            if not self.isInteractiveChild(targetChild, clickPosition):
                self._titleBar._handleMaximizeClicked()
                event.accept()
                return True
        return False

__init__(titleBar)

Initialize drag handler associated with a title bar instance.

Parameters:

Name Type Description Default
titleBar TitleBar

The parent TitleBar instance to manage mouse dragging and double clicks for.

required
Source code in src/qtframelesskit/windows/title_bar/drag_handler.py
def __init__(self, titleBar: TitleBar) -> None:
    """Initialize drag handler associated with a title bar instance.

    Parameters
    ----------
    titleBar : TitleBar
        The parent TitleBar instance to manage mouse dragging and double clicks for.
    """
    self._titleBar = titleBar

handleMouseDoubleClick(event)

Handle mouse double-click event to toggle window maximized state.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse double-click event.

required

Returns:

Type Description
bool

True if double click was handled and window maximized or restored, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/drag_handler.py
def handleMouseDoubleClick(self, event: QMouseEvent) -> bool:
    """Handle mouse double-click event to toggle window maximized state.

    Parameters
    ----------
    event : QMouseEvent
        The mouse double-click event.

    Returns
    -------
    bool
        True if double click was handled and window maximized or restored, False otherwise.
    """
    if getattr(self._titleBar, "_baseWindowResizable", True) and (
        event.button() == Qt.MouseButton.LeftButton
    ):
        clickPosition = (
            event.position().toPoint() if hasattr(event, "position") else event.pos()
        )
        targetChild = self._titleBar.childAt(clickPosition)
        if not self.isInteractiveChild(targetChild, clickPosition):
            self._titleBar._handleMaximizeClicked()
            event.accept()
            return True
    return False

handleMousePress(event)

Handle mouse press event on title bar to initiate system window drag.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse press event.

required

Returns:

Type Description
bool

True if system move was initiated and the event accepted, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/drag_handler.py
def handleMousePress(self, event: QMouseEvent) -> bool:
    """Handle mouse press event on title bar to initiate system window drag.

    Parameters
    ----------
    event : QMouseEvent
        The mouse press event.

    Returns
    -------
    bool
        True if system move was initiated and the event accepted, False otherwise.
    """
    if event.button() == Qt.MouseButton.LeftButton and self._titleBar.isPressToMove():
        clickPosition = (
            event.position().toPoint() if hasattr(event, "position") else event.pos()
        )
        targetChild = self._titleBar.childAt(clickPosition)
        isMenuBar = self.isMenuBarClick(clickPosition, targetChild)
        isDraggableWidget = not isMenuBar and targetChild in (
            None,
            self._titleBar.getTitle(),
            self._titleBar.getIcon(),
            self._titleBar._centerContainer,
            self._titleBar._cornerWidget,
        )
        if isDraggableWidget:
            targetWindow = self._titleBar.window()
            if targetWindow:
                windowHandle = targetWindow.windowHandle()
                if windowHandle:
                    windowHandle.startSystemMove()
                    event.accept()
                    return True
    return False

isInteractiveChild(childWidget, clickPosition)

Determine whether a child widget or click position represents an interactive element.

Parameters:

Name Type Description Default
childWidget QWidget or None

The child widget at the interaction position.

required
clickPosition QPoint

The position of the mouse interaction in title bar coordinates.

required

Returns:

Type Description
bool

True if the child widget is an interactive center widget or menu bar, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/drag_handler.py
def isInteractiveChild(self, childWidget: QWidget | None, clickPosition: QPoint) -> bool:
    """Determine whether a child widget or click position represents an interactive element.

    Parameters
    ----------
    childWidget : QWidget or None
        The child widget at the interaction position.
    clickPosition : QPoint
        The position of the mouse interaction in title bar coordinates.

    Returns
    -------
    bool
        True if the child widget is an interactive center widget or menu bar, False otherwise.
    """
    centerWidget = self._titleBar.getCenterWidget()
    isCenterInteractive = (
        centerWidget is not None
        and childWidget is not None
        and (childWidget is centerWidget or centerWidget.isAncestorOf(childWidget))
    )
    isMenuBarInteractive = self.isMenuBarClick(clickPosition, childWidget)
    return isCenterInteractive or isMenuBarInteractive

isMenuBarClick(clickPosition, targetChild)

Determine whether a click position or child widget belongs to the integrated menu bar.

Parameters:

Name Type Description Default
clickPosition QPoint

The position of the mouse click in title bar coordinates.

required
targetChild QWidget or None

The child widget located at the click position, or None if none.

required

Returns:

Type Description
bool

True if the click targets the menu bar or one of its child widgets, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/drag_handler.py
def isMenuBarClick(self, clickPosition: QPoint, targetChild: QWidget | None) -> bool:
    """Determine whether a click position or child widget belongs to the integrated menu bar.

    Parameters
    ----------
    clickPosition : QPoint
        The position of the mouse click in title bar coordinates.
    targetChild : QWidget or None
        The child widget located at the click position, or None if none.

    Returns
    -------
    bool
        True if the click targets the menu bar or one of its child widgets, False otherwise.
    """
    menuBar = self._titleBar.getMenuBar()
    if menuBar is None:
        return False
    isChildOfMenuBar = targetChild is not None and (
        targetChild is menuBar or menuBar.isAncestorOf(targetChild)
    )
    resolvedPoint = (
        clickPosition.toPoint() if hasattr(clickPosition, "toPoint") else clickPosition
    )
    return isChildOfMenuBar or menuBar.geometry().contains(resolvedPoint)

VectorButton

Bases: QPushButton

Base QPushButton subclass rendering crisp vector shapes via QPainter.

Parameters:

Name Type Description Default
parent QWidget

Parent widget holding this button.

None
Source code in src/qtframelesskit/windows/title_bar/buttons.py
class VectorButton(QPushButton):
    """Base QPushButton subclass rendering crisp vector shapes via QPainter.

    Parameters
    ----------
    parent : QWidget, optional
        Parent widget holding this button.
    """

    def __init__(self, parent: QWidget | None = None) -> None:
        super().__init__(parent)
        self._isDarkTheme = False
        self._isHovered = False
        self._isPressed = False
        self._glyphColor = QColor("#333333")
        self._hoverGlyphColor = QColor("#111111")
        self._customHoverColor: QColor | None = None
        self._customPressedColor: QColor | None = None
        self._currentBackgroundColor = self._getIdleColor()
        self._buttonWidth = 46
        self._buttonHeight = 30
        self.setFixedSize(self._buttonWidth, self._buttonHeight)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, True)

        self._colorAnimation = QVariantAnimation(self)
        self._colorAnimation.setDuration(120)
        self._colorAnimation.valueChanged.connect(self._onBackgroundColorChanged)

    def _onBackgroundColorChanged(self, color: QColor) -> None:
        """Update the active background color and request a widget repaint.

        Parameters
        ----------
        color : QColor
            Interpolated background color.
        """
        self._currentBackgroundColor = color
        self.update()

    def getCurrentBackgroundColor(self) -> QColor:
        """Return the current interpolated background color.

        Returns
        -------
        QColor
            Current background color.
        """
        return self._currentBackgroundColor

    def isHovered(self) -> bool:
        """Return whether the button is in a hovered visual state.

        Returns
        -------
        bool
            True if hovered directly or via non-client messages, False otherwise.
        """
        return self._isHovered or self.underMouse()

    def setHoverState(self, hovered: bool) -> None:
        """Set the hover visual state when handling non-client messages.

        Parameters
        ----------
        hovered : bool
            True to show hover styling, False to clear.
        """
        if self._isHovered != hovered:
            self._isHovered = hovered
            self._animateToTargetColor()

    def isPressedState(self) -> bool:
        """Return whether the button is in a pressed visual state.

        Returns
        -------
        bool
            True if pressed directly or via non-client messages, False otherwise.
        """
        return self._isPressed or self.isDown()

    def setPressedState(self, pressed: bool) -> None:
        """Set the pressed visual state when handling non-client mouse click messages.

        Parameters
        ----------
        pressed : bool
            True to show pressed styling, False to clear.
        """
        if self._isPressed != pressed or self.isDown() != pressed:
            self._isPressed = pressed
            self.setDown(pressed)
            self._animateToTargetColor()

    def enterEvent(self, event: QEvent) -> None:
        """Handle mouse enter event and trigger background hover transition.

        Parameters
        ----------
        event : QEvent
            Mouse enter event.
        """
        self._isHovered = True
        super().enterEvent(event)
        self._animateToTargetColor()

    def leaveEvent(self, event: QEvent) -> None:
        """Handle mouse leave event and trigger background restore transition.

        Parameters
        ----------
        event : QEvent
            Mouse leave event.
        """
        self._isHovered = False
        self._isPressed = False
        super().leaveEvent(event)
        self._animateToTargetColor()

    def mousePressEvent(self, event: QMouseEvent) -> None:
        """Handle mouse press event and trigger background pressed transition.

        Parameters
        ----------
        event : QMouseEvent
            Mouse press event.
        """
        super().mousePressEvent(event)
        self._animateToTargetColor()

    def mouseReleaseEvent(self, event: QMouseEvent) -> None:
        """Handle mouse release event and transition to hover or idle color.

        Parameters
        ----------
        event : QMouseEvent
            Mouse release event.
        """
        super().mouseReleaseEvent(event)
        self._animateToTargetColor()

    def _getHoverColor(self) -> QColor:
        """Return target background color when button is hovered.

        Uses crisp Windows 11 contrasting tones (#cfcfcf light, #3f3f3f dark)
        so the button highlight remains distinct on both opaque windows and
        translucent backdrop materials like Mica Alt, Mica, and Acrylic.

        Returns
        -------
        QColor
            Hover target color according to current theme or custom override.
        """
        if self._customHoverColor is not None:
            return self._customHoverColor
        return QColor("#3f3f3f") if self._isDarkTheme else QColor("#cfcfcf")

    def _getPressedColor(self) -> QColor:
        """Return target background color when button is pressed down.

        Returns
        -------
        QColor
            Pressed target color according to current theme or custom override.
        """
        if self._customPressedColor is not None:
            return self._customPressedColor
        return QColor("#525252") if self._isDarkTheme else QColor("#b8b8b8")

    def getHoverColor(self) -> QColor:
        """Return the effective background color applied when hovered.

        Returns
        -------
        QColor
            Current hover color.
        """
        return self._getHoverColor()

    def setHoverColor(self, color: QColor | str | None) -> None:
        """Configure a custom hover background color.

        Parameters
        ----------
        color : QColor, str, or None
            Custom hover color, or None to revert to theme default.
        """
        if color is None:
            self._customHoverColor = None
        elif isinstance(color, QColor):
            self._customHoverColor = QColor(color)
        else:
            self._customHoverColor = QColor(color)
        self._animateToTargetColor()

    def getPressedColor(self) -> QColor:
        """Return the effective background color applied when pressed down.

        Returns
        -------
        QColor
            Current pressed color.
        """
        return self._getPressedColor()

    def setPressedColor(self, color: QColor | str | None) -> None:
        """Configure a custom pressed background color.

        Parameters
        ----------
        color : QColor, str, or None
            Custom pressed color, or None to revert to theme default.
        """
        if color is None:
            self._customPressedColor = None
        elif isinstance(color, QColor):
            self._customPressedColor = QColor(color)
        else:
            self._customPressedColor = QColor(color)
        self._animateToTargetColor()

    def _getIdleColor(self) -> QColor:
        """Return transparent base color aligned with hover RGB to avoid dark flash.

        Returns
        -------
        QColor
            Transparent idle color sharing the hover RGB components.
        """
        hover = self._getHoverColor()
        return QColor(hover.red(), hover.green(), hover.blue(), 0)

    def _getTargetColor(self) -> QColor:
        """Determine target background color based on hover and pressed states.

        Returns
        -------
        QColor
            Target color for the current state.
        """
        if self.isPressedState():
            return self._getPressedColor()
        if self.isHovered():
            return self._getHoverColor()
        return self._getIdleColor()

    def _animateToTargetColor(self) -> None:
        """Start or redirect background color interpolation toward current target."""
        targetColor = self._getTargetColor()
        if (
            self._currentBackgroundColor == targetColor
            and self._colorAnimation.state() == QVariantAnimation.State.Stopped
        ):
            return
        self._colorAnimation.stop()
        self._colorAnimation.setStartValue(self._currentBackgroundColor)
        self._colorAnimation.setEndValue(targetColor)
        self._colorAnimation.start()

    def setDarkTheme(self, isDark: bool) -> None:
        """Update button stroke and hover background styles for dark mode.

        Parameters
        ----------
        isDark : bool
            True to apply dark theme styles, False for light theme.
        """
        self._isDarkTheme = isDark
        if isDark:
            self._glyphColor = QColor("#ffffff")
            self._hoverGlyphColor = QColor("#ffffff")
        else:
            self._glyphColor = QColor("#333333")
            self._hoverGlyphColor = QColor("#111111")
        if not self.isHovered() and not self.isPressedState():
            self._currentBackgroundColor = self._getIdleColor()
            self.update()
        else:
            self._animateToTargetColor()

    def setGlyphColor(self, color: QColor) -> None:
        """Set the normal stroke color for the vector glyph.

        Parameters
        ----------
        color : QColor
            New stroke color for the glyph.
        """
        self._glyphColor = color
        self.update()

    def getGlyphColor(self) -> QColor:
        """Return the normal stroke color of the vector glyph.

        Returns
        -------
        QColor
            Current stroke color.
        """
        return self._glyphColor

    def updateButtonHeight(self, newHeight: int) -> None:
        """Update button height maintaining proportional width.

        Parameters
        ----------
        newHeight : int
            New button height in pixels.
        """
        self._buttonHeight = max(24, newHeight)
        self._buttonWidth = round(self._buttonHeight * 1.4)
        self.setFixedSize(self._buttonWidth, self._buttonHeight)

    def getGlyphScaleFactor(self) -> float:
        """Return a subtle scaling factor for vector glyphs relative to base height.

        Dampens scaling so glyph symbols only grow slightly at high DPI rather
        than scaling linearly with button height (e.g. 1.25x at 200% scaling).

        Returns
        -------
        float
            Dampened scale multiplier where 1.0 corresponds to standard 30px height.
        """
        rawRatio = self._buttonHeight / 30.0
        return max(0.85, 1.0 + (rawRatio - 1.0) * 0.25)

    def paintEvent(self, event: QPaintEvent) -> None:
        """Paint button background directly using QPainter without native chrome.

        Leaves idle buttons completely transparent so parent window or title bar
        backgrounds show through cleanly, only rendering hover or pressed fill
        when the background color has positive alpha.

        Parameters
        ----------
        event : QPaintEvent
            The paint event.
        """
        if self._currentBackgroundColor.alpha() > 0:
            painter = QPainter(self)
            painter.fillRect(self.rect(), self._currentBackgroundColor)
            painter.end()

enterEvent(event)

Handle mouse enter event and trigger background hover transition.

Parameters:

Name Type Description Default
event QEvent

Mouse enter event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def enterEvent(self, event: QEvent) -> None:
    """Handle mouse enter event and trigger background hover transition.

    Parameters
    ----------
    event : QEvent
        Mouse enter event.
    """
    self._isHovered = True
    super().enterEvent(event)
    self._animateToTargetColor()

getCurrentBackgroundColor()

Return the current interpolated background color.

Returns:

Type Description
QColor

Current background color.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def getCurrentBackgroundColor(self) -> QColor:
    """Return the current interpolated background color.

    Returns
    -------
    QColor
        Current background color.
    """
    return self._currentBackgroundColor

getGlyphColor()

Return the normal stroke color of the vector glyph.

Returns:

Type Description
QColor

Current stroke color.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def getGlyphColor(self) -> QColor:
    """Return the normal stroke color of the vector glyph.

    Returns
    -------
    QColor
        Current stroke color.
    """
    return self._glyphColor

getGlyphScaleFactor()

Return a subtle scaling factor for vector glyphs relative to base height.

Dampens scaling so glyph symbols only grow slightly at high DPI rather than scaling linearly with button height (e.g. 1.25x at 200% scaling).

Returns:

Type Description
float

Dampened scale multiplier where 1.0 corresponds to standard 30px height.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def getGlyphScaleFactor(self) -> float:
    """Return a subtle scaling factor for vector glyphs relative to base height.

    Dampens scaling so glyph symbols only grow slightly at high DPI rather
    than scaling linearly with button height (e.g. 1.25x at 200% scaling).

    Returns
    -------
    float
        Dampened scale multiplier where 1.0 corresponds to standard 30px height.
    """
    rawRatio = self._buttonHeight / 30.0
    return max(0.85, 1.0 + (rawRatio - 1.0) * 0.25)

getHoverColor()

Return the effective background color applied when hovered.

Returns:

Type Description
QColor

Current hover color.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def getHoverColor(self) -> QColor:
    """Return the effective background color applied when hovered.

    Returns
    -------
    QColor
        Current hover color.
    """
    return self._getHoverColor()

getPressedColor()

Return the effective background color applied when pressed down.

Returns:

Type Description
QColor

Current pressed color.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def getPressedColor(self) -> QColor:
    """Return the effective background color applied when pressed down.

    Returns
    -------
    QColor
        Current pressed color.
    """
    return self._getPressedColor()

isHovered()

Return whether the button is in a hovered visual state.

Returns:

Type Description
bool

True if hovered directly or via non-client messages, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def isHovered(self) -> bool:
    """Return whether the button is in a hovered visual state.

    Returns
    -------
    bool
        True if hovered directly or via non-client messages, False otherwise.
    """
    return self._isHovered or self.underMouse()

isPressedState()

Return whether the button is in a pressed visual state.

Returns:

Type Description
bool

True if pressed directly or via non-client messages, False otherwise.

Source code in src/qtframelesskit/windows/title_bar/buttons.py
def isPressedState(self) -> bool:
    """Return whether the button is in a pressed visual state.

    Returns
    -------
    bool
        True if pressed directly or via non-client messages, False otherwise.
    """
    return self._isPressed or self.isDown()

leaveEvent(event)

Handle mouse leave event and trigger background restore transition.

Parameters:

Name Type Description Default
event QEvent

Mouse leave event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def leaveEvent(self, event: QEvent) -> None:
    """Handle mouse leave event and trigger background restore transition.

    Parameters
    ----------
    event : QEvent
        Mouse leave event.
    """
    self._isHovered = False
    self._isPressed = False
    super().leaveEvent(event)
    self._animateToTargetColor()

mousePressEvent(event)

Handle mouse press event and trigger background pressed transition.

Parameters:

Name Type Description Default
event QMouseEvent

Mouse press event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def mousePressEvent(self, event: QMouseEvent) -> None:
    """Handle mouse press event and trigger background pressed transition.

    Parameters
    ----------
    event : QMouseEvent
        Mouse press event.
    """
    super().mousePressEvent(event)
    self._animateToTargetColor()

mouseReleaseEvent(event)

Handle mouse release event and transition to hover or idle color.

Parameters:

Name Type Description Default
event QMouseEvent

Mouse release event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def mouseReleaseEvent(self, event: QMouseEvent) -> None:
    """Handle mouse release event and transition to hover or idle color.

    Parameters
    ----------
    event : QMouseEvent
        Mouse release event.
    """
    super().mouseReleaseEvent(event)
    self._animateToTargetColor()

paintEvent(event)

Paint button background directly using QPainter without native chrome.

Leaves idle buttons completely transparent so parent window or title bar backgrounds show through cleanly, only rendering hover or pressed fill when the background color has positive alpha.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def paintEvent(self, event: QPaintEvent) -> None:
    """Paint button background directly using QPainter without native chrome.

    Leaves idle buttons completely transparent so parent window or title bar
    backgrounds show through cleanly, only rendering hover or pressed fill
    when the background color has positive alpha.

    Parameters
    ----------
    event : QPaintEvent
        The paint event.
    """
    if self._currentBackgroundColor.alpha() > 0:
        painter = QPainter(self)
        painter.fillRect(self.rect(), self._currentBackgroundColor)
        painter.end()

setDarkTheme(isDark)

Update button stroke and hover background styles for dark mode.

Parameters:

Name Type Description Default
isDark bool

True to apply dark theme styles, False for light theme.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def setDarkTheme(self, isDark: bool) -> None:
    """Update button stroke and hover background styles for dark mode.

    Parameters
    ----------
    isDark : bool
        True to apply dark theme styles, False for light theme.
    """
    self._isDarkTheme = isDark
    if isDark:
        self._glyphColor = QColor("#ffffff")
        self._hoverGlyphColor = QColor("#ffffff")
    else:
        self._glyphColor = QColor("#333333")
        self._hoverGlyphColor = QColor("#111111")
    if not self.isHovered() and not self.isPressedState():
        self._currentBackgroundColor = self._getIdleColor()
        self.update()
    else:
        self._animateToTargetColor()

setGlyphColor(color)

Set the normal stroke color for the vector glyph.

Parameters:

Name Type Description Default
color QColor

New stroke color for the glyph.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def setGlyphColor(self, color: QColor) -> None:
    """Set the normal stroke color for the vector glyph.

    Parameters
    ----------
    color : QColor
        New stroke color for the glyph.
    """
    self._glyphColor = color
    self.update()

setHoverColor(color)

Configure a custom hover background color.

Parameters:

Name Type Description Default
color QColor, str, or None

Custom hover color, or None to revert to theme default.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def setHoverColor(self, color: QColor | str | None) -> None:
    """Configure a custom hover background color.

    Parameters
    ----------
    color : QColor, str, or None
        Custom hover color, or None to revert to theme default.
    """
    if color is None:
        self._customHoverColor = None
    elif isinstance(color, QColor):
        self._customHoverColor = QColor(color)
    else:
        self._customHoverColor = QColor(color)
    self._animateToTargetColor()

setHoverState(hovered)

Set the hover visual state when handling non-client messages.

Parameters:

Name Type Description Default
hovered bool

True to show hover styling, False to clear.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def setHoverState(self, hovered: bool) -> None:
    """Set the hover visual state when handling non-client messages.

    Parameters
    ----------
    hovered : bool
        True to show hover styling, False to clear.
    """
    if self._isHovered != hovered:
        self._isHovered = hovered
        self._animateToTargetColor()

setPressedColor(color)

Configure a custom pressed background color.

Parameters:

Name Type Description Default
color QColor, str, or None

Custom pressed color, or None to revert to theme default.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def setPressedColor(self, color: QColor | str | None) -> None:
    """Configure a custom pressed background color.

    Parameters
    ----------
    color : QColor, str, or None
        Custom pressed color, or None to revert to theme default.
    """
    if color is None:
        self._customPressedColor = None
    elif isinstance(color, QColor):
        self._customPressedColor = QColor(color)
    else:
        self._customPressedColor = QColor(color)
    self._animateToTargetColor()

setPressedState(pressed)

Set the pressed visual state when handling non-client mouse click messages.

Parameters:

Name Type Description Default
pressed bool

True to show pressed styling, False to clear.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def setPressedState(self, pressed: bool) -> None:
    """Set the pressed visual state when handling non-client mouse click messages.

    Parameters
    ----------
    pressed : bool
        True to show pressed styling, False to clear.
    """
    if self._isPressed != pressed or self.isDown() != pressed:
        self._isPressed = pressed
        self.setDown(pressed)
        self._animateToTargetColor()

updateButtonHeight(newHeight)

Update button height maintaining proportional width.

Parameters:

Name Type Description Default
newHeight int

New button height in pixels.

required
Source code in src/qtframelesskit/windows/title_bar/buttons.py
def updateButtonHeight(self, newHeight: int) -> None:
    """Update button height maintaining proportional width.

    Parameters
    ----------
    newHeight : int
        New button height in pixels.
    """
    self._buttonHeight = max(24, newHeight)
    self._buttonWidth = round(self._buttonHeight * 1.4)
    self.setFixedSize(self._buttonWidth, self._buttonHeight)