0
# Settings and Configuration
1

2
Setting cards, configuration management, and option panels for building preference interfaces with validation and persistence. These components provide a modern approach to application settings with fluent design integration.
3

4
## Capabilities
5

6
### Setting Cards
7

8
Pre-built setting cards for common configuration options with automatic validation and fluent design styling.
9

10
```python { .api }
11
class SettingCard(QWidget):
12
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], title: str, content: str = None, parent=None): ...
13
    def setTitle(self, title: str): ...
14
    def setContent(self, content: str): ...
15
    def setValue(self, value): ...
16
    def value(self): ...
17

18
class SwitchSettingCard(SettingCard):
19
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], title: str, content: str = None, 
20
                 configItem: ConfigItem = None, parent=None): ...
21
    def setChecked(self, checked: bool): ...
22
    def isChecked(self) -> bool: ...
23
    
24
    checkedChanged = pyqtSignal(bool)
25

26
class ComboBoxSettingCard(SettingCard):
27
    def __init__(self, configItem: ConfigItem, icon: Union[FluentIconBase, QIcon, str], 
28
                 title: str, content: str = None, texts: List[str] = None, parent=None): ...
29
    def setCurrentIndex(self, index: int): ...
30
    def setCurrentText(self, text: str): ...
31
    def currentIndex(self) -> int: ...
32
    def currentText(self) -> str: ...
33

34
class RangeSettingCard(SettingCard):
35
    def __init__(self, configItem: ConfigItem, icon: Union[FluentIconBase, QIcon, str],
36
                 title: str, content: str = None, parent=None): ...
37
    def setRange(self, min: int, max: int): ...
38
    def setValue(self, value: int): ...
39
    def value(self) -> int: ...
40
```
41

42
**Usage Example:**
43
```python
44
from qfluentwidgets import (SwitchSettingCard, ComboBoxSettingCard, RangeSettingCard, 
45
                           FluentIcon as FIF, ConfigItem, qconfig)
46

47
# Switch setting
48
auto_save_card = SwitchSettingCard(
49
    FIF.SAVE,
50
    "Auto Save",
51
    "Automatically save documents every 5 minutes"
52
)
53
auto_save_card.setChecked(True)
54
auto_save_card.checkedChanged.connect(self.on_auto_save_changed)
55

56
# Combo box setting
57
theme_card = ComboBoxSettingCard(
58
    qconfig.theme,  # Config item
59
    FIF.BRUSH,
60
    "Theme",
61
    "Choose the application theme",
62
    texts=["Light", "Dark", "Auto"]
63
)
64
theme_card.setCurrentText("Auto")
65

66
# Range setting
67
volume_card = RangeSettingCard(
68
    qconfig.volume,
69
    FIF.VOLUME,
70
    "Volume",
71
    "Adjust the application volume"
72
)
73
volume_card.setRange(0, 100)
74
volume_card.setValue(75)
75
```
76

77
### Advanced Setting Cards
78

79
Specialized setting cards for complex configuration options.
80

81
```python { .api }
82
class PushSettingCard(SettingCard):
83
    def __init__(self, text: str, icon: Union[FluentIconBase, QIcon, str], 
84
                 title: str, content: str = None, parent=None): ...
85
    def setButtonText(self, text: str): ...
86
    def buttonText(self) -> str: ...
87
    
88
    clicked = pyqtSignal()
89

90
class ColorSettingCard(SettingCard):
91
    def __init__(self, configItem: ConfigItem, icon: Union[FluentIconBase, QIcon, str],
92
                 title: str, content: str = None, enableAlpha: bool = False, parent=None): ...
93
    def setColor(self, color: QColor): ...
94
    def color(self) -> QColor: ...
95
    
96
    colorChanged = pyqtSignal(QColor)
97

98
class HyperlinkCard(SettingCard):
99
    def __init__(self, url: str, text: str, icon: Union[FluentIconBase, QIcon, str],
100
                 title: str, content: str = None, parent=None): ...
101
    def setUrl(self, url: str): ...
102
    def setText(self, text: str): ...
103

104
class ExpandSettingCard(SettingCard):
105
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], title: str, content: str = None, parent=None): ...
106
    def addWidget(self, widget: QWidget): ...
107
    def setExpanded(self, expanded: bool): ...
108
    def isExpanded(self) -> bool: ...
109
    
110
    expandedChanged = pyqtSignal(bool)
111
```
112

