CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pyqt-fluent-widgets

A fluent design widgets library based on PyQt5 providing modern Windows 11-style UI components

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

dialog-notification.mddocs/

Dialog and Notification System

Modal dialogs, message boxes, flyouts, and notification components with fluent design animations and positioning. These components provide modern user feedback and interaction patterns with smooth animations and proper accessibility support.

Capabilities

Modal Dialogs

Standard modal dialogs with fluent design styling and automatic positioning.

class Dialog(MaskDialogBase):
    def __init__(self, title: str, content: str, parent=None): ...
    def setTitleBarVisible(self, visible: bool): ...
    def titleBarVisible(self) -> bool: ...

class MessageBox(MaskDialogBase):
    def __init__(self, title: str, content: str, parent=None): ...
    def addButton(self, text: str, role: QMessageBox.ButtonRole) -> QPushButton: ...
    def buttonClicked = pyqtSignal(QPushButton)

class MessageDialog(MaskDialogBase):
    def __init__(self, title: str, content: str, parent=None): ...
    def setIcon(self, icon: Union[QIcon, FluentIconBase]): ...

Usage Example:

from qfluentwidgets import Dialog, MessageBox, FluentIcon as FIF

# Basic dialog
dialog = Dialog("Settings", "Configure your preferences", self)
dialog.setTitleBarVisible(True)

if dialog.exec() == QDialog.Accepted:
    print("Settings saved")

# Message box with buttons
msg_box = MessageBox("Confirm Action", "Are you sure you want to delete this item?", self)
msg_box.addButton("Delete", QMessageBox.AcceptRole)
msg_box.addButton("Cancel", QMessageBox.RejectRole)

msg_box.buttonClicked.connect(self.handle_message_response)

def handle_message_response(self, button):
    if button.text() == "Delete":
        self.delete_item()

Specialized Dialogs

Purpose-built dialogs for common operations like color selection and folder management.

class ColorDialog(MaskDialogBase):
    def __init__(self, color: QColor, title: str, parent=None, enableAlpha: bool = False): ...
    def setColor(self, color: QColor): ...
    def color(self) -> QColor: ...
    
    colorChanged = pyqtSignal(QColor)

class FolderListDialog(MaskDialogBase):
    def __init__(self, folders: List[str], title: str, parent=None): ...
    def addFolder(self, folder: str): ...
    def removeFolder(self, folder: str): ...
    def folders(self) -> List[str]: ...
    
    foldersChanged = pyqtSignal(list)

Usage Example:

from qfluentwidgets import ColorDialog, FolderListDialog
from PyQt5.QtGui import QColor

# Color picker dialog
color_dialog = ColorDialog(QColor(255, 0, 0), "Choose Color", self, enableAlpha=True)
color_dialog.colorChanged.connect(self.on_color_changed)

if color_dialog.exec() == QDialog.Accepted:
    selected_color = color_dialog.color()
    print(f"Selected color: {selected_color.name()}")

# Folder list dialog
folders = ["/home/user/Documents", "/home/user/Pictures"]
folder_dialog = FolderListDialog(folders, "Manage Folders", self)
folder_dialog.foldersChanged.connect(self.update_folder_list)

if folder_dialog.exec() == QDialog.Accepted:
    new_folders = folder_dialog.folders()
    self.save_folder_preferences(new_folders)

Information Bars

Non-intrusive notification bars for status updates and user feedback.

class InfoBar(QWidget):
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], title: str, content: str,
                 orientation: Qt.Orientation = Qt.Horizontal, isClosable: bool = True,
                 duration: int = -1, position: InfoBarPosition = InfoBarPosition.TOP,
                 parent=None): ...
    def addWidget(self, widget: QWidget): ...
    def setCustomBackgroundColor(self, color: str, color_dark: str): ...
    def close(self): ...
    
    closedSignal = pyqtSignal()

