Doxygen tab_deck_editor_visual (#6288)

Took 15 seconds

Took 3 minutes

Took 3 minutes


Took 45 seconds

Co-authored-by: Lukas Brübach <Bruebach.Lukas@bdosecurity.de>

cockatrice/src/interface/widgets/tabs/visual_deck_editor/tab_deck_editor_visual.cpp

@@ -34,24 +34,31 @@
 #include <libcockatrice/settings/cache_settings.h>
 #include <libcockatrice/utility/trice_limits.h>
 
+/**
+ * @brief Constructs the TabDeckEditorVisual instance.
+ *
+ * Sets up the central widget, tab container, menus, shortcuts,
+ * and restores the saved layout.
+ * @param _tabSupervisor Parent tab supervisor managing this tab.
+ */
 TabDeckEditorVisual::TabDeckEditorVisual(TabSupervisor *_tabSupervisor) : AbstractTabDeckEditor(_tabSupervisor)
 {
     setObjectName("TabDeckEditorVisual");
 
     createCentralFrame();
-
-    TabDeckEditorVisual::createMenus();
+    createMenus();
 
     installEventFilter(this);
 
-    TabDeckEditorVisual::retranslateUi();
+    retranslateUi();
     connect(&SettingsCache::instance().shortcuts(), SIGNAL(shortCutChanged()), this, SLOT(refreshShortcuts()));
-    TabDeckEditorVisual::refreshShortcuts();
+    refreshShortcuts();
 
-    TabDeckEditorVisual::loadLayout();
+    loadLayout();
     databaseDisplayDockWidget->setHidden(true);
 }
 
+/** @brief Creates the central frame containing the tab container. */
 void TabDeckEditorVisual::createCentralFrame()
 {
     centralWidget = new QWidget(this);
@@ -63,21 +70,22 @@ void TabDeckEditorVisual::createCentralFrame()
     tabContainer = new TabDeckEditorVisualTabWidget(centralWidget, this, deckDockWidget->deckModel,
                                                     databaseDisplayDockWidget->databaseModel,
                                                     databaseDisplayDockWidget->databaseDisplayModel);
+
     connect(tabContainer, &TabDeckEditorVisualTabWidget::cardChanged, this,
             &TabDeckEditorVisual::changeModelIndexAndCardInfo);
     connect(tabContainer, &TabDeckEditorVisualTabWidget::cardChangedDatabaseDisplay, this,
             &AbstractTabDeckEditor::updateCard);
     connect(tabContainer, &TabDeckEditorVisualTabWidget::cardClicked, this,
             &TabDeckEditorVisual::processMainboardCardClick);
-
     connect(tabContainer, &TabDeckEditorVisualTabWidget::cardClickedDatabaseDisplay, this,
             &TabDeckEditorVisual::processCardClickDatabaseDisplay);
-    centralFrame->addWidget(tabContainer);
 
+    centralFrame->addWidget(tabContainer);
     setCentralWidget(centralWidget);
     setDockOptions(QMainWindow::AnimatedDocks | QMainWindow::AllowNestedDocks | QMainWindow::AllowTabbedDocks);
 }
 
+/** @brief Updates the visual deck, analytics, and sample hand after a deck change. */
 void TabDeckEditorVisual::onDeckChanged()
 {
     AbstractTabDeckEditor::onDeckModified();
@@ -86,6 +94,7 @@ void TabDeckEditorVisual::onDeckChanged()
     tabContainer->sampleHandWidget->setDeckModel(deckDockWidget->deckModel);
 }
 
+/** @brief Creates menus for deck editing and view options, including dock actions. */
 void TabDeckEditorVisual::createMenus()
 {
     deckMenu = new DeckEditorMenu(this);
@@ -140,10 +149,10 @@ void TabDeckEditorVisual::createMenus()
     viewMenu->addAction(aResetLayout);
 
     deckMenu->setSaveStatus(false);
-
     addTabMenu(viewMenu);
 }
 
+/** @brief Returns the tab text, prepending a mark if the deck has unsaved changes. */
 QString TabDeckEditorVisual::getTabText() const
 {
     QString result = tr("Visual Deck: %1").arg(deckDockWidget->getSimpleDeckName());
@@ -152,12 +161,14 @@ QString TabDeckEditorVisual::getTabText() const
     return result;
 }
 
+/** @brief Updates card info and highlights the corresponding card in the deck view. */
 void TabDeckEditorVisual::changeModelIndexAndCardInfo(const ExactCard &activeCard)
 {
     updateCard(activeCard);
     changeModelIndexToCard(activeCard);
 }
 
+/** @brief Selects the given card in the deck view, checking main and side zones. */
 void TabDeckEditorVisual::changeModelIndexToCard(const ExactCard &activeCard)
 {
     QString cardName = activeCard.getName();
@@ -168,6 +179,7 @@ void TabDeckEditorVisual::changeModelIndexToCard(const ExactCard &activeCard)
     deckDockWidget->deckView->setCurrentIndex(index);
 }
 
+/** @brief Handles clicks on cards in the mainboard deck. */
 void TabDeckEditorVisual::processMainboardCardClick(QMouseEvent *event,
                                                     CardInfoPictureWithTextOverlayWidget *instance,
                                                     QString zoneName)
@@ -181,6 +193,7 @@ void TabDeckEditorVisual::processMainboardCardClick(QMouseEvent *event,
     }
 }
 