113
**Usage Example:**
114
```python
115
from qfluentwidgets import (PushSettingCard, ColorSettingCard, HyperlinkCard, 
116
                           ExpandSettingCard, FluentIcon as FIF)
117

118
# Button setting card
119
export_card = PushSettingCard(
120
    "Export Settings",
121
    FIF.SHARE,
122
    "Export Configuration",
123
    "Export your settings to a file"
124
)
125
export_card.clicked.connect(self.export_settings)
126

127
# Color setting card
128
accent_card = ColorSettingCard(
129
    qconfig.themeColor,
130
    FIF.PALETTE,
131
    "Accent Color",
132
    "Choose your preferred accent color",
133
    enableAlpha=False
134
)
135
accent_card.colorChanged.connect(self.on_accent_color_changed)
136

137
# Hyperlink card
138
docs_card = HyperlinkCard(
139
    "https://docs.example.com",
140
    "View Documentation",
141
    FIF.DOCUMENT,
142
    "Help & Support",
143
    "Access online documentation and tutorials"
144
)
145

146
# Expandable setting card
147
advanced_card = ExpandSettingCard(
148
    FIF.DEVELOPER_TOOLS,
149
    "Advanced Settings",
150
    "Configure advanced options"
151
)
152

153
# Add widgets to expandable card
154
debug_switch = SwitchSettingCard(FIF.BUG, "Debug Mode", "Enable debug logging")
155
cache_button = PushSettingCard("Clear Cache", FIF.DELETE, "Cache", "Clear application cache")
156

157
advanced_card.addWidget(debug_switch)
158
advanced_card.addWidget(cache_button)
159
```
160

161
### Setting Card Groups
162

163
Containers for organizing related setting cards with proper spacing and grouping.
164

165
```python { .api }
166
class SettingCardGroup(QWidget):
167
    def __init__(self, title: str, parent=None): ...
168
    def addSettingCard(self, card: SettingCard): ...
169
    def addSettingCards(self, cards: List[SettingCard]): ...
170
    def setTitle(self, title: str): ...
171
    def title(self) -> str: ...
172
```
173

174
**Usage Example:**
175
```python
176
from qfluentwidgets import SettingCardGroup
177

178
# Create setting groups
179
appearance_group = SettingCardGroup("Appearance", self)
180
appearance_group.addSettingCard(theme_card)
181
appearance_group.addSettingCard(accent_card)
182

183
behavior_group = SettingCardGroup("Behavior", self)
184
behavior_group.addSettingCard(auto_save_card)
185
behavior_group.addSettingCard(volume_card)
186

187
advanced_group = SettingCardGroup("Advanced", self)
188
advanced_group.addSettingCard(advanced_card)
189
advanced_group.addSettingCard(export_card)
190

191
# Layout groups in settings interface
192
settings_layout = QVBoxLayout()
193
settings_layout.addWidget(appearance_group)
194
settings_layout.addWidget(behavior_group)
195
settings_layout.addWidget(advanced_group)
196
```
197

198
### Configuration System
199

200
Robust configuration management with validation, serialization, and automatic persistence.
201

202
```python { .api }
203
class QConfig(QObject):
204
    def __init__(self): ...
205
    def get(self, item: ConfigItem): ...
206
    def set(self, item: ConfigItem, value, save: bool = True): ...
207
    def save(self): ...
208
    def load(self, file: str = None): ...
209
    
210
    configChanged = pyqtSignal(ConfigItem, object)
211

212
class ConfigItem:
213
    def __init__(self, group: str, name: str, default, validator: ConfigValidator = None, 
214
                 serializer: ConfigSerializer = None, restart: bool = False): ...
215
    def value(self): ...
216
    def setValue(self, value): ...
217

218
class RangeConfigItem(ConfigItem):
219
    def __init__(self, group: str, name: str, default: Union[int, float], 
220
                 range: Tuple[Union[int, float], Union[int, float]], validator: ConfigValidator = None): ...
221

222
class OptionsConfigItem(ConfigItem):
223
    def __init__(self, group: str, name: str, default, options: List, validator: ConfigValidator = None): ...
224

225
class ColorConfigItem(ConfigItem):
226
    def __init__(self, group: str, name: str, default: QColor, validator: ConfigValidator = None): ...
227
```
228

