From 24b5dab456b546b2b60b522fa83eca325f458211 Mon Sep 17 00:00:00 2001 From: RickyRister <42636155+RickyRister@users.noreply.github.com> Date: Thu, 28 Nov 2024 11:40:49 -0800 Subject: [PATCH] leave some documentation on Zone classes (#5199) * leave some documentation on Zone classes * small refactor * undo functional change from refactor and clean up comments * move variables into if block --- .../src/game/board/abstract_graphics_item.h | 3 ++ cockatrice/src/game/player/player.h | 3 ++ cockatrice/src/game/zones/card_zone.cpp | 8 +++++ cockatrice/src/game/zones/card_zone.h | 6 ++++ cockatrice/src/game/zones/pile_zone.h | 4 +++ cockatrice/src/game/zones/select_zone.h | 3 ++ cockatrice/src/game/zones/view_zone.cpp | 7 ++++ cockatrice/src/game/zones/view_zone.h | 9 ++++++ .../src/game/zones/view_zone_widget.cpp | 32 ++++++++++++------- cockatrice/src/game/zones/view_zone_widget.h | 6 ++++ 10 files changed, 69 insertions(+), 12 deletions(-) diff --git a/cockatrice/src/game/board/abstract_graphics_item.h b/cockatrice/src/game/board/abstract_graphics_item.h index 8fef7bb79..3461c35b3 100644 --- a/cockatrice/src/game/board/abstract_graphics_item.h +++ b/cockatrice/src/game/board/abstract_graphics_item.h @@ -13,6 +13,9 @@ enum GraphicsItemType typeOther = QGraphicsItem::UserType + 6 }; +/** + * Parent class of all objects that appear in a game. + */ class AbstractGraphicsItem : public QObject, public QGraphicsItem { Q_OBJECT diff --git a/cockatrice/src/game/player/player.h b/cockatrice/src/game/player/player.h index 5aecaa932..7f744a909 100644 --- a/cockatrice/src/game/player/player.h +++ b/cockatrice/src/game/player/player.h @@ -68,6 +68,9 @@ class ZoneViewZone; const int MAX_TOKENS_PER_DIALOG = 99; +/** + * The entire graphical area belonging to a single player. + */ class PlayerArea : public QObject, public QGraphicsItem { Q_OBJECT diff --git a/cockatrice/src/game/zones/card_zone.cpp b/cockatrice/src/game/zones/card_zone.cpp index 7e860d6de..ad0175506 100644 --- a/cockatrice/src/game/zones/card_zone.cpp +++ b/cockatrice/src/game/zones/card_zone.cpp @@ -11,6 +11,14 @@ #include #include +/** + * @param _p the player that the zone belongs to + * @param _name internal name of the zone + * @param _isShufflable whether it makes sense to shuffle this zone by default after viewing it + * @param _contentsKnown whether the cards in the zone are known to the client + * @param parent the parent graphics object. + * @param _isView whether this zone is a view of another zone. Modifications to a view should modify the original + */ CardZone::CardZone(Player *_p, const QString &_name, bool _hasCardAttr, diff --git a/cockatrice/src/game/zones/card_zone.h b/cockatrice/src/game/zones/card_zone.h index c0ad27bc3..6d6cddd81 100644 --- a/cockatrice/src/game/zones/card_zone.h +++ b/cockatrice/src/game/zones/card_zone.h @@ -14,6 +14,12 @@ class QAction; class QPainter; class CardDragItem; +/** + * A zone in the game that can contain cards. + * This class contains methods to get and modify the cards that are contained inside this zone. + * + * The cards are stored as a list of `CardItem*`. + */ class CardZone : public AbstractGraphicsItem { Q_OBJECT diff --git a/cockatrice/src/game/zones/pile_zone.h b/cockatrice/src/game/zones/pile_zone.h index 5d28b3816..a66543ab3 100644 --- a/cockatrice/src/game/zones/pile_zone.h +++ b/cockatrice/src/game/zones/pile_zone.h @@ -3,6 +3,10 @@ #include "card_zone.h" +/** + * A CardZone where the cards are in a single pile instead of being laid out. + * Usually only top card is accessible by clicking. + */ class PileZone : public CardZone { Q_OBJECT diff --git a/cockatrice/src/game/zones/select_zone.h b/cockatrice/src/game/zones/select_zone.h index efec4bb02..ff0c12182 100644 --- a/cockatrice/src/game/zones/select_zone.h +++ b/cockatrice/src/game/zones/select_zone.h @@ -3,6 +3,9 @@ #include "card_zone.h" +/** + * A CardZone where the cards are laid out, with each card directly interactable by clicking. + */ class SelectZone : public CardZone { Q_OBJECT diff --git a/cockatrice/src/game/zones/view_zone.cpp b/cockatrice/src/game/zones/view_zone.cpp index aea6e0df2..6c7defe66 100644 --- a/cockatrice/src/game/zones/view_zone.cpp +++ b/cockatrice/src/game/zones/view_zone.cpp @@ -16,6 +16,13 @@ #include #include +/** + * @param _p the player that the cards are revealed to. + * @param _origZone the zone the cards were revealed from. + * @param _revealZone if false, the cards will be face down. + * @param _writeableRevealZone whether the player can interact with the revealed cards. + * @param parent the parent QGraphicsWidget containing the reveal zone + */ ZoneViewZone::ZoneViewZone(Player *_p, CardZone *_origZone, int _numberCards, diff --git a/cockatrice/src/game/zones/view_zone.h b/cockatrice/src/game/zones/view_zone.h index a0bc15291..092a1c51c 100644 --- a/cockatrice/src/game/zones/view_zone.h +++ b/cockatrice/src/game/zones/view_zone.h @@ -10,6 +10,15 @@ class Response; class ServerInfo_Card; class QGraphicsSceneWheelEvent; +/** + * A CardZone that is a view into another CardZone. + * If this zone is writable, then modifications to this zone will be reflected in the underlying zone. + * + * Most interactions with StackZones are handled through a zone view. + * For example, viewing the deck/graveyard/exile is handled through a view. + * + * Handles both limited reveals (eg. look at top X cards) and full zone reveals (eg. searching the deck). + */ class ZoneViewZone : public SelectZone, public QGraphicsLayoutItem { Q_OBJECT diff --git a/cockatrice/src/game/zones/view_zone_widget.cpp b/cockatrice/src/game/zones/view_zone_widget.cpp index 077cff0b2..b6275c813 100644 --- a/cockatrice/src/game/zones/view_zone_widget.cpp +++ b/cockatrice/src/game/zones/view_zone_widget.cpp @@ -17,6 +17,15 @@ #include #include +/** + * @param _player the player the cards were revealed to. + * @param _origZone the zone the cards were revealed from. + * @param numberCards num of cards to reveal from the zone. Ex: scry the top 3 cards. + * Pass in a negative number to reveal the entire zone. + * -1 specifically will give the option to shuffle the zone upon closing the window. + * @param _revealZone if false, the cards will be face down. + * @param _writeableRevealZone whether the player can interact with the revealed cards. + */ ZoneViewWidget::ZoneViewWidget(Player *_player, CardZone *_origZone, int numberCards, @@ -31,10 +40,10 @@ ZoneViewWidget::ZoneViewWidget(Player *_player, setFlag(ItemIgnoresTransformations); QGraphicsLinearLayout *vbox = new QGraphicsLinearLayout(Qt::Vertical); - QGraphicsLinearLayout *hPilebox = 0; + // If the number is < 0, then it means that we can give the option to make the area sorted if (numberCards < 0) { - hPilebox = new QGraphicsLinearLayout(Qt::Horizontal); + QGraphicsLinearLayout *hPilebox = new QGraphicsLinearLayout(Qt::Horizontal); QGraphicsLinearLayout *hFilterbox = new QGraphicsLinearLayout(Qt::Horizontal); QGraphicsProxyWidget *sortByNameProxy = new QGraphicsProxyWidget; @@ -57,16 +66,16 @@ ZoneViewWidget::ZoneViewWidget(Player *_player, QGraphicsProxyWidget *pileViewProxy = new QGraphicsProxyWidget; pileViewProxy->setWidget(&pileViewCheckBox); hPilebox->addItem(pileViewProxy); - } - if (_origZone->getIsShufflable() && (numberCards == -1)) { - shuffleCheckBox.setChecked(true); - QGraphicsProxyWidget *shuffleProxy = new QGraphicsProxyWidget; - shuffleProxy->setWidget(&shuffleCheckBox); - hPilebox->addItem(shuffleProxy); - } + if (_origZone->getIsShufflable() && numberCards == -1) { + shuffleCheckBox.setChecked(true); + QGraphicsProxyWidget *shuffleProxy = new QGraphicsProxyWidget; + shuffleProxy->setWidget(&shuffleCheckBox); + hPilebox->addItem(shuffleProxy); + } - vbox->addItem(hPilebox); + vbox->addItem(hPilebox); + } extraHeight = vbox->sizeHint(Qt::PreferredSize).height(); resize(150, 150); @@ -93,8 +102,7 @@ ZoneViewWidget::ZoneViewWidget(Player *_player, connect(zone, SIGNAL(wheelEventReceived(QGraphicsSceneWheelEvent *)), scrollBarProxy, SLOT(recieveWheelEvent(QGraphicsSceneWheelEvent *))); - // numberCard is the num of cards we want to reveal from an area. Ex: scry the top 3 cards. - // If the number is < 0 then it means that we can make the area sorted and we dont care about the order. + // only wire up sort options after creating ZoneViewZone, since it segfaults otherwise. if (numberCards < 0) { connect(&sortByNameCheckBox, &QCheckBox::QT_STATE_CHANGED, this, &ZoneViewWidget::processSortByName); connect(&sortByTypeCheckBox, &QCheckBox::QT_STATE_CHANGED, this, &ZoneViewWidget::processSortByType); diff --git a/cockatrice/src/game/zones/view_zone_widget.h b/cockatrice/src/game/zones/view_zone_widget.h index 43e92f425..78b667bfa 100644 --- a/cockatrice/src/game/zones/view_zone_widget.h +++ b/cockatrice/src/game/zones/view_zone_widget.h @@ -31,6 +31,12 @@ public slots: } }; +/** + * A QGraphicsWidget that holds a ZoneViewZone. + * + * Some zone views allow sorting. + * This widget will display the sort options when relevant, and forward the values of the options to the ZoneViewZone. + */ class ZoneViewWidget : public QGraphicsWidget { Q_OBJECT