Package mekhq.gui.baseComponents.immersiveDialogs

Class ImmersiveDialogCore

java.lang.Object
java.awt.Component
java.awt.Container
java.awt.Window
java.awt.Dialog
javax.swing.JDialog
mekhq.gui.baseComponents.immersiveDialogs.ImmersiveDialogCore
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants
Direct Known Subclasses:
DefectionOffer, GrayMondayDialog, ImmersiveDialogSimple, MercenaryAuctionDialog, MissionEndPrisonerDefectorDialog, MissionEndPrisonerDialog, NewsDialog, PrisonerEscapeeScenarioDialog, PrisonerEventDialog, PrisonerEventResultsDialog, PrisonerRansomEventDialog, PrisonerWarningDialog, PrisonerWarningResultsDialog, ReplacementLimbDialog, VocationalExperienceAwardDialog
public class ImmersiveDialogCore extends JDialog
An immersive dialog used in MekHQ to display interactions between speakers, messages, and actions. The dialog supports entities such as speakers, campaign, buttons, and optional details for enhanced storytelling.

It allows displaying one or more speakers in a dialog alongside a central message, optional out-of-character notes, and UI buttons for user interaction.

The dialog is flexible in terms of panel layout and width adjustments, allowing for dynamic configurations based on the input parameters.

