Application Status Management
Relevant source files
The following files were used as context for generating this wiki page:
The Application Status Management system in SSA Consulta Rapida Cpp provides a centralized mechanism for tracking, updating, and displaying the operational state of the application. It primarily focuses on communicating the progress of asynchronous data queries, reporting errors encountered during background operations, and providing textual feedback to the user regarding the current dataset (e.g., record counts and pagination info).
This system is implemented through a decoupled architecture where the StatusViewModel acts as a specialized state container, while the MainViewModel orchestrates high-level operations and updates the status based on the lifecycle of data requests.
Sources: src/presentation/StatusViewModel.h, src/presentation/MainViewModel.cpp:218-258
Component Architecture
The status management architecture follows a reactive pattern using Qt's property system. The StatusViewModel exposes properties that the QML layer observes to update the UI (such as status pills or progress indicators).
Core Components
| Component | Responsibility |
|---|---|
StatusViewModel | Holds the raw state: a message string, an error string, and a loading boolean. |
MainViewModel | The primary controller that updates status during query execution and preferences saving. |
QFutureWatcher | Used within MainViewModel to monitor asynchronous tasks and trigger status updates upon completion or failure. |
Sources: src/presentation/StatusViewModel.h:11-15, src/presentation/MainViewModel.h:110-112, src/presentation/MainViewModel.cpp:218-245
Class Relationships
The following diagram illustrates how the Status system is integrated into the presentation layer:
Data Flow and State Transitions
Status updates are typically triggered by asynchronous operations. The MainViewModel manages a requestGeneration_ counter to ensure that status updates from stale (canceled or superseded) requests do not affect the UI.
Query Lifecycle Flow
When a user applies a filter or navigates pages, the following flow occurs:
Request Cancellation
The system supports explicit cancellation. When cancelCurrentRequest() is called, the request generation is incremented, the loading state is immediately cleared, and a specific "Consulta cancelada" (Query canceled) message is displayed.
Sources: src/presentation/MainViewModel.cpp:213-217, tests/smoke/PresentationSmokeTest.cpp:149-160
Implementation Details
Status Properties
The StatusViewModel provides three primary properties via Q_PROPERTY for QML integration:
- message: A general informative string (e.g., "Pronto", "Consultando dados...").
- error: Specifically holds technical error details when an operation fails.
- loading: A boolean indicating if a background task is currently active.
Sources: src/presentation/StatusViewModel.h:11-15
Thread Safety and Asynchronicity
Status updates are handled on the main thread through Qt's signal/slot mechanism. MainViewModel uses QtConcurrent::run to perform heavy lifting (like SQL queries or writing JSON preferences) and uses QFutureWatcher to receive notifications.
// Example of status update during async preference saving
connect(watcher, &QFutureWatcher<bool>::finished, this, [this, watcher] {
try {
watcher->result();
} catch (const std::exception& exc) {
status_.setError(QString::fromUtf8(exc.what()));
status_.setMessage("Falha ao salvar preferencias");
}
// ...
});
Sources: src/presentation/MainViewModel.cpp:322-330
Summary
The Application Status Management system ensures that the user is always aware of the application's internal state. By encapsulating state in StatusViewModel and utilizing request generation tracking in MainViewModel, the application maintains a consistent and responsive UI even during complex asynchronous database operations.
Sources: src/presentation/StatusViewModel.cpp, src/presentation/MainViewModel.cpp:218-258