PyQt Fluent Widgets

https://github.com/zhiyiyo/pyqt-fluent-widgets
Admin
A fluent design widgets library based on C++ Qt/PyQt/PySide. Make Qt Great Again.
Tokens:123,415
Snippets:821
Trust Score:9.5
License:GPL-3.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Run gallery example

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/README.md

After installing the package, navigate to the examples/gallery directory and run the demo.py file to launch the gallery example.

```shell
cd examples/gallery
python demo.py
```

--------------------------------

### Base install requirements from setup.py

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/index.md

Lists the base dependencies required for installation, as specified in setup.py's install_requires.

```text
PyQt5>=5.15.0
PyQt5-Frameless-Window>=0.8.0
darkdetect
```

--------------------------------

### Usage Examples

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/icon.md

Examples demonstrating how to use fluent icons in various scenarios, including theme-aware icons, colored/reversed icons, and error handling for font icons.

```APIDOC
## Usage

### Basic - theme-aware icon on a button

```python
from PyQt5.QtWidgets import QApplication, QPushButton
from qfluentwidgets import FluentIcon, Icon

app = QApplication([])
button = QPushButton()
button.setIcon(FluentIcon.SEARCH.qicon())        # auto updates when app theme changes
button.setIcon(QIcon(Icon(FluentIcon.HOME)))      # snapshot at construction time
```

### Advanced - colored/reversed icons and custom SVG rendering

```python
from qfluentwidgets import FluentIcon, Theme, drawIcon
from PyQt5.QtGui import QPainter, QColor

# two-color variant: white icon in light mode, black in dark mode (reversed)
reversed_icon = FluentIcon.SETTING.qicon(reverse=True)

# hard-coded colors per theme
colored = FluentIcon.PLAY.colored(QColor("black"), QColor("#009faa"))
button.setIcon(colored.qicon())

# manual painting into a widget's painter
def paintEvent(self, e):
    painter = QPainter(self)
    FluentIcon.SEND.render(painter, self.rect(), theme=Theme.DARK, fill="#009faa")
```

### Error handling - font icons raise when resources are missing

```python
from qfluentwidgets import FluentFontIconBase

class MyFontIcon(FluentFontIconBase):
    def path(self, theme=Theme.AUTO):
        return ":/fonts/my_icon_font.ttf"

try:
    MyFontIcon("\uE001")          # loadFont() opens the ttf
except FileNotFoundError as e:
    print(f"font file missing: {e}")
```
```

--------------------------------

### Usage Examples

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/config.md

Examples for basic and advanced usage of the config API.

```APIDOC
## Usage Example

### Basic Theme and Color Access
```python
from PyQt5.QtWidgets import QApplication
from qfluentwidgets import qconfig, Theme, isDarkTheme, theme

app = QApplication([])

print(qconfig.get(qconfig.themeMode))        # Theme.LIGHT
qconfig.set(qconfig.themeColor, '#009faa')   # updates themeColorChanged, saves config
print(qconfig.get(qconfig.fontFamilies))     # ['Segoe UI', 'Microsoft YaHei', 'PingFang SC']
print(isDarkTheme(), theme())                # False Theme.LIGHT
```

### Custom Config Items
```python
from qfluentwidgets import QConfig, ConfigItem, RangeConfigItem, OptionsValidator, RangeValidator

class MyConfig(QConfig):
    opacity = ConfigItem("MainWindow", "Opacity", 0.9, RangeValidator(0.0, 1.0), restart=True)
    layout = OptionsConfigItem("MainWindow", "Layout", "Grid", OptionsValidator(["Grid", "List", "Dock"]))

cfg = MyConfig()
cfg.file = "my_app/config.json"      # default config/config.json
qconfig.load(file=cfg.file, config=cfg)   # load persisted values into cfg

cfg.set(cfg.opacity, 0.5)            # emits appRestartSig (restart=True), saves file
assert cfg.get(cfg.opacity) == 0.5
```

### Error Handling - Invalid Values
```python
cfg.set(cfg.layout, "Fullscreen")    # not in options -> corrects to first option "Grid"
assert qconfig.get(cfg.layout) == "Grid"
```

### Default File Location
The persisted file defaults to `config/config.json` relative to the current working directory.
```

--------------------------------

### ColorDialog usage example

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/dialog.md

Shows how to instantiate ColorDialog, connect its colorChanged signal, and execute it modally.

```python
w = ColorDialog(self.color, self.tr('Choose ')+self.title, self.window(), self.enableAlpha)
w.colorChanged.connect(self.__onColorChanged)
w.exec()
```

--------------------------------

### Install full-featured version for PyQt5

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/README.md

Use this command to install the full-featured version of PyQt-Fluent-Widgets, which includes the AcrylicLabel component. The [full] extra installs additional dependencies.

```shell
pip install "PyQt-Fluent-Widgets[full]" -i https://pypi.org/simple/
```

--------------------------------

### Full configuration flow example

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/configuration.md

Defines a QConfig subclass with various ConfigItem types, then loads, mutates, persists, and reads configuration. The 'restart=True' parameter on any item makes qconfig.set emit appRestartSig.