class InfoBarPosition(Enum):
    TOP = 0
    BOTTOM = 1
    TOP_LEFT = 2
    TOP_RIGHT = 3
    BOTTOM_LEFT = 4
    BOTTOM_RIGHT = 5
    LEFT = 6
    RIGHT = 7

Usage Example:

from qfluentwidgets import InfoBar, InfoBarPosition, FluentIcon as FIF

# Success notification
success_bar = InfoBar(
    FIF.ACCEPT,
    "Success",
    "File saved successfully",
    duration=3000,  # Auto-close after 3 seconds
    position=InfoBarPosition.TOP,
    parent=self
)
success_bar.show()

# Error notification with custom action
error_bar = InfoBar(
    FIF.ERROR,
    "Error",
    "Failed to connect to server",
    isClosable=True,
    parent=self
)

# Add retry button
retry_btn = PushButton("Retry")
retry_btn.clicked.connect(self.retry_connection)
error_bar.addWidget(retry_btn)

error_bar.show()

Information Badges

Small status indicators for showing notifications, counts, or status information.

class InfoBadge(QWidget):
    def __init__(self, text: str = "", parent=None): ...
    def setText(self, text: str): ...
    def text(self) -> str: ...
    def setCustomBackgroundColor(self, color: str, color_dark: str): ...

class DotInfoBadge(InfoBadge):
    def __init__(self, parent=None): ...

class IconInfoBadge(InfoBadge):
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], parent=None): ...
    def setIcon(self, icon: Union[FluentIconBase, QIcon, str]): ...

Usage Example:

from qfluentwidgets import InfoBadge, DotInfoBadge, IconInfoBadge, FluentIcon as FIF

# Notification count badge
count_badge = InfoBadge("5", self)
count_badge.setCustomBackgroundColor("#d13438", "#d13438")

# Status dot
status_dot = DotInfoBadge(self)
status_dot.setCustomBackgroundColor("#10893e", "#10893e")

# Icon badge
icon_badge = IconInfoBadge(FIF.MAIL, self)

# Position badges on buttons
button = PushButton("Messages", self)
count_badge.move(button.x() + button.width() - 10, button.y() - 5)

Teaching Tips and Flyouts

Educational tooltips and contextual information panels with rich content support.

class TeachingTip(QWidget):
    def __init__(self, target: QWidget, parent=None): ...
    def setTitle(self, title: str): ...
    def setContent(self, content: str): ...
    def addWidget(self, widget: QWidget): ...
    def show(self): ...
    def close(self): ...

class PopupTeachingTip(TeachingTip):
    def __init__(self, title: str, content: str, image: str = "", isClosable: bool = True,
                 tailPosition: TeachingTipTailPosition = TeachingTipTailPosition.BOTTOM,
                 duration: int = -1, parent=None): ...

class TeachingTipTailPosition(Enum):
    TOP = 0
    BOTTOM = 1
    LEFT = 2
    RIGHT = 3
    TOP_LEFT = 4
    TOP_RIGHT = 5
    BOTTOM_LEFT = 6
    BOTTOM_RIGHT = 7

class Flyout(QWidget):
    def __init__(self, parent=None): ...
    def addWidget(self, widget: QWidget): ...
    def show(self, target: QWidget): ...
    def close(self): ...

class FlyoutView(QWidget):
    def __init__(self, parent=None): ...
    def setTitle(self, title: str): ...
    def setContent(self, content: str): ...

Usage Example:

from qfluentwidgets import PopupTeachingTip, Flyout, TeachingTipTailPosition

# Teaching tip for onboarding
teaching_tip = PopupTeachingTip(
    "Welcome!",
    "Click here to create a new document. You can also use Ctrl+N as a shortcut.",
    isClosable=True,
    tailPosition=TeachingTipTailPosition.BOTTOM,
    duration=5000,
    parent=self
)

# Show near target button
teaching_tip.show()

# Custom flyout with widgets
flyout = Flyout(self)
flyout_content = QWidget()
layout = QVBoxLayout(flyout_content)

title_label = TitleLabel("Quick Actions")
layout.addWidget(title_label)

