SSA Data Table Model

Relevant source files

The following files were used as context for generating this wiki page:

• src/presentation/SsaTableModel.h
• src/presentation/SsaTableModel.cpp
• src/domain/SsaTypes.h
• src/presentation/MainViewModel.h
• src/presentation/MainViewModel.cpp
• src/infra/sqlite/SqliteSsaRepository.cpp
• src/presentation/ColumnSettingsModel.h

The SSA Data Table Model is a core component of the presentation layer, responsible for managing and providing data to the user interface's tabular display. It implements the QAbstractTableModel interface to bridge the gap between domain-specific service records (SsaRecord) and the Qt Quick/QML view components.

Architecture and Design

The model is designed around the principles of asynchronous data loading and dynamic column management. It does not store the entire database in memory; instead, it holds only the current "page" of results requested by the user.

Key Components

Component	Responsibility
SsaTableModel	Inherits from QAbstractTableModel. Manages the internal buffer of rows and column definitions.
SsaRecord	A domain structure representing a single row, mapping column keys to their string values.
SsaPageResult	A container for a collection of records along with pagination metadata (total rows, current index).
MainViewModel	The orchestrator that triggers searches and updates the SsaTableModel when new data arrives.

Sources: src/presentation/SsaTableModel.h:15-18, src/domain/SsaTypes.h:112-120

Data Structure Relationship

The following diagram illustrates the relationship between the table model, the domain types it consumes, and the ViewModel that controls it:

Data Flow and Updates

The update cycle of the table model is reactive. When a user changes a search term or navigates to a different page, the MainViewModel initiates an asynchronous request through the SsaQueryService.

Update Sequence

1. Request Initiation: MainViewModel::runRequest is called with an SsaPageRequest.
2. Background Processing: The search is executed on a background thread using QtConcurrent::run.
3. Model Reset: Upon completion, SsaTableModel::setPage is invoked.
4. View Notification: The model calls beginResetModel() and endResetModel(), forcing the QML View to refresh its content.

Column and Layout Management

The model supports dynamic column visibility and custom widths, which are often derived from user preferences stored in a JSON file.

Column Resolution Logic

The model resolves column metadata (labels and widths) by looking up keys in the ColumnCatalog. If a custom width has been set by the user (and stored in columnWidths_), it takes precedence over the catalog's default width.

• Display Role: Returns the value from the SsaRecord corresponding to the column key.
• Header Data: Provides labels (e.g., "SSA", "Situação") for the horizontal header.
• Column Width: Calculated via columnWidth(int column), returning either a custom preference, a catalog default, or a fallback value of 132 pixels.

Sources: src/presentation/SsaTableModel.cpp:22-44, src/presentation/SsaTableModel.cpp:84-100

Property Summary

Property / Method	Return Type	Description
rowCount	int	Number of records in the current page.
columnCount	int	Number of currently visible columns.
visibleColumnCount	int	QML-accessible count of visible columns.
columnKey(int)	QString	Retrieves the internal database key for a specific column index.
columnLabel(int)	QString	Retrieves the human-readable label for a specific column.

Sources: src/presentation/SsaTableModel.h:23-33, src/presentation/SsaTableModel.cpp:73-82

Implementation Details

Data Retrieval Snippet

The following implementation shows how the model extracts data for the QML view. It relies on the SsaRecord::valueOf method to fetch values by string keys.

// src/presentation/SsaTableModel.cpp:22-38
QVariant SsaTableModel::data(const QModelIndex& index, const int role) const {
    if (!index.isValid() || role != Qt::DisplayRole) {
        return {};
    }
    const int column = index.column();
    const auto* record = recordAt(index.row());
    if (record == nullptr || column < 0) {
        return {};
    }
    const auto columnIndex = static_cast<std::size_t>(column);
    if (columnIndex >= columns_.size()) {
        return {};
    }
    return QString::fromStdString(record->valueOf(columns_[columnIndex]));
}

Record Selection

When a row is selected in the UI, MainViewModel::selectRow identifies the record at that index and passes it to the DetailsViewModel for a full-screen or side-panel view.

Sources: src/presentation/MainViewModel.cpp:202-208, src/presentation/SsaTableModel.cpp:102-110

Conclusion

The SsaTableModel provides a performant and flexible way to display SSA data. By decoupling the presentation logic from the underlying SQL queries and domain objects, it allows for seamless UI updates, dynamic column customization, and efficient memory usage through pagination.

Sources: src/presentation/SsaTableModel.cpp, src/presentation/MainViewModel.cpp