diff --git a/libcockatrice_card/libcockatrice/card/set/card_set.h b/libcockatrice_card/libcockatrice/card/set/card_set.h index 5967f9093..36db09892 100644 --- a/libcockatrice_card/libcockatrice/card/set/card_set.h +++ b/libcockatrice_card/libcockatrice/card/set/card_set.h @@ -13,31 +13,65 @@ using CardInfoPtr = QSharedPointer; class CardSet; using CardSetPtr = QSharedPointer; +/** + * @class CardSet + * @ingroup Cards + * + * @brief A collection of cards grouped under a common identifier. + * + * A set serves both as metadata (identifier, title, category, release date, and priority) + * and as a container of all cards that belong to it. Each set can be enabled/disabled + * and marked as known/unknown depending on context. + * + * The class inherits from `QList`, so it can be iterated over directly + * to access its contents. + * + * Typical usage: + * - Query metadata such as identifier, category, or release date. + * - Enable or disable sets according to user preference. + * - Store and retrieve CardInfo objects associated with the set. + */ class CardSet : public QList { public: + /** + * @enum Priority + * @brief Defines relative ordering and importance of sets. + */ enum Priority { - PriorityFallback = 0, - PriorityPrimary = 10, - PrioritySecondary = 20, - PriorityReprint = 30, - PriorityOther = 40, - PriorityLowest = 100, + PriorityFallback = 0, ///< Used when no other priority is defined. + PriorityPrimary = 10, ///< Primary, canonical set. + PrioritySecondary = 20, ///< Secondary but relevant. + PriorityReprint = 30, ///< Duplicate or reprint category. + PriorityOther = 40, ///< Miscellaneous grouping. + PriorityLowest = 100, ///< Lowest sorting priority. }; - static const char *TOKENS_SETNAME; + static const char *TOKENS_SETNAME; ///< Reserved identifier for token-like sets. private: - QSharedPointer priorityController; - QString shortName, longName; - unsigned int sortKey; - QDate releaseDate; - QString setType; - Priority priority; - bool enabled, isknown; + QSharedPointer priorityController; ///< Interface to the card set priority controller. + QString shortName; ///< Short identifier for the set. + QString longName; ///< Full name for the set. + unsigned int sortKey; ///< Custom numeric sort key. + QDate releaseDate; ///< Release date, may be empty if unknown. + QString setType; ///< Type/category label for the set. + Priority priority; ///< Priority level for sorting and relevance. + bool enabled; ///< Whether the set is active/enabled. + bool isknown; ///< Whether the set is considered known. public: + /** + * @brief Constructs a CardSet. + * + * @param priorityController Interface to a card set priority controller. + * @param _shortName Identifier string. + * @param _longName Full descriptive name. + * @param _setType Type/category string. + * @param _releaseDate Release date (optional). + * @param _priority Sorting/priority level. + */ explicit CardSet(ICardSetPriorityController *priorityController, const QString &_shortName = QString(), const QString &_longName = QString(), @@ -45,6 +79,17 @@ public: const QDate &_releaseDate = QDate(), const Priority _priority = PriorityFallback); + /** + * @brief Creates and returns a new shared CardSet instance. + * + * @param priorityController Interface to a card set priority controller. + * @param _shortName Identifier string. + * @param _longName Full descriptive name. + * @param _setType Type/category string. + * @param _releaseDate Release date (optional). + * @param _priority Sorting/priority level. + * @return A shared pointer to the new CardSet. + */ static CardSetPtr newInstance(ICardSetPriorityController *priorityController, const QString &_shortName = QString(), const QString &_longName = QString(), @@ -52,65 +97,131 @@ public: const QDate &_releaseDate = QDate(), const Priority _priority = PriorityFallback); + /** + * @brief Returns a safe, sanitized version of the short name. + * + * Intended for file paths or identifiers where only certain + * characters are allowed. + * + * @return Sanitized short name. + */ QString getCorrectedShortName() const; + /// @return Short identifier of the set. QString getShortName() const { return shortName; } + + /// @return Descriptive name of the set. QString getLongName() const { return longName; } + + /// @return Type/category string of the set. QString getSetType() const { return setType; } + + /// @return Release date of the set. QDate getReleaseDate() const { return releaseDate; } + + /// @return Priority level of the set. Priority getPriority() const { return priority; } + /** + * @brief Sets the full name of the set. + * @param _longName New full name. + */ void setLongName(const QString &_longName) { longName = _longName; } + + /** + * @brief Sets the category/type of the set. + * @param _setType New category string. + */ void setSetType(const QString &_setType) { setType = _setType; } + + /** + * @brief Sets the release date of the set. + * @param _releaseDate New release date. + */ void setReleaseDate(const QDate &_releaseDate) { releaseDate = _releaseDate; } + + /** + * @brief Updates the priority of the set. + * @param _priority New priority value. + */ + void setPriority(const Priority _priority) { priority = _priority; } + /** + * @brief Loads state values (enabled, known, sort key) from configuration. + * + * Reads external configuration and applies it to this set. + */ void loadSetOptions(); + + /// @return The sort key assigned to this set. int getSortKey() const { return sortKey; } + + /** + * @brief Assigns a new sort key to this set. + * @param _sortKey The numeric key to use for sorting. + */ void setSortKey(unsigned int _sortKey); + /// @return True if the set is enabled. bool getEnabled() const { return enabled; } + + /** + * @brief Enables or disables the set. + * @param _enabled True to enable, false to disable. + */ void setEnabled(bool _enabled); + /// @return True if the set is considered known. bool getIsKnown() const { return isknown; } + + /** + * @brief Marks the set as known or unknown. + * @param _isknown True if known, false if unknown. + */ void setIsKnown(bool _isknown); + /** + * @brief Determines whether the set has incomplete metadata and should be ignored. + * + * @return True if the long name, type, and release date are all empty. + */ bool getIsKnownIgnored() const { return longName.length() + setType.length() + releaseDate.toString().length() == 0; diff --git a/libcockatrice_card/libcockatrice/card/set/card_set_list.h b/libcockatrice_card/libcockatrice/card/set/card_set_list.h index af1bb365b..2e644a277 100644 --- a/libcockatrice_card/libcockatrice/card/set/card_set_list.h +++ b/libcockatrice_card/libcockatrice/card/set/card_set_list.h @@ -6,20 +6,97 @@ #include #include +/** + * @class CardSetList + * @ingroup Cards + * + * @brief A list-like container for CardSet objects with extended management methods. + * + * Extends `QList` by adding convenience operations for sorting, + * enabling/disabling sets, and tracking known/unknown status. Unlike a plain + * list, this container provides domain-specific functionality for handling + * groups of sets in bulk. + */ class CardSetList : public QList { private: + /** + * @class KeyCompareFunctor + * @brief Internal comparison functor for sorting by sort key. + * + * Used internally by `sortByKey()` to order sets consistently + * according to their assigned numeric sort keys. + */ class KeyCompareFunctor; public: + /** + * @brief Sorts the set list by each set’s assigned sort key. + * + * Uses KeyCompareFunctor internally. If two sets share the + * same sort key, their relative order is unspecified. + */ void sortByKey(); + + /** + * @brief Reassigns sort keys based on the current order. + * + * Calls defaultSort() and then assigns sequential sort keys + * to all sets according to their resulting positions, replacing + * any existing sort keys to ensure consistent ordering. + */ void guessSortKeys(); + + /** + * @brief Enables all sets that are unknown or ignored. + * + * Sets that are not marked as known and not ignored are marked as known + * and enabled. Ignored-known sets are also enabled, but remain ignored. + */ void enableAllUnknown(); + + /** + * @brief Enables all sets in the list. + * + * Equivalent to calling `setEnabled(true)` on each entry. + */ void enableAll(); + + /** + * @brief Marks all sets as known and adjusts their enabled state. + * + * Unknown, non-ignored sets become known and disabled. + * Ignored-known sets are enabled if they were previously disabled. + */ void markAllAsKnown(); + + /** + * @brief Counts the number of sets that are currently enabled. + * + * @return Integer count of enabled sets. + */ int getEnabledSetsNum(); + + /** + * @brief Counts the number of sets that are currently unknown. + * + * @return Integer count of unknown sets. + */ int getUnknownSetsNum(); + + /** + * @brief Collects the short names of all sets marked as unknown. + * + * @return A list of unknown set names. + */ QStringList getUnknownSetsNames(); + + /** + * @brief Sorts the list by default rules. + * + * Orders sets first by priority (ascending), then by release date + * (most recent first), and finally alphabetically by short name. + */ void defaultSort(); };