UI services and widgets¶
UI orchestration services and reusable widget containers.
📡 Theme signal integration¶
EzQt_App emits themeChanged whenever the active theme is switched via
the settings panel flow (set_app_theme() / refresh_theme()).
Use this signal to refresh custom widgets that keep theme-dependent caches outside standard QSS repaint behavior.
from ezqt_app import EzQt_App
window = EzQt_App().build()
def on_theme_changed() -> None:
# Recompute theme-dependent resources in custom components.
...
window.themeChanged.connect(on_theme_changed)
📦 ThemeService¶
Service responsible for loading and applying QSS themes.
Theme variables are declared without prefix in theme config files
(e.g. main_surface) and referenced in QSS files using the
standard CSS custom property notation var(--variable_name).
The service resolves each reference to its palette value before
applying the stylesheet.
staticmethod
¶
Load all QSS files from the themes directory and apply the merged stylesheet.
All .qss files found under <app_root>/bin/themes/ are loaded in
alphabetical order and concatenated before palette variables are resolved.
When that directory is absent or empty, the package's own
resources/themes/ directory is used as fallback.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
window
|
MainWindowProtocol
|
The application window whose |
required |
staticmethod
¶
Return available theme options as (display_label, internal_value) pairs.
Reads palette keys from theme.config.yaml and generates one entry
per preset × variant combination, e.g.
("Blue Gray - Dark", "blue_gray:dark").
Returns:
| Type | Description |
|---|---|
list[tuple[str, str]]
|
List of |
📦 MenuService¶
Service responsible for menu item selection state and style refresh.
📦 PanelService¶
📦 WindowService¶
📦 UiComponentFactory¶
Bases: UiComponentFactoryProtocol
Factory that exposes predefined UI component specifications.
Initialize the factory.
Return a predefined size policy specification by name.
📦 Core widgets¶
Bases: QApplication
Extended main application with theme and UTF-8 encoding support.
This class inherits from QApplication and adds functionality for theme management and UTF-8 encoding.
Initialize the application with UTF-8 and high resolution support.
Parameters¶
args : Any Positional arguments passed to QApplication. *kwargs : Any Keyword arguments passed to QApplication.
classmethod
¶
create_for_testing(*args: Any, **kwargs: Any) -> EzApplication
Create an EzApplication instance for testing, bypassing singleton checks.
Header(app_name: str = '', description: str = '', parent: QWidget | None = None, *args: Any, **kwargs: Any)
Bases: QFrame
Application header with logo, name and control buttons.
This class provides a customizable header bar with the application logo, its name, description and window control buttons (minimize, maximize, close).
Initialize the application header.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
app_name
|
str
|
Application name (default: ""). |
''
|
description
|
str
|
Application description (default: ""). |
''
|
parent
|
QWidget | None
|
The parent widget (default: None). |
None
|
*args
|
Any
|
Additional positional arguments. |
()
|
**kwargs
|
Any
|
Additional keyword arguments. |
{}
|
Set the application name in the header.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
app_name
|
str
|
The new application name. |
required |
Set the application description in the header.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
description
|
str
|
The new application description. |
required |
Apply current translations to all owned text labels and tooltips.
Handle Qt change events, triggering UI retranslation on language change.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
QEvent
|
The QEvent instance. |
required |
Set the application logo in the header.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
logo
|
str | QPixmap
|
The logo to display (file path or QPixmap). |
required |
y_shrink
|
int
|
Vertical reduction of the logo (default: 0). |
0
|
y_offset
|
int
|
Vertical offset of the logo (default: 0). |
0
|
Update the open dynamic property on the settings button.
The property is used by QSS to apply an accent background when the settings panel is visible. Calling this method forces Qt to re-evaluate the style rules for the button immediately.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
is_open
|
bool
|
|
required |
Update all button icons according to current theme.
Bases: QFrame
Menu container with expansion/reduction support.
This class provides a menu container with a toggle button to expand or reduce the menu width. The menu contains an upper section for menu items and a lower section for the toggle button.
Initialize the menu container.
Parameters¶
parent : QWidget, optional The parent widget (default: None). shrink_width : int, optional Width when menu is shrunk (default: 60). extended_width : int, optional Width when menu is extended (default: 240).
Bases: QFrame
Page container with stacked widget management.
This class provides a container to manage multiple pages within a central receptacle using a QStackedWidget.
Initialize the page container.
Parameters¶
parent : QWidget, optional The parent widget (default: None).
Bases: QFrame
This class is used to create a settings panel. It contains a top border, a content settings frame and a theme settings container. The settings panel is used to display the settings.
Add a setting based on its YAML configuration.
add_toggle_setting(key: str, label: str, default: bool = False, description: str = '', enabled: bool = True)
Add a toggle setting.
add_select_setting(key: str, label: str, options: list[str], default: str | None = None, description: str = '', enabled: bool = True)
Add a selection setting.
add_slider_setting(key: str, label: str, min_val: int, max_val: int, default: int, unit: str = '', description: str = '', enabled: bool = True)
Add a slider setting.
add_text_setting(key: str, label: str, default: str = '', description: str = '', enabled: bool = True)
Add a text setting.
add_checkbox_setting(key: str, label: str, default: bool = False, description: str = '', enabled: bool = True)
Add a checkbox setting.
Update theme icons for all widgets that support it.
Add a new setting widget to the settings panel.
Add a new settings section with optional title.
Scroll to a specific widget in the settings panel.
📦 Extended widgets¶
Setting widget components: toggle, select, slider, text, checkbox.