229
**Usage Example:**
230
```python
231
from qfluentwidgets import QConfig, ConfigItem, RangeConfigItem, OptionsConfigItem, ColorConfigItem
232

233
# Create global config instance
234
qconfig = QConfig()
235

236
# Define configuration items
237
class Config:
238
    # Basic config items
239
    auto_save = ConfigItem("General", "AutoSave", True)
240
    language = OptionsConfigItem("General", "Language", "English", ["English", "Spanish", "French"])
241
    
242
    # Range config
243
    volume = RangeConfigItem("Audio", "Volume", 75, (0, 100))
244
    
245
    # Color config
246
    theme_color = ColorConfigItem("Theme", "AccentColor", QColor(0, 120, 212))
247

248
# Register with global config
249
for item in [Config.auto_save, Config.language, Config.volume, Config.theme_color]:
250
    qconfig.addConfigItem(item)
251

252
# Load configuration
253
qconfig.load("config.json")
254

255
# Use configuration values
256
if qconfig.get(Config.auto_save):
257
    self.enable_auto_save()
258

259
# React to changes
260
qconfig.configChanged.connect(self.on_config_changed)
261

262
def on_config_changed(self, item, value):
263
    if item == Config.theme_color:
264
        self.update_theme_color(value)
265
```
266

267
### Configuration Validators
268

269
Input validation for configuration values with custom validation logic.
270

271
```python { .api }
272
class ConfigValidator:
273
    def validate(self, value) -> bool: ...
274
    def correct(self, value): ...
275

276
class RangeValidator(ConfigValidator):
277
    def __init__(self, min_value: Union[int, float], max_value: Union[int, float]): ...
278

279
class OptionsValidator(ConfigValidator):
280
    def __init__(self, options: List): ...
281

282
class BoolValidator(ConfigValidator): ...
283

284
class FolderValidator(ConfigValidator): ...
285

286
class FolderListValidator(ConfigValidator): ...
287

288
class ColorValidator(ConfigValidator): ...
289
```
290

291
**Usage Example:**
292
```python
293
from qfluentwidgets import RangeValidator, OptionsValidator, ColorValidator
294

295
# Custom validator
296
class EmailValidator(ConfigValidator):
297
    def validate(self, value):
298
        return "@" in str(value) and "." in str(value).split("@")[-1]
299
    
300
    def correct(self, value):
301
        if not self.validate(value):
302
            return "user@example.com"
303
        return value
304

305
# Configuration with validation
306
email_config = ConfigItem(
307
    "User", 
308
    "Email", 
309
    "user@example.com", 
310
    validator=EmailValidator()
311
)
312

313
# Range validation
314
volume_config = RangeConfigItem(
315
    "Audio", 
316
    "Volume", 
317
    50, 
318
    (0, 100),
319
    validator=RangeValidator(0, 100)
320
)
321

322
# Options validation
323
theme_config = OptionsConfigItem(
324
    "Appearance",
325
    "Theme",
326
    "Auto",
327
    ["Light", "Dark", "Auto"],
328
    validator=OptionsValidator(["Light", "Dark", "Auto"])
329
)
330
```
331

332
### Configuration Serializers
333

334
Custom serialization for complex configuration data types.
335

336
```python { .api }
337
class ConfigSerializer:
338
    def serialize(self, value) -> str: ...
339
    def deserialize(self, value: str): ...
340

341
class EnumSerializer(ConfigSerializer):
342
    def __init__(self, enum_class): ...
343

344
class ColorSerializer(ConfigSerializer): ...
345
```
346

347
**Usage Example:**
348
```python
349
from qfluentwidgets import EnumSerializer, ColorSerializer
350
from enum import Enum
351

352
# Enum serialization
353
class Priority(Enum):
354
    LOW = 1
355
    MEDIUM = 2
356
    HIGH = 3
357

358
priority_config = ConfigItem(
359
    "Tasks",
360
    "DefaultPriority", 
361
    Priority.MEDIUM,
362
    serializer=EnumSerializer(Priority)
363
)
364

365
# Color serialization
366
color_config = ConfigItem(
367
    "Theme",
368
    "AccentColor",
369
    QColor(0, 120, 212),
370
    serializer=ColorSerializer()
371
)
372

373
# Custom serializer
374
class ListSerializer(ConfigSerializer):
375
    def serialize(self, value):
376
        return ",".join(str(v) for v in value)
377
    
378
    def deserialize(self, value):
379
        return [item.strip() for item in value.split(",") if item.strip()]
380

381
favorites_config = ConfigItem(
382
    "User",
383
    "FavoriteFolders",
384
    ["/home/user/Documents", "/home/user/Pictures"],
385
    serializer=ListSerializer()
386
)
387
```
388

