Client State Management
Relevant source files
The following files were used as context for generating this wiki page:
Client State Management in HX-Music coordinates the persistence of user preferences, playback status, and UI configuration. The system uses a centralized singleton architecture to manage application-wide data and ensures synchronization between the C++ backend and the QML user interface.
Architecture Overview
The architecture relies on specialized Singletons and Model classes to handle different aspects of the application state. The GlobalSingleton acts as the primary container for persistent configurations, while the SignalBusSingleton manages asynchronous communication across the client.
Core Components
| Component | Description | File Path |
|---|---|---|
GlobalSingleton | Stores persistent music, lyric, and server configurations. | GlobalSingleton.hpp |
SignalBusSingleton | Provides a centralized hub for QML-accessible signals. | SignalBusSingleton.h |
ConfigManager | Handles JSON serialization and file I/O for settings. | ConfigManager.hpp |
AllMusicListModel | Manages the state of the music library view and pagination. | AllMusicListModel.hpp |
Sources: GlobalSingleton.hpp, SignalBusSingleton.h, ConfigManager.hpp
Persistent Configuration State
The client maintains state across sessions by serializing data structures into hxMusicConfig.json. This includes playback progress, volume, and UI preferences.
Configuration Data Structures
The system defines specific structures to categorize state data:
- MusicConfig: Tracks
volume,playMode, currentposition, and activeplaylistId. - LyricConfig: Stores window coordinates (
windowX,windowY), dimensions, and lock status for the floating lyric window. - Theme: Manages UI aesthetics, including text colors and background image URLs.
Sources: HX-Music-Client/README.md:143-205, ConfigManager.hpp:46-68
State Persistence Flow
The ConfigManager class implements the logic for saving and loading these structures.
The application triggers a save operation during the aboutToQuit signal in the main execution block.
Sources: HX-Music-Client/src/main.cpp:166-171, ConfigManager.hpp:35-44
UI and Signal Management
HX-Music utilizes a "Signal Bus" to decouple state changes from UI updates. The SignalBusSingleton exposes Qt signals that QML components monitor to react to state transitions.
Key Managed Signals
The signal bus manages events including, but not limited to:
listIndexChanged(): Notifies the UI when the active track in a playlist changes.loginSucceed(): Triggers UI transitions after successful authentication.lyricsConfigChanged(): Updates the rendering parameters for ASS subtitles.
Sources: SignalBusSingleton.h:35-60, AllMusicListModel.hpp:94-98
Data Model State
State regarding the music library and upload queues is managed via QAbstractListModel implementations. These models maintain an in-memory representation of server data and handle incremental loading.
Music Library State
The AllMusicListModel manages the "All Music" view state using pagination. It tracks the _beginId to request the next block of 10 songs from the server.
Initialization and Teardown
The MusicClient struct in main.cpp coordinates the lifecycle of state-managed components.
- Check Instance: Ensures only one client instance runs by attempting to connect to a
QLocalServer. - Load Configuration: The
loadConfig()method populatesGlobalSingletonfrom the local JSON file. - Register Contexts: Components like
MusicController,UserController, andThemeare set as QML context properties. - Teardown: On quit, the client captures the final
musicControllerposition and saves all configurations.
Sources: HX-Music-Client/src/main.cpp:45-165, ConfigManager.hpp:51-68
Client State Management ensures a consistent user experience by centralizing configuration in singletons, utilizing a signal bus for UI reactivity, and persisting session data to local storage during teardown.