Modularize and Doxygen decklist.cpp (#6099)

common/deck_list_card_node.h

@@ -0,0 +1,169 @@
+/**
+ * @file deck_list_card_node.h
+ * @brief Defines the DecklistCardNode class, representing a single card entry
+ *        in the deck list tree.
+ *
+ * DecklistCardNode is the concrete data-bearing node that corresponds to
+ * an individual card entry in a deck. It stores the card’s name, quantity,
+ * set information, and provider ID. These nodes live inside an
+ * InnerDecklistNode (e.g., under Mainboard → Group → Card).
+ */
+
+#ifndef COCKATRICE_DECK_LIST_CARD_NODE_H
+#define COCKATRICE_DECK_LIST_CARD_NODE_H
+
+#include "abstract_deck_list_card_node.h"
+#include "card_ref.h"
+
+/**
+ * @class DecklistCardNode
+ * @brief Concrete node type representing an actual card entry in the deck.
+ *
+ * This class extends AbstractDecklistCardNode to hold all information
+ * needed to uniquely identify a card printing within the deck.
+ *
+ * ### Role in the hierarchy:
+ * - Child of an InnerDecklistNode (which groups cards by zone or criteria).
+ * - Leaf node in the deck tree; it does not contain further children.
+ *
+ * ### Data stored:
+ * - @c name: Card’s display name.
+ * - @c number: Quantity of this card in the deck.
+ * - @c cardSetShortName: Abbreviation of the set (e.g., "NEO" for Neon Dynasty).
+ * - @c cardSetNumber: Collector number within the set.
+ * - @c cardProviderId: External provider identifier (e.g., UUID or MTGJSON ID).
+ *
+ * ### Usage:
+ * - Constructed directly when building a deck list from user input or file.
+ * - Used by DeckListModel to present cards in Qt views.
+ * - Convertible to @c CardRef for database lookups or cross-references.
+ *
+ * ### Ownership:
+ * - Owned by its parent InnerDecklistNode.
+ * - Destroyed automatically when its parent is destroyed.
+ */
+class DecklistCardNode : public AbstractDecklistCardNode
+{
+    QString name;             ///< Display name of the card.
+    int number;               ///< Quantity of this card in the deck.
+    QString cardSetShortName; ///< Short set code (e.g., "NEO").
+    QString cardSetNumber;    ///< Collector number within the set.
+    QString cardProviderId;   ///< External provider identifier (e.g., UUID).
+
+public:
+    /**
+     * @brief Construct a new DecklistCardNode.
+     *
+     * @param _name Display name of the card.
+     * @param _number Quantity of this card (default = 1).
+     * @param _parent Parent node in the tree (zone or group). May be nullptr.
+     * @param position Index to insert into parent’s children. -1 = append.
+     * @param _cardSetShortName Short set code (e.g., "NEO").
+     * @param _cardSetNumber Collector number within the set.
+     * @param _cardProviderId External provider ID (e.g., UUID).
+     *
+     * On construction, if a parent is provided, this node is inserted into
+     * the parent’s children list automatically.
+     */
+    explicit DecklistCardNode(QString _name = QString(),
+                              int _number = 1,
+                              InnerDecklistNode *_parent = nullptr,
+                              int position = -1,
+                              QString _cardSetShortName = QString(),
+                              QString _cardSetNumber = QString(),
+                              QString _cardProviderId = QString())
+        : AbstractDecklistCardNode(_parent, position), name(std::move(_name)), number(_number),
+          cardSetShortName(std::move(_cardSetShortName)), cardSetNumber(std::move(_cardSetNumber)),
+          cardProviderId(std::move(_cardProviderId))
+    {
+    }
+
+    /**
+     * @brief Copy constructor with new parent assignment.
+     * @param other Existing DecklistCardNode to copy.
+     * @param _parent Parent node for the copy.
+     *
+     * Creates a deep copy of the card node’s properties, but attaches
+     * the new instance to a different parent in the tree.
+     */
+    explicit DecklistCardNode(DecklistCardNode *other, InnerDecklistNode *_parent);
+
+    /// @return The quantity of this card.
+    int getNumber() const override
+    {
+        return number;
+    }
+
+    /// @param _number Set the quantity of this card.
+    void setNumber(int _number) override
+    {
+        number = _number;
+    }
+
+    /// @return The display name of this card.
+    QString getName() const override
+    {
+        return name;
+    }
+
+    /// @param _name Set the display name of this card.
+    void setName(const QString &_name) override
+    {
+        name = _name;
+    }
+
+    /// @return The provider identifier for this card.
+    QString getCardProviderId() const override
+    {
+        return cardProviderId;
+    }
+
+    /// @param _providerId Set the provider identifier for this card.
+    void setCardProviderId(const QString &_providerId) override
+    {
+        cardProviderId = _providerId;
+    }
+
+    /// @return The short set code (e.g., "NEO").
+    QString getCardSetShortName() const override
+    {
+        return cardSetShortName;
+    }
+
+    /// @param _cardSetShortName Set the short set code.
+    void setCardSetShortName(const QString &_cardSetShortName) override
+    {
+        cardSetShortName = _cardSetShortName;
+    }
+
+    /// @return The collector number of this card within its set.
+    QString getCardCollectorNumber() const override
+    {
+        return cardSetNumber;
+    }
+
+    /// @param _cardSetNumber Set the collector number.
+    void setCardCollectorNumber(const QString &_cardSetNumber) override
+    {
+        cardSetNumber = _cardSetNumber;
+    }
+
+    /// @return Always false; card nodes are not deck headers.
+    [[nodiscard]] bool isDeckHeader() const override
+    {
+        return false;
+    }
+
+    /**
+     * @brief Convert this node to a CardRef.
+     *
+     * @return A CardRef with the card’s name and provider ID, suitable
+     *         for database lookups or comparison with other card sources.
+     */
+    CardRef toCardRef() const
+    {
+        return {name, cardProviderId};
+    }
+};
+
+#endif // COCKATRICE_DECK_LIST_CARD_NODE_H