Skip to content

Commit

Permalink
Add detailed JavaDoc comments to campaign options classes
Browse files Browse the repository at this point in the history 
Enhanced the documentation across CampaignOptionsUtilities, CampaignOptionsDialog, and CampaignOptionsPane. Added class-level and method-level JavaDocs to improve clarity, describe functionality, and outline key features. This increases maintainability and helps developers understand the architecture and usage of these classes.
  • Loading branch information
@IllianiCBT
IllianiCBT committed Jan 14, 2025
1 parent 67bce21 commit f1bb5cf
Show file tree
Hide file tree
Showing 3 changed files with 208 additions and 40 deletions.
72 changes: 69 additions & 3 deletions MekHQ/src/mekhq/gui/campaignOptions/CampaignOptionsDialog.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,25 @@
import static mekhq.gui.campaignOptions.CampaignOptionsDialog.CampaignOptionsDialogMode.STARTUP;
import static mekhq.gui.campaignOptions.SelectPresetDialog.PRESET_SELECTION_CANCELLED;

/**
* The {@code CampaignOptionsDialog} class represents a dialog window for presenting
* and modifying the campaign options in MekHQ. It provides a user interface
* for accessing, editing, and applying various gameplay-related settings for a campaign.
* The dialog also supports applying presets and saving settings for future use.
* <p>
* This dialog is an extension of {@link AbstractMHQButtonDialog} and integrates closely
* with a {@link Campaign} instance, representing the current or a predefined campaign setup.
* It facilitates user interaction for fine-tuning the game campaign experience.
* </p>
*
* <h3>Key Features:</h3>
* <ul>
* <li>Initialization in multiple modes, such as NORMAL, STARTUP, and ABRIDGED.</li>
* <li>Ability to load and save presets for recurring configurations.</li>
* <li>Application of campaign settings directly to the active {@link Campaign} instance.</li>
* <li>Visual notifications, such as a notice about StratCon activation during the campaign.</li>
* </ul>
*/
public class CampaignOptionsDialog extends AbstractMHQButtonDialog {
private static final String RESOURCE_PACKAGE = "mekhq/resources/CampaignOptionsDialog";
private static final ResourceBundle resources = ResourceBundle.getBundle(RESOURCE_PACKAGE);
Expand All @@ -50,6 +69,13 @@ public enum CampaignOptionsDialogMode {
ABRIDGED
}

/**
* Constructs a {@code CampaignOptionsDialog} with the specified parent frame and
* campaign instance. Initializes the dialog using the default {@code NORMAL} mode.
*
* @param frame the parent {@link JFrame} for this dialog
* @param campaign the {@link Campaign} instance representing the current campaign
*/
public CampaignOptionsDialog(final JFrame frame, final Campaign campaign) {
super(frame, true, resources, "CampaignOptionsDialog", "campaignOptions.title");
this.campaign = campaign;
Expand All @@ -61,6 +87,16 @@ public CampaignOptionsDialog(final JFrame frame, final Campaign campaign) {
setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
}

/**
* Constructs a {@code CampaignOptionsDialog} with the specified parent frame,
* campaign instance, campaign preset, and mode. If a preset is provided, it is
* automatically applied to the campaign.
*
* @param frame the parent {@link JFrame} for this dialog
* @param campaign the {@link Campaign} instance for the current or preconfigured campaign
* @param preset an optional {@link CampaignPreset} to initialize the campaign (can be null)
* @param mode the {@link CampaignOptionsDialogMode} defining the behavior of the dialog
*/
public CampaignOptionsDialog(final JFrame frame, final Campaign campaign, @Nullable CampaignPreset preset,
CampaignOptionsDialogMode mode) {
super(frame, true, resources, "CampaignOptionsDialog", "campaignOptions.title");
Expand All @@ -77,15 +113,31 @@ public CampaignOptionsDialog(final JFrame frame, final Campaign campaign, @Nulla
setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
}

/**
* Indicates whether the dialog was canceled by the user.
*
* @return {@code true} if the user canceled the dialog, {@code false} otherwise
*/
public boolean wasCanceled() {
return wasCanceled;
}

/**
* Creates the central pane of the dialog, which contains the campaign options UI.
*
* @return a {@link Container} representing the center pane of the dialog
*/
@Override
protected Container createCenterPane() {
return campaignOptionsPane;
}

/**
* Creates the button panel for the dialog, allowing the user to apply settings,
* load and save presets, or cancel the dialog.
*
* @return a {@link JPanel} representing the button panel
*/
@Override
protected JPanel createButtonPanel() {
final JPanel pnlButtons = new JPanel(new GridLayout(1, 0));
Expand Down Expand Up @@ -121,6 +173,10 @@ protected JPanel createButtonPanel() {
return pnlButtons;
}

/**
* Handles the "Save Preset" button action. Opens a dialog to create a new preset and
* save the campaign configuration to a file if confirmed.
*/
private void btnSaveActionPerformed() {
final CreateCampaignPreset createCampaignPresetDialog
= new CreateCampaignPreset(null, campaign, null);
Expand All @@ -140,6 +196,11 @@ private void btnSaveActionPerformed() {
FileDialogs.saveCampaignPreset(null, preset).orElse(null));
}

/**
* Handles the "Load Preset" button action. Opens a preset selection dialog,
* and applies the selected preset to the current campaign options if a preset
* is selected and not canceled.
*/
private void btnLoadActionPerformed() {
final SelectPresetDialog presetSelectionDialog =
new SelectPresetDialog(null, true, false);
Expand All @@ -148,14 +209,19 @@ private void btnLoadActionPerformed() {
}
}

/**
* Applies a preset to the campaign options pane. This allows the user to quickly
* configure the campaign settings based on predefined presets.
*
* @param preset the {@link CampaignPreset} instance to apply
*/
public void applyPreset(CampaignPreset preset) {
campaignOptionsPane.applyPreset(preset);
}

/**
* Displays a promo introducing users to StratCon.
* This method shows the promo only when the Campaign Options pane is closed
* and the current day is the first day of the campaign.
* Displays a promo notice for StratCon functionality when the campaign options dialog
* is closed if the campaign is starting on the first day, and StratCon is enabled.
*/
private void showStratConNotice() {
// we don't store whether this dialog has previously appeared,
Expand Down
94 changes: 78 additions & 16 deletions MekHQ/src/mekhq/gui/campaignOptions/CampaignOptionsPane.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,30 @@
import static java.lang.Math.round;
import static mekhq.campaign.force.CombatTeam.recalculateCombatTeams;
import static mekhq.gui.campaignOptions.CampaignOptionsDialog.CampaignOptionsDialogMode.ABRIDGED;
import static mekhq.gui.campaignOptions.CampaignOptionsDialog.CampaignOptionsDialogMode.STARTUP;
import static mekhq.gui.campaignOptions.CampaignOptionsUtilities.createSubTabs;

/**
* The {@code CampaignOptionsPane} class represents a tabbed pane used for displaying
* and managing various campaign options in MekHQ. It organizes these options
* into tabs and sub-tabs, enabling users to configure different aspects of a campaign.
* This component serves as the central UI for campaign settings management.
*
* <p>
* The pane is initialized with a {@link Campaign} instance, which provides the campaign's
* data and allows options to be applied directly to the active campaign.
* The dialog supports multiple modes, such as {@code NORMAL}, {@code ABRIDGED},
* and {@code STARTUP}, to determine the level of detail and features shown.
* </p>
*
* <h3>Key Features:</h3>
* <ul>
* <li>Organizes options into logical groups, such as General, Human Resources,
* Advancement, Logistics, and Operations.</li>
* <li>Supports loading and applying campaign presets for streamlined configuration.</li>
* <li>Dynamically handles UI scaling and scrolling speed based on environment properties.</li>
* <li>Allows scalability for future addition of new campaign settings.</li>
* </ul>
*/
public class CampaignOptionsPane extends AbstractMHQTabbedPane {
private static final String RESOURCE_PACKAGE = "mekhq/resources/CampaignOptionsDialog";
private static final ResourceBundle resources = ResourceBundle.getBundle(RESOURCE_PACKAGE);
Expand All @@ -68,6 +89,15 @@ public class CampaignOptionsPane extends AbstractMHQTabbedPane {
private MarketsTab marketsTab;
private RulesetsTab rulesetsTab;

/**
* Constructs a {@code CampaignOptionsPane} for managing campaign settings.
* This initializes the tabbed pane and populates it with categories and sub-tabs
* based on the provided {@link Campaign} instance and dialog mode.
*
* @param frame the parent {@link JFrame} for this pane
* @param campaign the {@link Campaign} object representing the current campaign
* @param mode the {@link CampaignOptionsDialogMode} for configuring the pane's behavior
*/
public CampaignOptionsPane(final JFrame frame, final Campaign campaign, CampaignOptionsDialogMode mode) {
super(frame, resources, "campaignOptionsDialog");
this.campaign = campaign;
Expand All @@ -77,6 +107,11 @@ public CampaignOptionsPane(final JFrame frame, final Campaign campaign, Campaign
initialize();
}

/**
* Initializes the campaign options pane by creating all parent tabs and adding
* sub-tabs for various campaign settings categories. Dynamically adjusts tab fonts
* and layout based on UI scaling settings.
*/
@Override
protected void initialize() {
double uiScale = 1;
Expand All @@ -101,10 +136,12 @@ protected void initialize() {
}

/**
* Creates a tab and adds it to the TabbedPane.
* Adds a new tab to the pane. Wrapper method for adding a resource-labeled tab
* containing a {@link JScrollPane} to the campaign options pane. Dynamically adjusts font size
* for consistent scaling across all UI elements.
*
* @param resourceName the name of the resource used to create the tab's title
* @param tab the tab to be added
* @param resourceName the resource string key to locate the tab title
* @param tab the {@link JTabbedPane} to add as content for the tab
*/
private void createTab(String resourceName, JTabbedPane tab) {
JScrollPane tabScrollPane = new JScrollPane(tab);
Expand All @@ -128,9 +165,10 @@ private void createTab(String resourceName, JTabbedPane tab) {
}

/**
* Creates the General tab.
* Creates the panel for general campaign options. Loads settings for general preferences
* and initializes it with current campaign options.
*
* @return a {@link JScrollPane} containing the General tab
* @return a {@link JScrollPane} containing the general tab panel
*/
private JScrollPane createGeneralTab() {
generalTab = new GeneralTab(campaign, getFrame());
Expand All @@ -141,14 +179,10 @@ private JScrollPane createGeneralTab() {
}

/**
* The `createHumanResourcesParentTab` method creates and returns a `JTabbedPane` object,
* which represents the overarching "Human Resources" tab in the user interface.
* <p>
* Under the "Human Resources" tab, there are several sub-tabs for different categories, including
* Personnel, Biography, Relationships, and Turnover and Retention. Each sub-tab contains various
* settings related to its category.
* Creates the "Human Resources" parent tab. This tab organizes related sub-tabs concerning
* personnel management, relationships, turnover, and biography options.
*
* @return JTabbedPane representing the "Human Resources" tab.
* @return a {@link JTabbedPane} containing sub-tabs for the human resources category
*/
private JTabbedPane createHumanResourcesParentTab() {
// Parent Tab
Expand Down Expand Up @@ -211,6 +245,12 @@ private JTabbedPane createHumanResourcesParentTab() {
return humanResourcesParentTab;
}

/**
* Creates the "Advancement" parent tab. This tab organizes related sub-tabs for awards,
* skill randomization, general skill management, and special pilot abilities (SPAs).
*
* @return a {@link JTabbedPane} containing sub-tabs for the advancement category
*/
private JTabbedPane createAdvancementParentTab() {
// Parent Tab
JTabbedPane advancementParentTab = new JTabbedPane();
Expand Down Expand Up @@ -255,10 +295,10 @@ private JTabbedPane createAdvancementParentTab() {
}

/**
* This `createEquipmentAndSuppliesParentTab` method creates and returns a `JTabbedPane` object.
* This represents the "Logistics and Maintenance" parent tab in the user interface.
* Creates the "Logistics and Maintenance" parent tab. This tab organizes related sub-tabs
* for equipment acquisition, repair, maintenance, and supply management options.
*
* @return JTabbedPane representing the "Logistics and Maintenance" tab.
* @return a {@link JTabbedPane} containing sub-tabs for the logistics and maintenance category
*/
private JTabbedPane createEquipmentAndSuppliesParentTab() {
// Parent Tab
Expand Down Expand Up @@ -293,6 +333,12 @@ private JTabbedPane createEquipmentAndSuppliesParentTab() {
return equipmentAndSuppliesParentTab;
}

/**
* Creates the "Strategic Operations" parent tab. This tab organizes related sub-tabs for
* finances, market management (personnel, units, and contracts), and ruleset configuration.
*
* @return a {@link JTabbedPane} containing sub-tabs for the strategic operations category
*/
private JTabbedPane createStrategicOperationsParentTab() {
// Parent Tab
JTabbedPane strategicOperationsParentTab = new JTabbedPane();
Expand Down Expand Up @@ -336,6 +382,15 @@ private JTabbedPane createStrategicOperationsParentTab() {
return strategicOperationsParentTab;
}

/**
* Applies the currently configured campaign options to the active {@link Campaign}.
* This method processes all tabs in the dialog, applying the options to the campaign
* in logical order (e.g., "General" first, followed by other categories).
*
* @param preset an optional {@link CampaignPreset} used to override campaign options
* @param isStartUp specifies whether this is run as part of a startup initialization
* @param isSaveAction determines if this action is saving options to a preset
*/
public void applyCampaignOptionsToCampaign(@Nullable CampaignPreset preset, boolean isStartUp,
boolean isSaveAction) {
CampaignOptions options = this.campaignOptions;
Expand Down Expand Up @@ -381,6 +436,13 @@ public void applyCampaignOptionsToCampaign(@Nullable CampaignPreset preset, bool
}
}

/**
* Applies the values from a {@link CampaignPreset} to all tabs in the dialog. This propagates
* preset-specific configuration to all associated components and sub-tabs, including
* campaign-related properties such as dates, factions, and skills.
*
* @param campaignPreset the {@link CampaignPreset} containing the preset options to apply
*/
public void applyPreset(@Nullable CampaignPreset campaignPreset) {
if (campaignPreset == null) {
return;
Expand Down
Loading

0 comments on commit f1bb5cf

Please sign in to comment.