```python
from qfluentwidgets import (QConfig, ConfigItem, RangeConfigItem, OptionsConfigItem,
                            OptionsValidator, RangeValidator, EnumSerializer, BoolValidator)
from enum import Enum

class Accent(Enum):
    BLUE = "Blue"
    GREEN = "Green"

class AppConfig(QConfig):
    autoSave = ConfigItem("Editor", "AutoSave", True, BoolValidator())
    fontSize = RangeConfigItem("Editor", "FontSize", 14, RangeValidator(8, 48))
    accent = OptionsConfigItem("Editor", "Accent", Accent.BLUE, OptionsValidator(Accent), EnumSerializer(Accent))

appCfg = AppConfig()
appCfg.file = "config/app.json"
qconfig.load(file=appCfg.file, config=appCfg)      # hydrate from disk

qconfig.set(appCfg.accent, Accent.GREEN)            # -> saves config/app.json
print(qconfig.get(appCfg.fontSize))
```

--------------------------------

### Example JSON configuration format

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/configuration.md

Shows the JSON structure produced by QConfig.toDict(serialize=True), grouping attributes by their group key.

```json
{
    "QFluentWidgets": {
        "ThemeMode": "Light",
        "ThemeColor": "#009faa",
        "FontFamilies": ["Segoe UI", "Microsoft YaHei", "PingFang SC"]
    }
}
```

--------------------------------

### Basic FluentWindow app

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/window.md

Minimal example of a FluentWindow subclass with three sub-interfaces. Requires PyQt5 and qfluentwidgets. The window is resized to 800x600 and shown with app.exec().

```python
import sys
from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import QApplication, QWidget, QLabel
from qfluentwidgets import FluentWindow, FluentIcon, NavigationItemPosition, SplashScreen
from qfluentwidgets import FluentIcon as FIF

class Demo(FluentWindow):
    def __init__(self):
        super().__init__()
        self.resize(800, 600)

        self.home = QWidget(self); self.home.setObjectName("home")
        self.music = QWidget(self); self.music.setObjectName("music")
        self.settings = QWidget(self); self.settings.setObjectName("settings")

        self.addSubInterface(self.home, FIF.HOME, "Home")
        self.addSubInterface(self.music, FIF.MUSIC, "Music",
                             position=NavigationItemPosition.SCROLL)
        self.addSubInterface(self.settings, FIF.SETTING, "Settings",
                             position=NavigationItemPosition.BOTTOM)

app = QApplication(sys.argv)
window = Demo()
window.show()
app.exec()
```

--------------------------------

### Usage: Basic Setting Cards

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/settings.md

Example of creating setting cards bound to a QConfig and adding them to a SettingCardGroup.

```APIDOC
## Usage: Basic Setting Cards

### Description
Example of creating setting cards bound to a QConfig and adding them to a SettingCardGroup.

### Code Example
```python
from PyQt5.QtWidgets import QWidget
from qfluentwidgets import (qconfig, QConfig, ConfigItem, BoolValidator,
                            OptionsConfigItem, RangeConfigItem, OptionsValidator,
                            RangeValidator, SwitchSettingCard, RangeSettingCard,
                            OptionsSettingCard, SettingCardGroup, FluentIcon)

group = SettingCardGroup("General", self)

# define config items inside a QConfig subclass
class Cfg(QConfig):
    autoStart = ConfigItem("App", "AutoStart", False, BoolValidator())
    volume = RangeConfigItem("App", "Volume", 70, RangeValidator(0, 100))
    themeColor = OptionsConfigItem("App", "Accent", "Blue",
                                   OptionsValidator(["Blue", "Green", "Purple"]))
cfg = Cfg()

group.addSettingCard(SwitchSettingCard(FluentIcon.POWER_BUTTON, "Auto start",
                                       "Launch on boot", configItem=cfg.autoStart))
group.addSettingCard(RangeSettingCard(cfg.volume, FluentIcon.VOLUME, "Volume"))
group.addSettingCard(OptionsSettingCard(cfg.themeColor, FluentIcon.PALETTE, "Accent color",
                                        texts=["Blue", "Green", "Purple"]))
```

```

--------------------------------

### Basic qconfig usage: read and write theme and color

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/config.md

Basic usage example showing how to read and write theme and color settings using the global qconfig. qconfig.set updates the themeColorChanged signal and saves the config. The output comments show expected values.

```python
from PyQt5.QtWidgets import QApplication
from qfluentwidgets import qconfig, Theme, isDarkTheme, theme

app = QApplication([])

print(qconfig.get(qconfig.themeMode))        # Theme.LIGHT
qconfig.set(qconfig.themeColor, '#009faa')   # updates themeColorChanged, saves config
print(qconfig.get(qconfig.fontFamilies))     # ['Segoe UI', 'Microsoft YaHei', 'PingFang SC']
print(isDarkTheme(), theme())                # False Theme.LIGHT
```

--------------------------------

### TeachingTip.showEvent

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Handles the show event, starting the auto-dismiss timer and repositioning.

```APIDOC
## TeachingTip.showEvent

### Description
Event handler called when the tip is shown. Starts the auto-dismiss timer, repositions via manager, and fades in (167 ms).

### Method
Event handler

### Signature
```python
def showEvent(self, event)
```

### Parameters
- **event** (QShowEvent) - Required - The show event.

```

--------------------------------

### Install lite version for PyQt5

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/README.md

Use this command to install the lite version of PyQt-Fluent-Widgets for PyQt5. The lite version does not include the AcrylicLabel component.

```shell
pip install PyQt-Fluent-Widgets -i https://pypi.org/simple/
```

--------------------------------

### Theme switching and per-widget overrides

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Demonstrates switching the global theme with setTheme, applying a permanent light/dark overlay to a single widget with setCustomStyleSheet, and changing the theme color with setThemeColor. The example also shows how to retrieve the current theme color name.