action_btn = PushButton("Perform Action")
layout.addWidget(action_btn)

flyout.addWidget(flyout_content)
flyout.show(target_button)

Tooltips

Enhanced tooltips with rich content and fluent design styling.

class ToolTip(QWidget):
    def __init__(self, text: str = "", parent=None): ...
    def setText(self, text: str): ...
    def setTitle(self, title: str): ...
    def show(self, pos: QPoint, duration: int = 1000): ...

class StateToolTip(QWidget):
    def __init__(self, title: str, content: str, parent=None): ...
    def setTitle(self, title: str): ...
    def setContent(self, content: str): ...
    def move(self, pos: QPoint): ...
    def show(self): ...

class ToolTipFilter(QObject):
    def __init__(self, parent=None): ...
    def eventFilter(self, obj: QObject, event: QEvent) -> bool: ...

Usage Example:

from qfluentwidgets import ToolTip, StateToolTip, ToolTipFilter

# Rich tooltip
tooltip = ToolTip("This is a helpful tooltip with additional information", self)
tooltip.setTitle("Help")

# Install tooltip filter for automatic showing
tooltip_filter = ToolTipFilter()
button.installEventFilter(tooltip_filter)

# State tooltip for progress indication
state_tooltip = StateToolTip("Processing", "Please wait while the operation completes...", self)
state_tooltip.show()

# Auto-hide after operation
self.operation_completed.connect(state_tooltip.close)

Dialog Base Classes

Base classes for creating custom dialogs with fluent design integration.

class MaskDialogBase(QDialog):
    def __init__(self, parent=None): ...
    def showEvent(self, event: QShowEvent): ...
    def hideEvent(self, event: QHideEvent): ...
    def setMaskColor(self, color: QColor): ...

class DialogQuitOnLastWindowClosedPolicy:
    def __init__(self): ...

Usage Example:

from qfluentwidgets import MaskDialogBase

class CustomDialog(MaskDialogBase):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setupUi()
        
    def setupUi(self):
        layout = QVBoxLayout(self)
        
        # Add custom content
        self.title_label = TitleLabel("Custom Dialog")
        self.content_widget = QWidget()
        
        layout.addWidget(self.title_label)
        layout.addWidget(self.content_widget)
        
        # Buttons
        button_layout = QHBoxLayout()
        self.ok_button = PrimaryPushButton("OK")
        self.cancel_button = PushButton("Cancel")
        
        button_layout.addWidget(self.cancel_button)
        button_layout.addWidget(self.ok_button)
        layout.addLayout(button_layout)
        
        # Connect signals
        self.ok_button.clicked.connect(self.accept)
        self.cancel_button.clicked.connect(self.reject)

# Usage
dialog = CustomDialog(self)
if dialog.exec() == QDialog.Accepted:
    print("Dialog accepted")

Animation and Effects

Dialogs and notifications include smooth animations and transitions:

# Dialogs automatically include:
# - Fade in/out animations
# - Blur background effects
# - Smooth positioning
# - Responsive scaling

# InfoBars include:
# - Slide in/out animations
# - Auto-dismiss timers
# - Smooth color transitions

# Teaching tips include:
# - Bounce animations
# - Arrow positioning
# - Content transitions

Accessibility Features

All dialog and notification components include accessibility support:

# Set accessible properties
dialog.setAccessibleName("Settings Dialog")
info_bar.setAccessibleDescription("Success notification")
teaching_tip.setAccessibleRole(QAccessible.ToolTip)

# Keyboard navigation
dialog.setTabOrder(ok_button, cancel_button)

# Screen reader support
info_bar.setAccessibleText(f"{title}: {content}")

Install with Tessl CLI

npx tessl i tessl/pypi-pyqt-fluent-widgets

docs

buttons.md

dialog-notification.md

display-widgets.md

index.md

input-controls.md

layout-animation.md

list-view-widgets.md

material-effects.md

menu-command.md

multimedia.md

settings-config.md

theme-styling.md

window-navigation.md

tile.json