+/** @brief Handles clicks on cards in the database display. */
 void TabDeckEditorVisual::processCardClickDatabaseDisplay(QMouseEvent *event,
                                                           CardInfoPictureWithTextOverlayWidget *instance)
 {
@@ -193,15 +206,16 @@ void TabDeckEditorVisual::processCardClickDatabaseDisplay(QMouseEvent *event,
     }
 }
 
+/** @brief Performs "Save Deck As..." while temporarily disabling the search bar. */
 bool TabDeckEditorVisual::actSaveDeckAs()
 {
-    // We have to disable the quick-add search bar or else it'll steal focus after dialog creation.
     tabContainer->visualDeckView->searchBar->setEnabled(false);
     auto result = AbstractTabDeckEditor::actSaveDeckAs();
     tabContainer->visualDeckView->searchBar->setEnabled(true);
     return result;
 }
 
+/** @brief Shows the printing selector dock and updates it with the current card. */
 void TabDeckEditorVisual::showPrintingSelector()
 {
     printingSelectorDockWidget->printingSelector->setCard(cardInfoDockWidget->cardInfo->getCard().getCardPtr(),
@@ -211,6 +225,7 @@ void TabDeckEditorVisual::showPrintingSelector()
     printingSelectorDockWidget->setVisible(true);
 }
 
+/** @brief Set size restrictions for free floating dock widgets. */
 void TabDeckEditorVisual::freeDocksSize()
 {
     deckDockWidget->setMinimumSize(100, 100);
@@ -226,12 +241,14 @@ void TabDeckEditorVisual::freeDocksSize()
     printingSelectorDockWidget->setMaximumSize(5000, 5000);
 }
 
+/** @brief Refreshes keyboard shortcuts for this tab from settings. */
 void TabDeckEditorVisual::refreshShortcuts()
 {
     ShortcutsSettings &shortcuts = SettingsCache::instance().shortcuts();
     aResetLayout->setShortcuts(shortcuts.getShortcut("TabDeckEditorVisual/aResetLayout"));
 }
 
+/** @brief Loads the saved layout or resets to default if no layout exists. */
 void TabDeckEditorVisual::loadLayout()
 {
     LayoutsSettings &layouts = SettingsCache::instance().layouts();
@@ -280,6 +297,7 @@ void TabDeckEditorVisual::loadLayout()
     QTimer::singleShot(100, this, &TabDeckEditorVisual::freeDocksSize);
 }
 
+/** @brief Resets the layout to default positions and dock states. */
 void TabDeckEditorVisual::restartLayout()
 {
     aCardInfoDockVisible->setChecked(true);
@@ -315,6 +333,7 @@ void TabDeckEditorVisual::restartLayout()
     QTimer::singleShot(100, this, SLOT(freeDocksSize()));
 }
 
+/** @brief Retranslates UI elements for localization. */
 void TabDeckEditorVisual::retranslateUi()
 {
     deckMenu->setTitle(tr("&Visual Deck Editor"));
@@ -344,7 +363,11 @@ void TabDeckEditorVisual::retranslateUi()
     aResetLayout->setText(tr("Reset layout"));
 }
 
-// Method uses to sync docks state with menu items state
+/**
+ * @brief Handles dock visibility, floating, and layout saving events.
+ *
+ * Keeps dock state in sync with menu items and saves layout when hidden.
+ */
 bool TabDeckEditorVisual::eventFilter(QObject *o, QEvent *e)
 {
     if (e->type() == QEvent::Close) {
@@ -362,6 +385,7 @@ bool TabDeckEditorVisual::eventFilter(QObject *o, QEvent *e)
             aPrintingSelectorDockFloating->setEnabled(false);
         }
     }
+
     if (o == this && e->type() == QEvent::Hide) {
         LayoutsSettings &layouts = SettingsCache::instance().layouts();
         layouts.setDeckEditorLayoutState(saveState());
@@ -374,6 +398,7 @@ bool TabDeckEditorVisual::eventFilter(QObject *o, QEvent *e)
     return false;
 }
 
+/** @brief Toggles dock visibility based on the corresponding menu action. */
 void TabDeckEditorVisual::dockVisibleTriggered()
 {
     QObject *o = sender();
@@ -402,6 +427,7 @@ void TabDeckEditorVisual::dockVisibleTriggered()
     }
 }
 