```python
from qfluentwidgets import setTheme, Theme, setCustomStyleSheet, themeColor, setThemeColor
from PyQt5.QtGui import QColor

setTheme(Theme.DARK)                       # switches everything registered
setTheme(Theme.LIGHT, save=True)           # persists to config/config.json

# permanent light/dark overlay for a single widget:
setCustomStyleSheet(myWidget,
                    "QPushButton { color: black; }",   # light qss
                    "QPushButton { color: white; }")   # dark qss

print(themeColor().name())                 # e.g. #009faa
setThemeColor('#6a5acd')                   # changes the whole palette
```

--------------------------------

### TeachingTip.view property

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Gets or sets the view of the teaching tip.

```APIDOC
## TeachingTip.view property

### Description
Property to get or set the view of the teaching tip.

### Method
Property

### Signature
```python
view: FlyoutViewBase
```

### Usage
- Get: `tip.view`
- Set: `tip.view = new_view`

```

--------------------------------

### Using AcrylicFlyout, VideoWidget, DatePicker, and FlowLayout

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/material-multimedia.md

Shows how to use AcrylicFlyout, VideoWidget with StandardMediaPlayBar, DatePicker, and FlowLayout from qfluentwidgets. The video example creates a player and attaches a play bar; the date picker sets a specific date and prints changes; the flow layout adds two widgets.

```python
from PyQt5.QtCore import QUrl
from qfluentwidgets import (AcrylicFlyout, VideoWidget, MediaPlayer,
                            StandardMediaPlayBar, DatePicker, FlowLayout)

# acrylic flyout
AcrylicFlyout.create("Hello", "Acrylic content", target=button, parent=self)

# video with play bar
video = VideoWidget()
video.setVideo(QUrl.fromLocalFile("clip.mp4"))
player = video.player()
bar = StandardMediaPlayBar()
bar.setMediaPlayer(player)
bar.play()

# date picker
picker = DatePicker()
picker.dateChanged.connect(lambda d: print(d.toString("yyyy-MM-dd")))
import datetime
picker.setDate(datetime.date(2024, 3, 1))

# flow layout
flow = FlowLayout()
flow.addWidget(w1); flow.addWidget(w2)
```

--------------------------------

### Define StyleSheet class and apply to MainWindow

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/docs/source/theme.md

Inherit StyleSheetBase and override path() to return the QSS file path based on the current theme. The example shows a StyleSheet enum with MAIN_WINDOW and a MainWindow class that applies the style sheet in its constructor. The path() method uses qconfig.theme when theme is Theme.AUTO and constructs the path using the theme value and the enum value.

```python
from enum import Enum
from qfluentwidgets import StyleSheetBase, Theme, isDarkTheme, qconfig


class StyleSheet(StyleSheetBase, Enum):
    """ Style sheet  """

    MAIN_WINDOW = "main_window"

    def path(self, theme=Theme.AUTO):
        theme = qconfig.theme if theme == Theme.AUTO else theme
        return f"app/resource/qss/{theme.value.lower()}/{self.value}.qss"


class MainWindow(QWidget):

    def __init__(self, parent=None):
        super().__init__(parent=parent)

        # apply style sheet to main window
        StyleSheet.MAIN_WINDOW.apply(self)
```

--------------------------------

### TeachingTipView.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Constructs a TeachingTipView with title, content, optional icon and image, and tail position.

```APIDOC
## TeachingTipView.__init__

### Description
Initializes a TeachingTipView instance with the given title, content, optional icon and image, and tail position.

### Method
Constructor

### Signature
```python
def __init__(self, title: str, content: str, icon: Union[FluentIconBase, QIcon, str] = None,
             image: Union[str, QPixmap, QImage] = None, isClosable=True, tailPosition=TeachingTipTailPosition.BOTTOM,
             parent=None)
```

### Parameters
- **title** (str) - Required - The title text.
- **content** (str) - Required - The content text.
- **icon** (Union[FluentIconBase, QIcon, str]) - Optional - Icon to display.
- **image** (Union[str, QPixmap, QImage]) - Optional - Image to display.
- **isClosable** (bool) - Optional - Whether the view is closable.
- **tailPosition** (TeachingTipTailPosition) - Optional - Position of the tail.
- **parent** (QWidget) - Optional - Parent widget.

```

--------------------------------

### TeachingTip.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Constructs a TeachingTip widget with a view, target widget, duration, tail position, and parent.

```APIDOC
## TeachingTip.__init__

### Description
Initializes a TeachingTip widget with the given view, target widget, and display options.

### Method
Constructor

### Signature
```python
def __init__(self, view: FlyoutViewBase, target: QWidget, duration=1000,
             tailPosition=TeachingTipTailPosition.BOTTOM, parent=None, isDeleteOnClose=True)
```

### Parameters
- **view** (FlyoutViewBase) - Required - Bubble content.
- **target** (QWidget) - Required - Anchor widget.
- **duration** (int) - Optional - Display milliseconds; `< 0` never auto-dismisses. Default: `1000`.
- **tailPosition** (TeachingTipTailPosition) - Optional - Bubble tail orientation. Default: `BOTTOM`.
- **parent** (QWidget) - Optional - Parent window (resizing/moving repositions the tip). Default: `None`.
- **isDeleteOnClose** (bool) - Optional - `deleteLater()` on close. Default: `True`.

```

--------------------------------

### getStyleSheetFromFile(file: Union[str, QFile])

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Gets the style sheet from a QSS file.

