QML & UI Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The HX-Music client utilizes a C++/Qt and QML architecture to provide a high-performance, visually rich music player interface. The system integrates C++ logic controllers and data models with QML-based presentation layers, specifically optimized for rendering complex ASS karaoke subtitles and managing a modern music library.
The architecture relies on the QQmlApplicationEngine to load QML modules and exposes C++ singletons and models to the QML context for real-time interaction.
Sources: HX-Music-Client/README.md:1-25, HX-Music-Client/src/main.cpp:115-180
Core UI Components and Controllers
The application bridges C++ backend logic to the QML frontend by registering controllers and models as context properties or QML types. This allows QML components to invoke C++ methods and react to property changes.
Controller Registration
Key controllers manage specific domains of the UI, such as music playback, playlist management, and user authentication.
- UserController: Handles login, registration, and user session state.
- MusicController: Manages playback state, volume, and current track position.
- PlaylistController: Controls playlist CRUD operations and track ordering.
- LyricController: Manages ASS lyric rendering and provides images to the UI via a custom
QQuickImageProvider.
Sources: HX-Music-Client/src/main.cpp:106-140
Logic to UI Flow
The following diagram illustrates how the MusicClient initializes and bridges C++ components to the QML environment.
Sources: HX-Music-Client/src/main.cpp:92-192
Data Models for UI Lists
HX-Music uses the QAbstractListModel interface to provide data to QML ListView components. These models handle large datasets, such as the global music library, by implementing lazy loading.
AllMusicListModel
This model manages the display of all songs available in the system. It uses MusicApi::selectMusic to fetch songs in chunks and exposes them to QML via specific roles.
| Role | Data Type | Description |
|---|---|---|
title | QString | The display title of the music track. |
artist | QStringList | List of singers/artists for the track. |
album | QString | The name of the music album. |
duration | QString | Track length in milliseconds (string format). |
id | QString | Unique identifier for server-side operations. |
Sources: HX-Music-Client/include/model/AllMusicListModel.hpp:34-75
Lazy Loading Logic
The loadMoreRequested() function facilitates pagination, ensuring the UI remains responsive when browsing large libraries.
Theme and Visual Configuration
The Theme class provides a centralized management system for UI colors and background assets. It utilizes C++ macros to generate QML-accessible properties and persists changes to a JSON configuration file.
Theme Properties
| Property | Default Value | Usage |
|---|---|---|
textColor | #ffffff | Primary text for labels and titles. |
paratextColor | #b3b3b3 | Secondary/dimmed text. |
highlightingColor | #ff13ff | Active states and highlighting. |
backgroundColor | #12121298 | Main container background (semi-transparent). |
backgroundImgUrl | qrc:/img/background.jpg | Active background image path. |
Sources: HX-Music-Client/include/config/Theme.hpp:95-108
Persistence Logic
The Theme constructor reads from themeConfig.json upon initialization, while the destructor writes current values back to the file to ensure settings persist across sessions.
Sources: HX-Music-Client/include/config/Theme.hpp:67-93
Dynamic Asset Rendering
The application utilizes custom QQuickImageProvider implementations to handle dynamic assets that cannot be served as static files.
Colored SVG Provider
The QmlSvgPars class allows QML to request SVG icons with dynamic color tinting. By using the image://svgColored/ prefix, the UI can specify a path and a hex color code.
Request Format: image://svgColored/qrc:/icons/next.svg?color=#ff0000
Sources: HX-Music-Client/include/utils/SvgPars.hpp:97-129
Image Provider Workflow
Windowing and Wayland Support
The client implements specific architectural choices to handle the limitations of the Wayland protocol, particularly regarding window positioning and layering for floating lyrics.
- WindowMaskUtil: Registered as a context property to manage window transparency and interaction masks.
- Floating Windows: Use
Qt.ToolTipflags to bypass taskbar icons and tab-switching, which is a specific workaround for Wayland systems. - System Rules: The application expects specific KDE Plasma window rules (defined in
README.md) to force "Above" status for Wayland windows, as programmatic positioning is restricted.
Sources: HX-Music-Client/README.md:35-55, HX-Music-Client/src/main.cpp:103-104
Summary
The HX-Music UI architecture effectively separates presentation from logic through a robust C++ backplane and a flexible QML frontend. By utilizing custom image providers and pagination-enabled models, the system handles complex visual tasks—like dynamic SVG coloring and floating ASS lyric rendering—while maintaining library responsiveness. Persistence is handled via JSON-backed theme and configuration singletons that synchronize state between the application lifecycle and the filesystem.