jeirmeister/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2026-07-03 03:53:56 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Standardize Doxygen documentation (#6885)

Browse source
This commit is contained in:
DawnFire42 2026-05-21 16:58:07 -04:00 • committed by GitHub
parent 03d54265fe
commit 33e0f8699b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
306 changed files with 539 additions and 487 deletions
Download patch file Download diff file Expand all files Collapse all files

68
cockatrice/src/game_graphics/zones/select_zone.h
View file

@ -21,33 +21,41 @@ class SelectZone : public CardZone
{
Q_OBJECT
public:
/// Finds the SelectZone that owns a card, regardless of whether the card is parented
/// to the zone directly or to its clip container. Returns nullptr if not in a SelectZone.
/**
* @brief Finds the SelectZone that owns a card, regardless of whether the card is parented
* to the zone directly or to its clip container. Returns nullptr if not in a SelectZone.
*/
static SelectZone *findOwningSelectZone(const QGraphicsItem *card);
SelectZone(CardZoneLogic *logic, QGraphicsItem *parent = nullptr);
~SelectZone() override;
void onCardAdded(CardItem *addedCard) override;
/// @brief Temporarily reparents a card from the clip container to this zone so hover scaling is visible beyond clip
/// bounds. Safe no-op if no clip container exists. Coordinates are preserved (clip container is at (0,0) with no
/// transform).
/**
* @brief Temporarily reparents a card from the clip container to this zone so hover scaling is visible beyond clip
* bounds. Safe no-op if no clip container exists. Coordinates are preserved (clip container is at (0,0) with no
* transform).
*/
void escapeClipForHover(QGraphicsItem *card);
/// @brief Restores a hover-escaped card back to the clip container. Guards against zone transitions that already
/// reparented the card.
/**
* @brief Restores a hover-escaped card back to the clip container. Guards against zone transitions that already
* reparented the card.
*/
void restoreClipAfterHover(QGraphicsItem *card);
private:
QPointF selectionOrigin;
QSet<CardItem *> cardsInSelectionRect;
/// Invisible clipping parent for cards; owned by Qt parent-child tree (parented to this zone).
/// Created by setupClipContainer(); null when no clip container is active.
/**
* @brief Invisible clipping parent for cards; owned by Qt parent-child tree (parented to this zone).
* Created by setupClipContainer(); null when no clip container is active.
*/
QGraphicsRectItem *cardClipContainer = nullptr;
protected:
// -- Layout computation --
/// Parameters describing a vertical card stack's geometry.
/** @brief Parameters describing a vertical card stack's geometry. */
struct StackLayoutParams
{
int cardCount; ///< Number of cards in the stack
@ -55,21 +63,23 @@ protected:
qreal cardHeight; ///< Height of a single card
qreal desiredOffset; ///< Preferred vertical offset between card tops
qreal minOffset = 0.0; ///< Minimum offset to preserve (0 allows full compression)
/// When false (default), reserves full cardHeight for the bottom card, ensuring
/// all cards remain within zone bounds. When true, allows the bottom card to
/// partially overflow using sqrt-scaled allowance. Use with setupClipContainer()
/// for zones too short to fit a full card.
/**
* @brief When false (default), reserves full cardHeight for the bottom card, ensuring
* all cards remain within zone bounds. When true, allows the bottom card to
* partially overflow using sqrt-scaled allowance. Use with setupClipContainer()
* for zones too short to fit a full card.
*/
bool allowBottomOverflow = false;
};
/// Result of computing a vertical stack layout.
/** @brief Result of computing a vertical stack layout. */
struct ZoneLayout
{
qreal effectiveOffset; ///< Actual offset between card tops (may be compressed)
qreal start; ///< Y coordinate of the first card's top edge
};
/// Minimum visible pixels of each card's top edge when stacking compresses offsets in tight zones.
/** @brief Minimum visible pixels of each card's top edge when stacking compresses offsets in tight zones. */
static constexpr qreal MIN_CARD_VISIBLE = 10.0;
/**
@ -88,11 +98,13 @@ protected:
*/
static ZoneLayout computeZoneLayout(const StackLayoutParams &params);
/// Builds StackLayoutParams from the current card list and zone geometry.
/** @brief Builds StackLayoutParams from the current card list and zone geometry. */
StackLayoutParams buildStackParams(qreal minOffset = 0.0) const;
/// Computes the card index at a given y-coordinate within the zone's vertical layout.
/// Returns 0 if the zone has no cards or the offset is zero.
/**
* @brief Computes the card index at a given y-coordinate within the zone's vertical layout.
* Returns 0 if the zone has no cards or the offset is zero.
*/
int calcDropIndexFromY(qreal dropY, qreal minOffset = 0.0) const;
/**
@ -111,17 +123,21 @@ protected:
// (e.g., zones too short to fit a full card). To enable: call setupClipContainer() in the
// zone's constructor, and set allowBottomOverflow=true in layout params.
/// Restores any cards that were hover-escaped but whose hover state was not properly cleaned up.
/// Call at the start of reorganizeCards() in zones that use a clip container.
/**
* @brief Restores any cards that were hover-escaped but whose hover state was not properly cleaned up.
* Call at the start of reorganizeCards() in zones that use a clip container.
*/
void restoreStaleEscapedCards();
/// Creates a clip container child item that clips card overflow to zone bounds.
/// Cards entering this zone are reparented to this container by the onCardAdded override.
/// Disables zone-level child clipping; clipping is delegated to the container.
/// @param zValue Optional z-value for the clip container (e.g. ZValues::CARD_BASE)
/**
* @brief Creates a clip container child item that clips card overflow to zone bounds.
* Cards entering this zone are reparented to this container by the onCardAdded override.
* Disables zone-level child clipping; clipping is delegated to the container.
* @param zValue Optional z-value for the clip container (e.g. ZValues::CARD_BASE)
*/
void setupClipContainer(std::optional<qreal> zValue = std::nullopt);
/// Updates the clip container rect to match this zone's current boundingRect().
/** @brief Updates the clip container rect to match this zone's current boundingRect(). */
void updateClipRect();
void mouseMoveEvent(QGraphicsSceneMouseEvent *event) override;