```APIDOC
## getStyleSheetFromFile(file: Union[str, QFile])

### Description
Gets the style sheet from a QSS file.

### Parameters
- **file** (Union[str, QFile]) - Required - The path to the QSS file or a QFile object.

### Returns
- The style sheet string read from the file.
```

--------------------------------

### Top-level entry point qfluentwidgets/__init__.py

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/index.md

Shows the star import aggregator that re-exports all public symbols from subpackages.

```python
__version__ = "1.11.3"
__author__ = "zhiyiYo"

from .components import *
from .common import *
from .window import *
from ._rc import resource
```

--------------------------------

### PopupTeachingTip.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Constructs a PopupTeachingTip with a view, target, duration, tail position, and parent.

```APIDOC
## PopupTeachingTip.__init__

### Description
Initializes a PopupTeachingTip widget, using `Qt.Popup` window flags instead of `Qt.Tool`.

### Method
Constructor

### Signature
```python
def __init__(self, view: FlyoutViewBase, target: QWidget, duration=1000, tailPosition=..., parent=None, isDeleteOnClose=True)
```

### Parameters
- **view** (FlyoutViewBase) - Required - Bubble content.
- **target** (QWidget) - Required - Anchor widget.
- **duration** (int) - Optional - Display milliseconds; `< 0` never auto-dismisses. Default: `1000`.
- **tailPosition** (TeachingTipTailPosition) - Optional - Bubble tail orientation.
- **parent** (QWidget) - Optional - Parent window. Default: `None`.
- **isDeleteOnClose** (bool) - Optional - `deleteLater()` on close. Default: `True`.

```

--------------------------------

### QConfig.theme property

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/config.md

Gets or sets the current theme mode, resolving AUTO to the system theme.

```APIDOC
## QConfig.theme property

### Description
Getter returns the current theme. Setter maps `Theme.AUTO` to the system theme via `darkdetect.theme()` (fallback to `Theme.LIGHT`) and stores the resolved mode. Does not modify the config file.

### Method
`theme` property (getter/setter)

### Parameters (setter)
- **value** (Theme) - Required - The theme mode to set.

### Returns (getter)
- **Theme** - The current theme mode.

```

--------------------------------

### StyleSheetFile

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Represents a style sheet from a file path. Provides a method to get the file path.

```APIDOC
## StyleSheetFile

### Description
Represents a style sheet from a file path. Provides a method to get the file path.

### Constructor

#### __init__(path: str)
- **Parameters**: `path` (str) - Required - The file path of the style sheet.

### Methods

#### path()
- **Returns**: str - The file path of the style sheet.
```

--------------------------------

### Usage: Observing Changes

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/settings.md

Example of observing value changes on a setting card at the config item level.

```APIDOC
## Usage: Observing Changes

### Description
Example of observing value changes on a setting card at the config item level.

### Code Example
```python
from qfluentwidgets import ComboBoxSettingCard

card = ComboBoxSettingCard(cfg.themeColor, FluentIcon.PALETTE, "Accent",
                           texts=["Blue", "Green", "Purple"])
# all cards write through qconfig.set; observe at the item level:
cfg.themeColor.valueChanged.connect(lambda v: print("accent ->", v))
card.setValue("Green")
```

```

--------------------------------

### Load configuration file

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/configuration.md

Loads the default configuration file or a custom file with a custom QConfig subclass. Errors are silently ignored.

```python
qconfig.load()                  # loads the default file (errors silently ignored)
qconfig.load(file="settings.json", config=myConfig)   # custom file + custom QConfig subclass
```

--------------------------------

### FluentWindowBase.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/window.md

Initializes the base window with a horizontal layout, a stacked widget, and a navigation interface placeholder. The navigation interface is set to None and must be assigned by subclasses.

```python
def __init__(self, parent=None):
    self.hBoxLayout = QHBoxLayout(self)
    self.stackedWidget = StackedWidget(self)
    self.navigationInterface = None
```

--------------------------------

### InfoBadgeManager Constructor

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/info-bar-badge.md

Creates a manager that positions a badge relative to a target widget and installs a resize event filter.

```APIDOC
## InfoBadgeManager Constructor

### Description
Creates a manager that positions a badge relative to a target widget and installs a resize event filter.

### Method
Constructor

### Signature
```python
InfoBadgeManager(target: QWidget, badge: InfoBadge)
```

### Parameters
- **target** (QWidget) - Required - The target widget to which the badge is anchored.
- **badge** (InfoBadge) - Required - The badge to position.

### Usage Example
```python
manager = InfoBadgeManager(target_widget, badge)
```
```

--------------------------------

### ToolTip with Filter and Delay

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Installs a ToolTipFilter on a button to show a custom tooltip after a 500-millisecond delay, positioned at the bottom of the button.

```python
from qfluentwidgets import ToolTipFilter, ToolTipPosition

button.installEventFilter(ToolTipFilter(button, showDelay=500, position=ToolTipPosition.BOTTOM))
button.setToolTip("Custom tooltip text")
```

--------------------------------

### FolderListSettingCard.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/settings.md

Initializes a FolderListSettingCard, an ExpandSettingCard that shows configured folders as cards and emits a folderChanged signal when the list changes.

