Modularize and Doxygen decklist.cpp (#6099)

common/abstract_deck_list_card_node.h

@@ -0,0 +1,148 @@
+/**
+ * @file abstract_deck_list_card_node.h
+ * @brief Defines the AbstractDecklistCardNode base class, which adds
+ *        card-specific behavior on top of AbstractDecklistNode.
+ *
+ * This class is the intermediate abstract base between the generic
+ * AbstractDecklistNode and concrete card entries such as DecklistCardNode
+ * or DecklistModelCardNode.
+ */
+
+#ifndef COCKATRICE_ABSTRACT_DECK_LIST_CARD_NODE_H
+#define COCKATRICE_ABSTRACT_DECK_LIST_CARD_NODE_H
+
+#include "abstract_deck_list_node.h"
+
+/**
+ * @class AbstractDecklistCardNode
+ * @brief Abstract base class for all deck list nodes that represent
+ *        actual card entries.
+ *
+ * While AbstractDecklistNode provides the general interface for all
+ * nodes in the deck tree (zones, groups, cards), this subclass refines
+ * the interface to cover properties specific to *cards*:
+ * - Quantity (number of copies).
+ * - Name.
+ * - Set code and collector number.
+ * - Provider ID.
+ *
+ * ### Role in the hierarchy:
+ * - Leaf-oriented abstract class; no children of its own.
+ * - Serves as the base for concrete implementations:
+ *   - @c DecklistCardNode: Stores real card data in the deck tree.
+ *   - @c DecklistModelCardNode: Wraps a DecklistCardNode for use
+ *     in the Qt model layer.
+ *
+ * ### Responsibilities:
+ * - Defines getters/setters for all card-identifying attributes.
+ * - Provides comparison logic for sorting by name or number.
+ * - Implements XML serialization for saving/loading deck files.
+ *
+ * ### Ownership:
+ * - As with all nodes, owned by its parent InnerDecklistNode.
+ */
+class AbstractDecklistCardNode : public AbstractDecklistNode
+{
+public:
+    /**
+     * @brief Construct a new AbstractDecklistCardNode.
+     *
+     * @param _parent Optional parent node. If provided, this node
+     *        will be inserted into the parent’s children list.
+     * @param position Index at which to insert into parent’s children.
+     *        If -1, the node is appended to the end.
+     */
+    explicit AbstractDecklistCardNode(InnerDecklistNode *_parent = nullptr, int position = -1)
+        : AbstractDecklistNode(_parent, position)
+    {
+    }
+
+    /// @return The number of copies of this card in the deck.
+    virtual int getNumber() const = 0;
+
+    /// @param _number Set the number of copies of this card.
+    virtual void setNumber(int _number) = 0;
+
+    /// @return The display name of this card.
+    QString getName() const override = 0;
+
+    /// @param _name Set the display name of this card.
+    virtual void setName(const QString &_name) = 0;
+
+    /// @return The provider identifier for this card (e.g., UUID).
+    virtual QString getCardProviderId() const override = 0;
+
+    /// @param _cardProviderId Set the provider identifier for this card.
+    virtual void setCardProviderId(const QString &_cardProviderId) = 0;
+
+    /// @return The abbreviated set code (e.g., "NEO").
+    virtual QString getCardSetShortName() const override = 0;
+
+    /// @param _cardSetShortName Set the abbreviated set code.
+    virtual void setCardSetShortName(const QString &_cardSetShortName) = 0;
+
+    /// @return The collector number of the card within its set.
+    virtual QString getCardCollectorNumber() const override = 0;
+
+    /// @param _cardSetNumber Set the collector number.
+    virtual void setCardCollectorNumber(const QString &_cardSetNumber) = 0;
+
+    /**
+     * @brief Get the height of this node in the tree.
+     *
+     * For card nodes, height is always 0 because they are leaf nodes
+     * and do not contain children.
+     *
+     * @return 0
+     */
+    int height() const override
+    {
+        return 0;
+    }
+
+    /**
+     * @brief Compare this card node against another for sorting.
+     *
+     * Uses the node’s current @c sortMethod to determine how to compare:
+     * - ByName: Alphabetical comparison.
+     * - ByNumber: Numerical comparison.
+     * - Default: Falls back to implementation-defined behavior.
+     *
+     * @param other Another node to compare against.
+     * @return true if this node should sort before @p other.
+     */
+    bool compare(AbstractDecklistNode *other) const override;
+
+    /**
+     * @brief Compare this card node to another by quantity.
+     * @param other Node to compare against.
+     * @return true if this node’s number < other’s number.
+     */
+    bool compareNumber(AbstractDecklistNode *other) const;
+
+    /**
+     * @brief Compare this card node to another by name.
+     * @param other Node to compare against.
+     * @return true if this node’s name comes before other’s name.
+     */
+    bool compareName(AbstractDecklistNode *other) const;
+
+    /**
+     * @brief Deserialize this node’s properties from XML.
+     * @param xml QXmlStreamReader positioned at the element.
+     * @return true if parsing succeeded.
+     *
+     * This supports loading deck files from Cockatrice’s XML format.
+     */
+    bool readElement(QXmlStreamReader *xml) override;
+
+    /**
+     * @brief Serialize this node’s properties to XML.
+     * @param xml Writer to append this node’s XML element.
+     *
+     * This supports saving deck files to Cockatrice’s XML format.
+     */
+    void writeElement(QXmlStreamWriter *xml) override;
+};
+
+#endif // COCKATRICE_ABSTRACT_DECK_LIST_CARD_NODE_H