389
## Complete Settings Interface Example
390

391
```python
392
from qfluentwidgets import *
393

394
class SettingsInterface(QWidget):
395
    def __init__(self, parent=None):
396
        super().__init__(parent)
397
        self.setupUi()
398
        self.connectSignals()
399
    
400
    def setupUi(self):
401
        # Main layout
402
        layout = QVBoxLayout(self)
403
        
404
        # Title
405
        title = LargeTitleLabel("Settings")
406
        layout.addWidget(title)
407
        
408
        # Scroll area for settings
409
        scroll = SmoothScrollArea(self)
410
        scroll_widget = QWidget()
411
        scroll_layout = QVBoxLayout(scroll_widget)
412
        
413
        # General settings group
414
        general_group = SettingCardGroup("General")
415
        
416
        self.auto_save_card = SwitchSettingCard(
417
            FIF.SAVE, "Auto Save", "Automatically save changes"
418
        )
419
        self.language_card = ComboBoxSettingCard(
420
            None, FIF.LOCALE, "Language", "Select interface language",
421
            texts=["English", "Spanish", "French", "German"]
422
        )
423
        
424
        general_group.addSettingCards([self.auto_save_card, self.language_card])
425
        
426
        # Appearance settings group
427
        appearance_group = SettingCardGroup("Appearance")
428
        
429
        self.theme_card = ComboBoxSettingCard(
430
            None, FIF.BRUSH, "Theme", "Choose application theme",
431
            texts=["Light", "Dark", "Auto"]
432
        )
433
        self.accent_card = ColorSettingCard(
434
            None, FIF.PALETTE, "Accent Color", "Personalize your accent color"
435
        )
436
        
437
        appearance_group.addSettingCards([self.theme_card, self.accent_card])
438
        
439
        # Advanced settings group
440
        advanced_group = SettingCardGroup("Advanced")
441
        
442
        self.debug_card = SwitchSettingCard(
443
            FIF.DEVELOPER_TOOLS, "Debug Mode", "Enable debugging features"
444
        )
445
        self.export_card = PushSettingCard(
446
            "Export", FIF.SHARE, "Export Settings", "Save settings to file"
447
        )
448
        
449
        advanced_group.addSettingCards([self.debug_card, self.export_card])
450
        
451
        # Add groups to layout
452
        scroll_layout.addWidget(general_group)
453
        scroll_layout.addWidget(appearance_group)
454
        scroll_layout.addWidget(advanced_group)
455
        scroll_layout.addStretch()
456
        
457
        scroll.setWidget(scroll_widget)
458
        layout.addWidget(scroll)
459
    
460
    def connectSignals(self):
461
        self.auto_save_card.checkedChanged.connect(self.on_auto_save_changed)
462
        self.language_card.currentTextChanged.connect(self.on_language_changed)
463
        self.theme_card.currentTextChanged.connect(self.on_theme_changed)
464
        self.accent_card.colorChanged.connect(self.on_accent_changed)
465
        self.export_card.clicked.connect(self.export_settings)
466
    
467
    def on_auto_save_changed(self, checked):
468
        qconfig.set(Config.auto_save, checked)
469
    
470
    def on_language_changed(self, language):
471
        qconfig.set(Config.language, language)
472
    
473
    def on_theme_changed(self, theme):
474
        theme_enum = Theme.LIGHT if theme == "Light" else Theme.DARK if theme == "Dark" else Theme.AUTO
475
        setTheme(theme_enum)
476
    
477
    def on_accent_changed(self, color):
478
        setThemeColor(color)
479
    
480
    def export_settings(self):
481
        file_path, _ = QFileDialog.getSaveFileName(self, "Export Settings", "", "JSON files (*.json)")
482
        if file_path:
483
            qconfig.save(file_path)
484
```