```APIDOC
## FolderListSettingCard.__init__

### Description
Initializes a FolderListSettingCard, an ExpandSettingCard that shows configured folders as cards and emits a folderChanged signal when the list changes.

### Method
Constructor

### Signature
```python
def __init__(self, icon: Union[str, QIcon, FluentIconBase], title, content=None, folderPaths: list = None, parent=None):
```

### Parameters
- **icon** (Union[str, QIcon, FluentIconBase]) - Required - The icon to display on the card.
- **title** - Required - The title text of the card.
- **content** - Optional - The content text of the card.
- **folderPaths** (list) - Optional - Initial list of folder paths to display.
- **parent** - Optional - The parent widget.

### Signals
- **folderChanged** (list) - Emitted when the folder list changes.

### Methods
- **addFolderCard(folderPath)** - Adds a folder card for the given path.
- **setValue(folderPaths: list)** - Writes the given folder paths to the config item.

```

--------------------------------

### AnimationBase

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/animation.md

Base class for animations that installs an event filter on a parent widget and forwards mouse events to overridable handlers.

```APIDOC
## AnimationBase

### Description
Base class for animations that installs an event filter on a parent widget and forwards mouse events to overridable handlers.

### Constructor
- `__init__(parent: QWidget)` - Installs an event filter on parent.

### Overridable Handlers
- `_onHover(e: QEnterEvent)` - Called on hover enter.
- `_onLeave(e)` - Called on leave.
- `_onPress(e: QMouseEvent)` - Called on mouse press.
- `_onRelease(e)` - Called on mouse release.

### Usage
Subclass and override the handlers to implement custom behavior.
```

--------------------------------

### getStyleSheet(source: Union[str, StyleSheetBase], theme=Theme.AUTO)

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Gets the style sheet; source may be a string path or a `StyleSheetBase` instance.

```APIDOC
## getStyleSheet(source: Union[str, StyleSheetBase], theme=Theme.AUTO)

### Description
Gets the style sheet; source may be a string path or a `StyleSheetBase` instance.

### Parameters
- **source** (Union[str, StyleSheetBase]) - Required - The source of the style sheet.
- **theme** (Theme) - Optional - The theme to use (default: `Theme.AUTO`).

### Returns
- The style sheet string.
```

--------------------------------

### TeachingTip classmethods make and create

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Classmethods to build and show a teaching tip. make() takes a view and target; create() takes target, title, content, and optional icon/image. Both accept duration, tail position, parent, and delete-on-close.

```python
@classmethod
def make(cls, view: FlyoutViewBase, target: QWidget, duration=1000, tailPosition=TeachingTipTailPosition.BOTTOM,
         parent=None, isDeleteOnClose=True):     # builds + show()

@classmethod
def create(cls, target: QWidget, title: str, content: str, icon: Union[FluentIconBase, QIcon, str] = None,
           image: Union[str, QPixmap, QImage] = None, isClosable=True, duration=1000,
           tailPosition=TeachingTipTailPosition.BOTTOM, parent=None, isDeleteOnClose=True):
```

--------------------------------

### CustomStyleSheet

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Manages per-widget custom style sheets for light and dark themes. Provides methods to set and get the custom QSS.

```APIDOC
## CustomStyleSheet

### Description
Manages per-widget custom style sheets for light and dark themes. Provides methods to set and get the custom QSS.

### Constructor

#### __init__(widget: QWidget)
- **Parameters**: `widget` (QWidget) - Required - The widget to associate with this custom style sheet.

### Methods

#### setCustomStyleSheet(lightQss, darkQss)
- **Parameters**: `lightQss` (str) - Required - The light theme QSS. `darkQss` (str) - Required - The dark theme QSS.
- **Returns**: self - Chainable.

#### setLightStyleSheet(qss)
- **Parameters**: `qss` (str) - Required - The light theme QSS.
- **Returns**: self - Chainable.

#### setDarkStyleSheet(qss)
- **Parameters**: `qss` (str) - Required - The dark theme QSS.
- **Returns**: self - Chainable.

#### lightStyleSheet()
- **Returns**: str - The light theme QSS.

#### darkStyleSheet()
- **Returns**: str - The dark theme QSS.

#### content(theme)
- **Parameters**: `theme` (Theme) - Required - The theme for which to get the content.
- **Returns**: str - The QSS content for the given theme.
```

--------------------------------

### StyleSheetBase

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Base class for style sheet sources. Provides methods to get the path, content, and apply the style sheet to a widget.

```APIDOC
## StyleSheetBase

### Description
Base class for style sheet sources. Provides methods to get the path, content, and apply the style sheet to a widget.

### Methods

#### path(theme=Theme.AUTO)
- **Parameters**: `theme` (Theme) - Optional - The theme for which to get the path. Defaults to `Theme.AUTO`.
- **Returns**: str - The path of the style sheet.
- **Raises**: `NotImplementedError` - If not overridden.

#### content(theme=Theme.AUTO)
- **Parameters**: `theme` (Theme) - Optional - The theme for which to get the content. Defaults to `Theme.AUTO`.
- **Returns**: str - The content of the style sheet, loaded from the file at `path(theme)`.

#### apply(widget: QWidget, theme=Theme.AUTO)
- **Parameters**: `widget` (QWidget) - Required - The widget to apply the style sheet to. `theme` (Theme) - Optional - The theme to use. Defaults to `Theme.AUTO`.
- **Returns**: None - Applies the style sheet to the widget.
```

--------------------------------

### NavigationInterface.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/navigation.md

Initializes the navigation interface with configurable options for menu button, return button, and collapsibility.

```APIDOC
## NavigationInterface.__init__

### Description
Initializes the navigation interface with configurable options for menu button, return button, and collapsibility.

### Method
Constructor

### Signature
```python
NavigationInterface(parent=None, showMenuButton=True, showReturnButton=False, collapsible=True)
```

### Parameters
- **parent** (QWidget) - Optional - parent widget
- **showMenuButton** (bool) - Optional - whether to show the expand/collapse menu button
- **showReturnButton** (bool) - Optional - whether to show the back (router pop) button
- **collapsible** (bool) - Optional - whether the interface can collapse to a compact strip
```