+/** @brief Toggles dock floating state based on the corresponding menu action. */
 void TabDeckEditorVisual::dockFloatingTriggered()
 {
     QObject *o = sender();
@@ -426,6 +452,7 @@ void TabDeckEditorVisual::dockFloatingTriggered()
     }
 }
 
+/** @brief Updates menu checkboxes when a dock's top-level/floating state changes. */
 void TabDeckEditorVisual::dockTopLevelChanged(bool topLevel)
 {
     QObject *o = sender();
@@ -448,4 +475,4 @@ void TabDeckEditorVisual::dockTopLevelChanged(bool topLevel)
         aPrintingSelectorDockFloating->setChecked(topLevel);
         return;
     }
-}
+}

cockatrice/src/interface/widgets/tabs/visual_deck_editor/tab_deck_editor_visual.h

@@ -4,47 +4,193 @@
 #include "../tab.h"
 #include "tab_deck_editor_visual_tab_widget.h"
 
+/**
+ * @class TabDeckEditorVisual
+ * @ingroup DeckEditorTabs
+ * @brief TabDeckEditorVisual provides a fully-featured deck editor tab with an enhanced visual interface. It extends
+ * AbstractTabDeckEditor.
+ *
+ * **Description:**
+ * TabDeckEditorVisual is a fully-featured deck editor tab with an enhanced visual interface. It extends
+ * AbstractTabDeckEditor and integrates multiple visual components such as a visual deck view, database display,
+ * deck analytics, and sample hand preview.
+ *
+ * **Purpose:**
+ *
+ * - Provides an intuitive, visual interface for deck editing.
+ * - Combines visual deck representation, card database browsing, and analytics into one tab.
+ * - Supports card interactions via clicks, hover events, and drag-and-drop-like behavior (not yet).
+ *
+ * **Dock Widgets and Components:**
+ *
+ * - TabDeckEditorVisualTabWidget — Container for visual sub-tabs (further described in @ref
+ *   code_client_tabs_deck_editor_visual_tab).
+ *     - VisualDeckEditorWidget — Displays and interacts with the deck visually.
+ *     - VisualDatabaseDisplayWidget — Allows adding cards from the database visually.
+ *     - DeckAnalyticsWidget — Displays deck statistics and analytics.
+ *     - VisualDeckEditorSampleHandWidget — Simulates a sample hand from the deck.
+ * - DeckEditorCardInfoDockWidget — Shows detailed card info for hovered/selected cards.
+ * - DeckEditorDeckDockWidget — Displays deck zones and cards in a tree-view.
+ * - DeckEditorFilterDockWidget — Provides filtering options for card searches.
+ * - DeckEditorPrintingSelectorDockWidget — Selects specific card printings.
+ *
+ * **Key Methods:**
+ *
+ * - createCentralFrame() — Sets up the central widget and visual sub-tabs.
+ * - onDeckChanged() — Refreshes visual widgets when the deck is modified.
+ * - changeModelIndexAndCardInfo(const ExactCard &card) — Updates deck model selection and card info.
+ * - changeModelIndexToCard(const ExactCard &card) — Selects the card in the deck view.
+ * - processMainboardCardClick(QMouseEvent *event, ...) — Handles clicks on mainboard cards.
+ * - processCardClickDatabaseDisplay(QMouseEvent *event, ...) — Handles clicks on database cards.
+ * - actSaveDeckAs() — Overrides save action with temporary UI adjustments.
+ * - showPrintingSelector() — Opens the printing selector dock for the current card.
+ * - freeDocksSize() — Frees constraints on dock widget sizes.
+ * - refreshShortcuts() — Updates tab-specific shortcuts from settings.
+ * - loadLayout() — Loads saved layout or applies default if none exists.
+ * - restartLayout() — Resets dock positions, visibility, and floating states.
+ * - retranslateUi() — Updates text/UI elements for localization.
+ * - eventFilter(QObject *o, QEvent *e) — Syncs dock states with menu actions and saves layout.
+ */
 class TabDeckEditorVisual : public AbstractTabDeckEditor
 {
     Q_OBJECT
+
 protected slots:
+    /**
+     * @brief Load the editor layout from settings.
+     */
     void loadLayout() override;
+
+    /**
+     * @brief Reset and restart the layout to default.
+     */
     void restartLayout() override;
+
+    /**
+     * @brief Set size restrictions for free floating dock widgets.
+     */
     void freeDocksSize() override;
+
+    /**
+     * @brief Refresh keyboard shortcuts for this tab.
+     */
     void refreshShortcuts() override;
 
+    /**
+     * @brief Synchronize dock state with menu items.
+     * @param o The object sending the event.
+     * @param e The event being filtered.
+     * @return true if the event is handled, false otherwise.
+     */
     bool eventFilter(QObject *o, QEvent *e) override;
+
+    /**
+     * @brief Triggered when a dock visibility menu item is clicked.
+     */
     void dockVisibleTriggered() override;
+
+    /**
+     * @brief Triggered when a dock floating menu item is clicked.
+     */
     void dockFloatingTriggered() override;
+
+    /**
+     * @brief Triggered when a dock top-level state changes.
+     * @param topLevel True if the dock became floating.
+     */
     void dockTopLevelChanged(bool topLevel) override;
 
 protected:
-    TabDeckEditorVisualTabWidget *tabContainer;
+    TabDeckEditorVisualTabWidget *tabContainer; ///< Tab container holding different visual widgets.
 
-    QVBoxLayout *centralFrame;
-    QVBoxLayout *searchAndDatabaseFrame;
-    QHBoxLayout *searchLayout;
-    QDockWidget *searchAndDatabaseDock;
-    QWidget *centralWidget;
+    QVBoxLayout *centralFrame;           ///< Layout for central widgets.
+    QVBoxLayout *searchAndDatabaseFrame; ///< Layout for search and database display.
+    QHBoxLayout *searchLayout;           ///< Layout for search bar.
+    QDockWidget *searchAndDatabaseDock;  ///< Dock widget for search/database display.
+    QWidget *centralWidget;              ///< Central widget of the editor.
 
 public:
+    /**
+     * @brief Constructs a visual deck editor tab.
+     * @param _tabSupervisor Pointer to the tab supervisor managing this tab.
+     */
     explicit TabDeckEditorVisual(TabSupervisor *_tabSupervisor);
+
+    /**
+     * @brief Retranslate UI strings (for i18n support).
+     */
     void retranslateUi() override;
+
+    /**
+     * @brief Get the display text for the tab.
+     * @return Tab text with optional modification indicator.
+     */
     QString getTabText() const override;
+
+    /**
+     * @brief Update the currently selected card in the deck and UI.
+     * @param activeCard Card to display.
+     */
     void changeModelIndexAndCardInfo(const ExactCard &activeCard);
+
+    /**
+     * @brief Change the deck view selection to a specific card.
+     * @param activeCard Card to select in the deck view.
+     */
     void changeModelIndexToCard(const ExactCard &activeCard);
+
+    /**
+     * @brief Create the deck analytics dock widget.
+     */
     void createDeckAnalyticsDock();
+
+    /**
+     * @brief Setup menus for this visual deck editor.
+     */
     void createMenus() override;
+
+    /**
+     * @brief Create search and database display frame.
+     */
     void createSearchAndDatabaseFrame();
+
+    /**
+     * @brief Create central frame for visual widgets.
+     */
     void createCentralFrame();
 
 public slots:
+    /**
+     * @brief Refresh UI when the deck changes.
+     */
     void onDeckChanged() override;
+
+    /**
+     * @brief Show the printing selector dock for the currently active card.
+     */
     void showPrintingSelector() override;
+
+    /**
+     * @brief Handle card clicks in the mainboard visual deck.
+     * @param event Mouse event triggering the action.
+     * @param instance Widget representing the clicked card.
+     * @param zoneName Deck zone of the card.
+     */
     void
     processMainboardCardClick(QMouseEvent *event, CardInfoPictureWithTextOverlayWidget *instance, QString zoneName);
+
+    /**
+     * @brief Handle card clicks in the database visual display.
+     * @param event Mouse event triggering the action.
+     * @param instance Widget representing the clicked card.
+     */
     void processCardClickDatabaseDisplay(QMouseEvent *event, CardInfoPictureWithTextOverlayWidget *instance);
+
+    /**
+     * @brief Save the deck under a new name.
+     * @return true if successful, false otherwise.
+     */
     bool actSaveDeckAs() override;
 };
 
-#endif
+#endif