See Also:

  • Field Details

  • Constructor Details

    • ImmersiveDialogCore

      public ImmersiveDialogCore(Campaign campaign, @Nullable Person leftSpeaker, @Nullable Person rightSpeaker, String centerMessage, List<ImmersiveDialogCore.ButtonLabelTooltipPair> buttons, @Nullable String outOfCharacterMessage, @Nullable Integer centerWidth, boolean isVerticalLayout, @Nullable JPanel supplementalPanel, @Nullable ImageIcon imageIcon, boolean isModal)
      Constructs and initializes an immersive dialog with configurable layouts, speakers, actions, and messages.

      This dialog is designed to provide a rich, immersive interface featuring optional speakers on the left and right, a central message panel with configurable width, a spinner panel, and a list of actionable buttons. An optional out-of-character message can also be displayed below the buttons.

      Parameters:
      campaign - The Campaign instance tied to the dialog, providing contextual information.
      leftSpeaker - Optional left-side Person; use null if no left speaker is present.
      rightSpeaker - Optional right-side Person; use null if no right speaker is present.
      centerMessage - The main String message displayed in the center panel of the dialog.
      buttons - A List of ImmersiveDialogCore.ButtonLabelTooltipPair instances representing actions available in the dialog (displayed as buttons). The default option is used if the user closes or cancels the dialog.
      outOfCharacterMessage - An optional String message displayed below the buttons; use null if not applicable.
      centerWidth - An optional width for the center panel; uses the default value if null.
      isVerticalLayout - A boolean determining the button layout: true for vertical stacking, false for horizontal layout.
      supplementalPanel - An optional JPanel containing a JSpinner and/or a MMComboBox to be displayed in the center panel; use null if not applicable.

  • Method Details

    • getDialogChoice

      public int getDialogChoice()
      Retrieves the user's selected dialog choice.

      Usage: This allows us to keep function code out of the GUI element, making it far easier to test what's happening for any given option selection. Create the dialog, as normal, then fetch whatever decision the user made and perform any code actions required.

      Returns:
      An integer representing the index of the button selected by the user. If the dialog is closed without selection, this will return the defaultChoiceIndex defined during construction.

    • setDialogChoice

      public void setDialogChoice(int dialogChoice)
      Sets the dialog choice for the current object.
      Parameters:
      dialogChoice - The integer value representing the dialog choice to set.

    • getSpinnerValue

      public int getSpinnerValue()
      Retrieves the current value of the spinner.

      Note: will return 0 if the dialog does not contain a JSpinner in the supplemental panel.

      Returns:
      The integer value of the spinner.

    • setSpinnerValue

      public void setSpinnerValue(int spinnerValue)
      Sets a new value for the spinner.

      Note: will return 0 if the dialog does not contain a MMComboBox in the supplemental panel.

      Parameters:
      spinnerValue - The integer value to set for the spinner.

    • getComboBoxChoiceIndex

      public int getComboBoxChoiceIndex()
      Retrieves the current index of the combo box choice.
      Returns:
      The integer value representing the current selected index of the combo box.

    • setComboBoxChoiceIndex

      public void setComboBoxChoiceIndex(int comboBoxChoiceIndex)
      Sets a new index for the combo box choice.
      Parameters:
      comboBoxChoiceIndex - The integer value to set as the combo box's selected index.

    • getPADDING

      protected int getPADDING()
      Retrieves the padding value defined in this object.
      Returns:
      The padding value as an integer.

    • setTitle

      protected void setTitle()
      Sets the title of the dialog window using localized text.

    • handleImmersiveHyperlinkClick

      public static void handleImmersiveHyperlinkClick(JDialog parent, Campaign campaign, String reference)
      Handles hyperlink clicks from HTML content dialog.

      This method processes the provided hyperlink reference to determine the type of command and executes the appropriate action. It supports commands for displaying a glossary entry or focusing on a specific person in the campaign.

      Supported Commands:
      • GLOSSARY_COMMAND_STRING: Opens a new GlossaryDialog to display the referenced glossary entry.
      • PERSON_COMMAND_STRING: Focuses on a specific person in the campaign using their unique identifier (UUID). If using this, you will need to ensure your dialog has modal set to false

      If the command is not recognized, no action is performed.

      Parameters:
      parent - The parent JDialog instance to associate with the new dialog, if created.
      campaign - The Campaign instance that contains application and campaign data.
      reference - The hyperlink reference used to determine the command and additional information (e.g., a specific glossary term key or a person's UUID).

    • hyperlinkEventListenerActions

      protected void hyperlinkEventListenerActions(HyperlinkEvent evt)
      Handles actions triggered by hyperlink events, such as clicks on hyperlinks. This method identifies when the event type is HyperlinkEvent.EventType.ACTIVATED and processes the event accordingly by delegating to the specified handler.
      Parameters:
      evt - the HyperlinkEvent which contains details about the hyperlink interaction. It could represent events such as entering, exiting, or activating a hyperlink.

    • populateButtonPanel

      protected JPanel populateButtonPanel(List<ImmersiveDialogCore.ButtonLabelTooltipPair> buttons, boolean isVerticalLayout, @Nullable JPanel supplementalPanel)
      Populates a button panel with a list of buttons, each defined by a label and an optional tooltip.

      This method dynamically creates buttons based on the provided ImmersiveDialogCore.ButtonLabelTooltipPair objects. Each button is added to the specified JPanel (`buttonPanel`) and arranged according to the selected layout style (`isVerticalLayout`).

      Parameters:
      buttons - A List of ImmersiveDialogCore.ButtonLabelTooltipPair instances, where each pair defines the label and tooltip for a button.
      isVerticalLayout - A boolean value indicating the layout style: true for vertical stacking, false for horizontal arrangement.

    • buildSpeakerPanel

      protected JPanel buildSpeakerPanel(@Nullable Person speaker, Campaign campaign)
      Builds a panel for displaying a speaker's image, name, and role.

      This method creates a vertically stacked panel that includes the person's icon, title, and any additional descriptive information (e.g., roles, forces, or campaign affiliations).

      Parameters:
      speaker - The character shown in the dialog, can be null for no speaker
      campaign - The current campaign.
      Returns:
      A JPanel forming the speaker's dialog box.

    • getSpeakerDescription

      public static StringBuilder getSpeakerDescription(Campaign campaign, Person speaker, String speakerName)
      Assembles the speaker description based on the provided speaker and campaign details.

      The description includes:

      • The speaker's title and roles (both primary and secondary, if applicable).
      • The force associated with the speaker.
      • A fallback to the campaign name if the speaker is not available.
      Parameters:
      campaign - The current campaign.
      speaker - The Person representing the speaker, or null to use fallback data.
      speakerName - The name/title to use for the speaker if one exists.
      Returns:
      A StringBuilder containing the formatted HTML description of the speaker.

    • getSpeakerIcon

      @Nullable public static ImageIcon getSpeakerIcon(@Nullable Campaign campaign, @Nullable Person speaker)
      Retrieves the speaker's icon for dialogs. If no speaker is supplied, the faction icon for the campaign is returned instead.
      Parameters:
      campaign - the Campaign instance containing the faction icon; can be null to use a default image.
      speaker - the Person serving as the speaker for the dialog; can be null.
      Returns:
      an ImageIcon for the speaker's portrait, or the faction icon if the speaker is null.