--------------------------------

### AnimationBase class definition

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/animation.md

Base class for animations that installs an event filter on the parent widget and forwards mouse events to overridable handlers.

```python
class AnimationBase(QObject):
    """ Animation base class """

    def __init__(self, parent: QWidget):
        # installs an event filter on parent; hook points _onHover/_onLeave/_onPress/_onRelease (all no-op by default)
```

--------------------------------

### QConfig.toDict(serialize=True)

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/config.md

Serializes all configuration items into a dictionary.

```APIDOC
## QConfig.toDict(serialize=True)

### Description
Walks class attributes of the config class and collects every `ConfigItem`, returning a dictionary mapping group names to item values (or directly to values for nameless items).

### Method
`toDict(self, serialize=True)`

### Parameters
- **serialize** (bool) - Optional - Whether to serialize values. Default: True.

### Returns
- **dict** - A dictionary of configuration items.

```

--------------------------------

### ToolTipFilter(QObject)

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

An event filter that automatically shows a ToolTip on hover after a delay, and takes care of hiding it on other events. It is installed on widgets via installEventFilter.

```APIDOC
## ToolTipFilter(QObject)

### Description
An event filter that manages showing a ToolTip on hover. It can be installed on any QWidget to provide custom tooltip behavior.

### Constructor
- `__init__(self, parent: QWidget, showDelay=300, position=ToolTipPosition.TOP)` - Creates a ToolTipFilter for the given parent widget with a show delay and position.

### Usage
- Install with `widget.installEventFilter(ToolTipFilter(widget))`.

### Method hooks
- `_canShowToolTip()` - Override to control whether the tooltip should be shown; default is `True`.
- `_createToolTip()` - Override to create a custom tooltip widget; the base class has an implementation.

### Behavior
- Shows a ToolTip after `showDelay` ms of hovering.
- Hides on leave, hide, or press events.
- Suppresses the native `QEvent.ToolTip`.

### Registered position managers
- `TopToolTipManager`, `BottomToolTipManager`, `LeftToolTipManager`, `RightToolTipManager`, `TopRightToolTipManager`, `TopLeftToolTipManager`, `BottomRightToolTipManager`, `BottomLeftToolTipManager`, `ItemViewToolTipManager(itemRect=QRect())`, `TableItemToolTipManager`.
```

--------------------------------

### Set up a TableView with a TableItemDelegate

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/widgets-core.md

Creates a TableView and assigns a TableItemDelegate to it, then sets the number of columns. Use this when you need a table view with a custom delegate for rendering or editing items.

```python
from qfluentwidgets import TableView, TableItemDelegate

table = TableView()
table.setItemDelegate(TableItemDelegate(table))
table.setColumnCount(2)
```

--------------------------------

### Checking acrylic availability with isAcrylicAvailable

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/material-multimedia.md

Checks if acrylic effects are available and prints a warning to install PyQt-Fluent-Widgets[full] if not. Use this before relying on acrylic components.

```python
from qfluentwidgets.components.widgets.acrylic_label import isAcrylicAvailable, checkAcrylicAvailability

if not isAcrylicAvailable:
    checkAcrylicAvailability()   # prints a warning to install PyQt-Fluent-Widgets[full]
```

--------------------------------

### Basic setting cards with QConfig

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/settings.md

Basic usage: create a SettingCardGroup, define a QConfig subclass with ConfigItem, RangeConfigItem, and OptionsConfigItem, then add SwitchSettingCard, RangeSettingCard, and OptionsSettingCard bound to those items.

```python
from PyQt5.QtWidgets import QWidget
from qfluentwidgets import (qconfig, QConfig, ConfigItem, BoolValidator,
                            OptionsConfigItem, RangeConfigItem, OptionsValidator,
                            RangeValidator, SwitchSettingCard, RangeSettingCard,
                            OptionsSettingCard, SettingCardGroup, FluentIcon)

group = SettingCardGroup("General", self)

# define config items inside a QConfig subclass
class Cfg(QConfig):
    autoStart = ConfigItem("App", "AutoStart", False, BoolValidator())
    volume = RangeConfigItem("App", "Volume", 70, RangeValidator(0, 100))
    themeColor = OptionsConfigItem("App", "Accent", "Blue",
                                   OptionsValidator(["Blue", "Green", "Purple"]))
cfg = Cfg()

group.addSettingCard(SwitchSettingCard(FluentIcon.POWER_BUTTON, "Auto start",
                                       "Launch on boot", configItem=cfg.autoStart))
group.addSettingCard(RangeSettingCard(cfg.volume, FluentIcon.VOLUME, "Volume"))
group.addSettingCard(OptionsSettingCard(cfg.themeColor, FluentIcon.PALETTE, "Accent color",
                                        texts=["Blue", "Green", "Purple"]))
```

--------------------------------

### AcrylicWidget mixin class

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/material-multimedia.md

Base mixin for acrylic widgets. Requires the [full] install for AcrylicBrush (scipy-based gaussian blur); degrades gracefully when gaussianBlur cannot be imported.

```python
class AcrylicWidget:
    """ Acrylic widget mixin """

    def __init__(self, *args, **kwargs):
        # creates self.acrylicBrush = AcrylicBrush(self, blurRadius)
        # installs _blurThread (BlurCoverThread)

    def acrylicClipPath(self):
        """ return the clip path of the acrylic area """
        raise NotImplementedError

    def _updateClipPath(self) -> None ...
    def paintEvent(self, e): ...
```

