From 1da767ff0ad1109eaa645718faeced129c1f0439 Mon Sep 17 00:00:00 2001 From: James Graham Date: Sat, 15 Apr 2023 17:18:33 +0000 Subject: [PATCH] Document roomlistmodel --- src/models/roomlistmodel.cpp | 44 ++++++----- src/models/roomlistmodel.h | 134 ++++++++++++++++++++++++--------- src/qml/Page/RoomList/Page.qml | 2 +- 3 files changed, 125 insertions(+), 55 deletions(-) diff --git a/src/models/roomlistmodel.cpp b/src/models/roomlistmodel.cpp index dfbed4a7a..f82d2c33f 100644 --- a/src/models/roomlistmodel.cpp +++ b/src/models/roomlistmodel.cpp @@ -69,6 +69,11 @@ RoomListModel::RoomListModel(QObject *parent) RoomListModel::~RoomListModel() = default; +Quotient::Connection *RoomListModel::connection() const +{ + return m_connection; +} + void RoomListModel::setConnection(Connection *connection) { if (connection == m_connection) { @@ -237,6 +242,11 @@ void RoomListModel::handleNotifications() } #endif +int RoomListModel::notificationCount() const +{ + return m_notificationCount; +} + void RoomListModel::refreshNotificationCount() { int count = 0; @@ -440,40 +450,40 @@ QHash RoomListModel::roleNames() const return roles; } -QString RoomListModel::categoryName(int section) +QString RoomListModel::categoryName(int category) { - switch (section) { - case 1: + switch (category) { + case NeoChatRoomType::Invited: return i18n("Invited"); - case 2: + case NeoChatRoomType::Favorite: return i18n("Favorite"); - case 3: + case NeoChatRoomType::Direct: return i18n("Direct Messages"); - case 4: + case NeoChatRoomType::Normal: return i18n("Normal"); - case 5: + case NeoChatRoomType::Deprioritized: return i18n("Low priority"); - case 6: + case NeoChatRoomType::Space: return i18n("Spaces"); default: return "Deadbeef"; } } -QString RoomListModel::categoryIconName(int section) +QString RoomListModel::categoryIconName(int category) { - switch (section) { - case 1: + switch (category) { + case NeoChatRoomType::Invited: return QStringLiteral("user-invisible"); - case 2: + case NeoChatRoomType::Favorite: return QStringLiteral("favorite"); - case 3: + case NeoChatRoomType::Direct: return QStringLiteral("dialog-messages"); - case 4: + case NeoChatRoomType::Normal: return QStringLiteral("group"); - case 5: + case NeoChatRoomType::Deprioritized: return QStringLiteral("object-order-lower"); - case 6: + case NeoChatRoomType::Space: return QStringLiteral("group"); default: return QStringLiteral("tools-report-bug"); @@ -511,7 +521,7 @@ NeoChatRoom *RoomListModel::roomByAliasOrId(const QString &aliasOrId) return nullptr; } -int RoomListModel::indexForRoom(NeoChatRoom *room) const +int RoomListModel::rowForRoom(NeoChatRoom *room) const { return m_rooms.indexOf(room); } diff --git a/src/models/roomlistmodel.h b/src/models/roomlistmodel.h index 2b65ae25a..6ee1f1fd4 100644 --- a/src/models/roomlistmodel.h +++ b/src/models/roomlistmodel.h @@ -20,77 +20,137 @@ class NeoChatRoomType : public QObject Q_OBJECT public: + /** + * @brief Defines the room list categories a room can be assigned. + */ enum Types { - Invited = 1, - Favorite, - Direct, - Normal, - Deprioritized, - Space, + Invited = 1, /**< The user has been invited to the room. */ + Favorite, /**< The room is set as a favourite. */ + Direct, /**< The room is a direct chat. */ + Normal, /**< The default category for a joined room. */ + Deprioritized, /**< The room is set as low priority. */ + Space, /**< The room is a space. */ }; Q_ENUM(Types) }; +/** + * @class RoomListModel + * + * This class defines the model for visualising the user's list of joined rooms. + */ class RoomListModel : public QAbstractListModel { Q_OBJECT + + /** + * @brief The current connection that the model is getting its rooms from. + */ Q_PROPERTY(Quotient::Connection *connection READ connection WRITE setConnection NOTIFY connectionChanged) + + /** + * @brief The total number of notifications for all the rooms. + */ Q_PROPERTY(int notificationCount READ notificationCount NOTIFY notificationCountChanged) public: + /** + * @brief Defines the model roles. + */ enum EventRoles { - NameRole = Qt::UserRole + 1, - DisplayNameRole, - AvatarRole, - CanonicalAliasRole, - TopicRole, - CategoryRole, - UnreadCountRole, - NotificationCountRole, - HighlightCountRole, - LastEventRole, - LastActiveTimeRole, - JoinStateRole, - CurrentRoomRole, - CategoryVisibleRole, - SubtitleTextRole, - AvatarImageRole, - IdRole, - IsSpaceRole, + NameRole = Qt::UserRole + 1, /**< The name of the room. */ + DisplayNameRole, /**< The display name of the room. */ + AvatarRole, /**< The source URL for the room's avatar. */ + CanonicalAliasRole, /**< The room canonical alias. */ + TopicRole, /**< The room topic. */ + CategoryRole, /**< The room category, e.g favourite. */ + UnreadCountRole, /**< The number of unread messages in the room. */ + NotificationCountRole, /**< The number of notifications in the room. */ + HighlightCountRole, /**< The number of highlighted messages in the room. */ + LastEventRole, /**< Text for the last event in the room. */ + LastActiveTimeRole, /**< The timestamp of the last event sent in the room. */ + JoinStateRole, /**< The local user's join state in the room. */ + CurrentRoomRole, /**< The room object for the room. */ + CategoryVisibleRole, /**< If the room's category is visible. */ + SubtitleTextRole, /**< The text to show as the room subtitle. */ + AvatarImageRole, /**< The room avatar as an image. */ + IdRole, /**< The room matrix ID. */ + IsSpaceRole, /**< Whether the room is a space. */ }; Q_ENUM(EventRoles) RoomListModel(QObject *parent = nullptr); ~RoomListModel() override; - [[nodiscard]] Quotient::Connection *connection() const - { - return m_connection; - } + [[nodiscard]] Quotient::Connection *connection() const; void setConnection(Quotient::Connection *connection); - void doResetModel(); - Q_INVOKABLE [[nodiscard]] NeoChatRoom *roomAt(int row) const; + [[nodiscard]] int notificationCount() const; + /** + * @brief Get the given role value at the given index. + * + * @sa QAbstractItemModel::data + */ [[nodiscard]] QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override; + + /** + * @brief Number of rows in the model. + * + * @sa QAbstractItemModel::rowCount + */ Q_INVOKABLE [[nodiscard]] int rowCount(const QModelIndex &parent = QModelIndex()) const override; + /** + * @brief Returns a mapping from Role enum values to role names. + * + * @sa EventRoles, QAbstractItemModel::roleNames() + */ [[nodiscard]] QHash roleNames() const override; - Q_INVOKABLE [[nodiscard]] static QString categoryName(int section); - Q_INVOKABLE [[nodiscard]] static QString categoryIconName(int section); + /** + * @brief Return the room at the given row. + */ + Q_INVOKABLE [[nodiscard]] NeoChatRoom *roomAt(int row) const; + + /** + * @brief Return a string to represent the given room category. + */ + Q_INVOKABLE [[nodiscard]] static QString categoryName(int category); + + /** + * @brief Return a string with the name of the given room category icon. + */ + Q_INVOKABLE [[nodiscard]] static QString categoryIconName(int category); + + /** + * @brief Set whether a given category should be visible or not. + * + * @param category the NeoChatRoomType::Types value for the category (it's an + * int due to the pain of Q_INVOKABLES and cpp enums). + * @param visible true if the category should be visible, false if not. + */ Q_INVOKABLE void setCategoryVisible(int category, bool visible); + + /** + * @brief Return whether a room category is set to be visible. + */ Q_INVOKABLE [[nodiscard]] bool categoryVisible(int category) const; - Q_INVOKABLE [[nodiscard]] int indexForRoom(NeoChatRoom *room) const; - [[nodiscard]] int notificationCount() const - { - return m_notificationCount; - } + /** + * @brief Return the model row for the given room. + */ + Q_INVOKABLE [[nodiscard]] int rowForRoom(NeoChatRoom *room) const; + /** + * @brief Return a room for the given room alias or room matrix ID. + * + * The room must be in the model. + */ Q_INVOKABLE NeoChatRoom *roomByAliasOrId(const QString &aliasOrId); private Q_SLOTS: + void doResetModel(); void doAddRoom(Quotient::Room *room); void updateRoom(Quotient::Room *room, Quotient::Room *prev); void deleteRoom(Quotient::Room *room); diff --git a/src/qml/Page/RoomList/Page.qml b/src/qml/Page/RoomList/Page.qml index fe5b634fe..28ffdfefe 100644 --- a/src/qml/Page/RoomList/Page.qml +++ b/src/qml/Page/RoomList/Page.qml @@ -58,7 +58,7 @@ Kirigami.ScrollablePage { Connections { target: RoomManager function onCurrentRoomChanged() { - itemSelection.setCurrentIndex(roomListModel.index(roomListModel.indexForRoom(RoomManager.currentRoom), 0), ItemSelectionModel.SelectCurrent) + itemSelection.setCurrentIndex(roomListModel.index(roomListModel.rowForRoom(RoomManager.currentRoom), 0), ItemSelectionModel.SelectCurrent) } }