--------------------------------

### TeachingTip.make

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/flyout-tip.md

Classmethod that builds a TeachingTip and shows it.

```APIDOC
## TeachingTip.make

### Description
Classmethod that constructs a TeachingTip with the given view and target, then shows it.

### Method
Classmethod

### Signature
```python
@classmethod
def make(cls, view: FlyoutViewBase, target: QWidget, duration=1000, tailPosition=TeachingTipTailPosition.BOTTOM,
         parent=None, isDeleteOnClose=True)
```

### Parameters
- **view** (FlyoutViewBase) - Required - Bubble content.
- **target** (QWidget) - Required - Anchor widget.
- **duration** (int) - Optional - Display milliseconds; `< 0` never auto-dismisses. Default: `1000`.
- **tailPosition** (TeachingTipTailPosition) - Optional - Bubble tail orientation. Default: `BOTTOM`.
- **parent** (QWidget) - Optional - Parent window. Default: `None`.
- **isDeleteOnClose** (bool) - Optional - `deleteLater()` on close. Default: `True`.

```

--------------------------------

### Smooth scrolling and animations

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/animation.md

Shows how to create a SmoothScroll with COSINE mode and a FluentAnimation with FAST_INVOKE type and OPACITY property. The animation is started with a duration of 0.3 seconds.

```python
from qfluentwidgets import SmoothScroll, SmoothMode, FluentAnimation, FluentAnimationType, FluentAnimationProperty, FluentAnimationSpeed

scroll = SmoothScroll(myScrollArea, dynamicEngineEnabled=True)
scroll.setSmoothMode(SmoothMode.COSINE)

ani = FluentAnimation.create(
    FluentAnimationType.FAST_INVOKE,
    FluentAnimationProperty.OPACITY,
    speed=FluentAnimationSpeed.FAST,
    value=1.0,
    parent=myWidget,
)
ani.startAnimation(0.3)
```

--------------------------------

### SmoothScrollArea.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/widgets-core.md

Initializes a SmoothScrollArea with smooth scrolling.

```APIDOC
## SmoothScrollArea.__init__

### Description
Initializes a SmoothScrollArea with smooth scrolling.

### Method
Constructor

### Parameters
- **parent** (QWidget) - Optional - Parent widget.

### Request Example
```python
area = SmoothScrollArea(parent)
```
```

--------------------------------

### setValue with invalid option

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/settings.md

Error handling example: setValue ignores values not present in optionToText, so passing an invalid option is silently ignored without exception or change.

```python
card.setValue("NotAnOption")   # ignored silently (no exception, no change)
```

--------------------------------

### Create global qconfig singleton

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/configuration.md

Instantiate the global QConfig object at import time. All widgets, style sheets, and theme APIs read and write through this singleton.

```python
qconfig = QConfig()
```

--------------------------------

### getIconColor(theme, reverse) - get icon color based on theme

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/icon.md

Returns 'black' or 'white' based on the theme. When reverse=True, the mapping is swapped. Theme.AUTO consults isDarkTheme().

```python
def getIconColor(theme=Theme.AUTO, reverse=False):
    """ get the color of icon based on theme """
```

--------------------------------

### QConfig.load(file=None, config=None)

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/config.md

Loads configuration from a JSON file and applies it to the config items.

```APIDOC
## QConfig.load(file=None, config=None)

### Description
Reads a JSON file and deserializes values into matching configuration items. Optionally bridges the `themeChanged` signal from another `QConfig` instance. Falls back to an empty dict on read failure.

### Method
`load(self, file=None, config=None)`

### Parameters
- **file** (str or Path) - Optional - Path to the JSON file to load.
- **config** (QConfig) - Optional - Another QConfig instance whose `themeChanged` signal is bridged.

### Returns
None.

```

--------------------------------

### ColoredFluentIcon.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/icon.md

Initializes a ColoredFluentIcon with a base icon and light/dark colors.

```APIDOC
## ColoredFluentIcon.__init__

### Description
Initializes a ColoredFluentIcon with a base icon and light/dark colors.

### Method
Constructor

### Signature
python
def __init__(self, icon: FluentIconBase, lightColor, darkColor):


### Parameters
- **icon** (FluentIconBase) - Required - The base icon to color.
- **lightColor** (QColor) - Required - The color used in light theme.
- **darkColor** (QColor) - Required - The color used in dark theme.
```

--------------------------------

### Invalid config value correction

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/config.md

Error handling example: setting an invalid value for an OptionsConfigItem does not raise an error but corrects it to the first option. The assertion confirms the corrected value.

```python
cfg.set(cfg.layout, "Fullscreen")    # not in options -> corrects to first option "Grid"
assert qconfig.get(cfg.layout) == "Grid"
```

--------------------------------

### Icon.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/icon.md

Constructor for the `Icon` class, which wraps a `FluentIcon` into a theme-aware `QIcon`.

```APIDOC
## `Icon`

```python
class Icon(QIcon):

    def __init__(self, fluentIcon: FluentIcon):
        super().__init__(fluentIcon.path())
        self.fluentIcon = fluentIcon
```

### Description
Creates a theme-aware `QIcon` from a `FluentIcon` enum member. The icon is loaded from the fluent icon's path and the original `FluentIcon` is stored for later theme updates.

### Parameters
- **fluentIcon** (`FluentIcon`) - Required - The fluent icon enum member to convert to a `QIcon`.

### Returns
- `Icon` - A `QIcon` subclass that holds the fluent icon reference.
```

--------------------------------

### FluentIconBase

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/icon.md

Abstract base (protocol) for theme-aware icons. Provides methods to get the icon path, create QIcon, create colored icons, convert to QIcon, and render the icon.

```APIDOC
## FluentIconBase

### Description
Abstract base (protocol) for theme-aware icons.

### Methods

#### path(self, theme=Theme.AUTO) -> str
Gets the path of the icon. Theme: Light: black, DARK: white, AUTO: depends on config.theme.

#### icon(self, theme=Theme.AUTO, color: QColor = None) -> QIcon
Creates a fluent icon. `color` only applicable to svg icon. If `path` ends with `.svg` and `color` is given, it writes `fill=QColor(color).name()` into the SVG and returns a `SvgIconEngine`-backed `QIcon`; otherwise `QIcon(self.path(theme))`.

#### colored(self, lightColor: QColor, darkColor: QColor) -> "ColoredFluentIcon"
Creates a colored fluent icon.

#### qicon(self, reverse=False) -> QIcon
Converts to QIcon, theme updated synchronously with app (FluentIconEngine).

#### render(self, painter, rect, theme=Theme.AUTO, indexes=None, **attributes)
Draws svg icon.
```

--------------------------------

### FluentWindowBase.switchTo

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/window.md

Switches the stacked widget to the given interface with a short 300 ms transition.

```APIDOC
## switchTo(self, interface: QWidget)

### Description
Sets the stacked widget's current widget to the given interface with a short 300 ms transition.

### Method
switchTo

### Parameters
- **interface** (QWidget) - Required - The interface widget to switch to.

### Response
No return value.
```

--------------------------------

### StyleSheetManager class definition

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Defines the StyleSheetManager QObject that manages style sheet composition per widget using a weak-key dictionary. The manager registers sources, installs event filters, and provides methods for deregistration and retrieval.

```python
class StyleSheetManager(QObject):
    """ Style sheet manager """

    def __init__(self):
        self.widgets = weakref.WeakKeyDictionary()   # widget -> StyleSheetCompose
```

--------------------------------

### Render QSS with theme color variables

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/style-sheet.md

Shows how renderQss substitutes known theme color variables in a QSS string while leaving unknown variables verbatim. The example uses --ThemeColorPrimary (substituted) and --NotARealVar (preserved).

```python
qss = """
QWidget { background: --ThemeColorPrimary; border: 1px solid --NotARealVar; }
"""
print(renderQss(qss))   # --ThemeColorPrimary substituted; --NotARealVar preserved
```

--------------------------------

### CustomMenuStyle.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/menu.md

Initializes a CustomMenuStyle with a specified icon size, adjusting the PM_SmallIconSize style metric accordingly.

```APIDOC
## CustomMenuStyle.__init__

### Description
Initializes a CustomMenuStyle instance that adjusts the PM_SmallIconSize style metric to the given icon size.

### Method
Constructor

### Signature
```python
def __init__(self, iconSize=14)
```

### Parameters
- **iconSize** (int) - Optional - The desired small icon size in pixels. Defaults to 14.
```

--------------------------------

### Fluent window with grouped navigation

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/navigation.md

Creates a FluentWindow subclass with multiple pages added via addSubInterface. The example shows how to set object names (required) and add a nested item using the parentRouteKey parameter. This is the basic usage for integrating with FluentWindow.

```python
from PyQt5.QtWidgets import QWidget
from qfluentwidgets import FluentWindow, FluentIcon, NavigationItemPosition

class Demo(FluentWindow):
    def __init__(self):
        super().__init__()
        self.setObjectName("demo")

        for name in ["home", "folder", "album", "settings"]:
            page = QWidget(self)
            page.setObjectName(name)          # required
            self.addSubInterface(page, FluentIcon[name.upper()] if name != "folder" else FluentIcon.FOLDER, name)

        # tree (nested) item using parentRouteKey
        self.settings = QWidget(self); self.settings.setObjectName("settings")
        self.advanced = QWidget(self); self.advanced.setObjectName("advanced")
        self.addSubInterface(self.settings, FluentIcon.SETTING, "Settings")
        self.addSubInterface(self.advanced, FluentIcon.DEVELOPER_TOOLS, "Advanced", parent="settings")
```

--------------------------------

### ExpandSettingCard.__init__

Source: https://github.com/zhiyiyo/pyqt-fluent-widgets/blob/master/_autodocs/api-reference/settings.md

Initializes an ExpandSettingCard with an icon, title, optional content, and parent. The card is collapsible with a header and a view layout revealed by an arrow button.

```APIDOC
## ExpandSettingCard.__init__

### Description
Initializes an ExpandSettingCard with an icon, title, optional content, and parent. The card is collapsible with a header and a view layout revealed by an arrow button.

### Signature
```python
def __init__(self, icon: Union[str, QIcon, FIF], title: str, content: str = None, parent=None):
```

### Parameters
- **icon** (Union[str, QIcon, FIF]) - Required - The icon to display on the card header.
- **title** (str) - Required - The title of the card.
- **content** (str) - Optional - The content or subtitle of the card.
- **parent** (QWidget) - Optional - The parent widget.

### Public Methods
- **addWidget(widget)** - Adds a widget to the view layout.
- **setExpand(isExpand)** - Expands or collapses the card.
- **toggleExpand()** - Toggles the expanded state.
- **setValue(value)** - Sets the value of the card.

```
Tokens:
Raw