# Encounter Builder Modules

## encounter_builder module

Contains definition of the encounter builder window.

If run as the main script, will create and display a window allowing the user to edit, save, and export an encounter of monsters to a file.

class `encounter_builder.``EncounterBuilderFrame`

  Bases: `ui_helpers.BuilderFrame`

  Main window of the application if running as an encounter builder.

  `__init__`()

    Constructor for the window. Sets up and initializes UI elements.

  `__module__` = 'encounter_builder'
  `_cb_close`(event: wx._core.CloseEvent)

    Callback to handle closing the window.

    Parameters: | event – CloseEvent object containing details about the event.

  `_cb_export_rtf`(event: wx._core.CommandEvent)

    Callback handling the user wanting to export the monster to an RTF file.

    Parameters: | event – CommandEvent object containing details about the event.

  `_cb_new`(event: wx._core.CommandEvent)

    Callback handling the user wanting to create a new monster.

    Parameters: | event – CommandEvent object containing details about the event.

  `_cb_open`(event: wx._core.CommandEvent)

    Callback handling the user wanting to open a monster file to edit.

    Parameters: | event – CommandEvent object containing details about the event.

  `_cb_resize`(event: wx._core.SizeEvent)

    Callback to handle resizing the window.

    Parameters: | event – SizeEvent object containing details about the event.

  `_cb_save`(event: wx._core.CommandEvent)

    Callback handling the user wanting to (re-)save the monster to a file.

    Parameters: | event – CommandEvent object containing details about the event.

  `_cb_save_as`(event: wx._core.CommandEvent)

    Callback handling the user wanting to save the monster to a file.

    Parameters: | event – CommandEvent object containing details about the event.

  `_initialize`()

    Gives UI elements their initial values.

  `_setup_ui`()

    Sets up and places all UI elements on the window.

  `clear_status`()

    Forcibly clears the contents of the status bar and cancels any waiting status clearing timer.

  `new`()

    Resets all controls to default values, clears out any buildable lists or special properties.

  `open`()

    Opens a saved encounter file for editing, replacing all the contents of this frame with whatever’s in the file.

  `repaint`()

    Sizes and “redraws” the window.

  `resize`()

    Handles the window being resized by telling all children to rearrange themselves.

    The encounter panel’s resize() method automatically calls our repaint(), so we can omit it here.

  `set_status`(status_text: str, clear_later: bool = True)

    Sets the status bar to the given text string and sets a timer to clear the status bar later.

    Parameters: | status_text – The text to show on the status bar. clear_later – If True (the default) will set a timer to clear the status bar later, otherwise will leave the text there.

class `encounter_builder.``EncounterBuilderPanel`(frame: ui_helpers.BuilderFrame, parent: wx._core.Window)

  Bases: `wx._core.Panel`

  Main panel for the encounter builder.

  `XP_BUDGET_STR` = 'Encounter XP Budget ({0:d}):'
  `XP_USED_STR` = 'Encounter XP ({0:d}):'
  `__init__`(frame: ui_helpers.BuilderFrame, parent: wx._core.Window)

    Constructor for the window. Sets up and initializes UI elements. :param frame: EncounterBuilderFrame object that will hold this panel. Used to reference frame controls like the status bar. :param parent: The owner of this panel.

  `__module__` = 'encounter_builder'
  `_cb_level_changed`(event: wx._core.CommandEvent)

    Callback handling when the user changes the encounter level.

    Parameters: | event – CommandEvent containing details about the event.

  `_cb_player_count_changed`(event: wx._core.CommandEvent)

    Callback handling when the user changes the number of players in the encounter.

    Parameters: | event – CommandEvent containing details about the event.

  `_cb_xp_budget_clicked`(event: wx._core.CommandEvent)

    Callback handling when the user (un)checks the custom XP budget checkbox.

    Parameters: | event – CommandEvent containing details about the event.

  `_cb_xp_used_clicked`(event: wx._core.CommandEvent)

    Callback handling when the user (un)checks the custom XP checkbox.

    Parameters: | event – CommandEvent containing details about the event.

  `_initialize`()

    Gives UI elements their initial values.

  `_setup_ui`()

    Sets up and places all UI elements on the window.

  `export_to_rtf`()

    Exports the data for this encounter to an RTF file.

  `recalculate`()

    Calculates all derived and suggested values for the encounter based on current state.

  `repaint`()

    Sizes and “redraws” the panel. Also calls up to the containing frame’s repaint() so it can adjust if this panel’s size changes as a result of the Layout() and Fit() calls.

  `reset`()

    Removes all monsters from the encounter and sets the encounter properties back to their defaults.

  `resize`()

    Calls Layout() for everything and then Fit() to ensure everything has the correct UI size.

  `save`() → int

    Saves the data of the current encounter to a file. Uses the last file saved to, or asks the user for a file name if no file has been specified yet. Saves all monsters in the encounter as well, and only saves the encounter if all monsters saved properly.

    Returns: | 1 if all files saved successfully, 0 if a save was canceled, -1 if a save failed.

  `save_as`(filename: str = '') → int

    Saves the data of the current encounter to a file. Prompts the user for a file name to save to if filename is blank. Saves all monsters in the encounter as well, and only saves the encounter if all monsters saved properly.

    Returns: | 1 if all files saved successfully, 0 if a save was canceled, -1 if a save failed.

  `set_label_vals`()

    Sets the “suggested” values and other hints in labels based on current calculated values.

  `update_ui`()

    Updates all UI fields after an encounter gets loaded or some UI-changing event happens.

`encounter_builder.``main`(argv)

  Main function to run the program as an encounter editor.

  Parameters: | argv – Command-line args as sys.argv would provide.

## encounter_ui_helpers module

Contains helper data, functions, and classes for Monster Builder UI creation & management.

class `encounter_ui_helpers.``DummyMonsterBuilderPanel`(frame: ui_helpers.BuilderFrame, parent: wx._core.Window)

  Bases: `wx._core.Panel`

  Dummy panel to use in place of a MonsterBuilderPanel when no monster is available.

  `__init__`(frame: ui_helpers.BuilderFrame, parent: wx._core.Window)

    Constructor for the dummy monster window. Sets up and initializes UI elements.

    Parameters: | frame – MonsterBuilderFrame or EncounterBuilderFrame object that will hold this panel. Used to reference frame controls like the status bar. parent – The owner of this panel.

  `__module__` = 'encounter_ui_helpers'

class `encounter_ui_helpers.``MonsterListItemControls`(manage_panel: encounter_ui_helpers.MonsterManagementPanel, parent: wx._core.Window, monster_id: int, monster_name: str, quantity: int = 1, orient: int = 8)

  Bases: `wx._core.BoxSizer`

  Specialized BoxSizer containing the controls needed to display a monster in the monster list.

  `__init__`(manage_panel: encounter_ui_helpers.MonsterManagementPanel, parent: wx._core.Window, monster_id: int, monster_name: str, quantity: int = 1, orient: int = 8)

    Creates a new set of monster list item controls in a sizer. All controls get the wx naming convention “[Control]:[Index]”, where [Control] is what the control represents, and [Index] is the numeric index of the monster in the list.

    Parameters: | manage_panel – MonsterManagementPanel that will manage these controls. Used for callbacks. parent – The owner of the new controls. monster_id – The numeric ID of the monster in the encounter list. monster_name – The monster’s initial name. quantity – The initial number of monsters of this type in the encounter, default 1. orient – The orientation of the sizer, default HORIZONTAL.

  `__module__` = 'encounter_ui_helpers'
  `_cb_include_clicked`(event: wx._core.CommandEvent)

    Event handler when the monster is (un)checked to be excluded/included in the encounter.

    Parameters: | event – CommandEvent containing details about the event.

  `_cb_move_down`(event: wx._core.CommandEvent)

    Callback handling moving a monster down in the order.

    Parameters: | event – CommandEvent object containing details about the event.

  `_cb_move_up`(event: wx._core.CommandEvent)

    Callback handling moving a monster up in the order.

    Parameters: | event – CommandEvent object containing details about the event.

  `_cb_name_clicked`(event: wx._core.CommandEvent)

    Event handler when the monster is selected to be the current monster to view/edit.

    Parameters: | event – CommandEvent containing details about the event.

  `_cb_quantity_changed`(event: wx._core.SpinEvent)

    Event handler when the monster’s quantity is changed.

    Parameters: | event – SpinEvent containing details about the event.

  `_cb_remove_monster`(event: wx._core.CommandEvent)

    Callback handling removing a monster from the monster list.

    Parameters: | event – CommandEvent object containing details about the event.

  `cb_monster_name_changed`(event: wx._core.CommandEvent)

    Event handler when the monster’s name gets changed. Public because it gets connected directly to the monster’s name field.

    Parameters: | event – CommandEvent containing details about the event.

  `change_name`(new_name: str)

    Changes the name of the monster in the list to the new value.

    Parameters: | new_name – New name for the monster.

  `destroy`()

    Destroys this collection of controls and then itself.

  `get_quantity`() → str

    Returns the string contents of the quantity textbox.

  `get_quantity_int`() → int

    Returns the integer-cast contents of the quantity textbox, or 0 if its contents aren’t an integer.

  `is_included`() → bool

    Returns True if the monster is checked (included in the encounter), False if not.

  `is_selected`()

    Returns True if the monster is selected as the active viewing/editing monster, False if not.

  `monster_quantity_changed`()

    Handles recalculating values & and adjusting UI when the quantity of monsters in an encounter changes.

  `repaint`()

    Adjusts the display of the child controls based on what’s selected.

  `reset_values`()

    Reverts to the default of selecting the monster and having its quantity be 1.

  `set_monster_id`(new_monster_id: int)

    Sets the monster ID to the new ID, adjusting control names accordingly.

    Parameters: | new_monster_id – Integer ID to assign to this monster.

  `set_selected`(selected: bool = True)

    Helper method to (de)select this monster’s radio button.

    Parameters: | selected – Selects the radio button if True (the default), deselects if False.

  `update_ui`(recalculate=True)

    Checks if the monster’s checkbox is checked or not. Changes whether or not the text box is editable, and has the management panel recalculate its used XP budget accordingly.

    Parameters: | recalculate – Will recalculate encounter stats if True, will skip it if False.

class `encounter_ui_helpers.``MonsterManagementPanel`(encounter_panel: encounter_builder.EncounterBuilderPanel, parent: wx._core.Window, label: str = 'Encounter Monsters')

  Bases: `wx._core.Panel`

  Specialized Panel containing & managing controls to display the list of encounter monsters.

  Access controls for each monster by doing something like this.monster_ctrl[MONSTER_ID].

  `__init__`(encounter_panel: encounter_builder.EncounterBuilderPanel, parent: wx._core.Window, label: str = 'Encounter Monsters')

    Creates the controls to display a list of monsters in the encounter.

    Parameters: | encounter_panel – EncounterBuilderPanel object that will hold this panel. Used to reference callbacks and other controls. parent – The owner of this panel. label – The name to show for the panel’s box.

  `__module__` = 'encounter_ui_helpers'
  `_add_monster`(monster_panel: monster_builder.MonsterBuilderPanel, update_ui: bool = True) → encounter_ui_helpers.MonsterListItemControls

    Takes a (presumably newly created/loaded) MonsterBuilderPanel, adds it to the encounter monster data structures, and adds controls to manage it to the bottom of the mosnter list. Indended to be a helper method to new_monster() and load_monster().

    Parameters: | update_ui – If True, will update the monster list appearance. Will skip doing so if False.
    Returns: | Tuple of the monster’s ID and the MonsterListItemControls object created as part of making the new monster.

  `_cb_load_monster`(event)

    Callback handling when the user wants to load a monster from file & add it to the list.

    Parameters: | event – CommandEvent object containing details about the event.

  `_cb_new_monster`(event)

    Callback handling when the user wants to add a new monster to the list.

    Parameters: | event – CommandEvent object containing details about the event.

  `_get_next_monster_id`(monster_id)

    Finds the next monster ID after the given one.

    Parameters: | monster_id – ID of the “current” monster.
    Returns: | The next highest monster ID in the list, or -1 if there is no ID after the given one.

  `_get_previous_monster_id`(monster_id)

    Finds the previous monster ID before the given one.

    Parameters: | monster_id – ID of the “current” monster.
    Returns: | The next lowest monster ID in the list, or -1 if there is no ID before the given one.

  `_organize_monster_ctrls`(update_ui: bool = True)

    Ensures that the list of monsters are displayed in order.

    Parameters: | update_ui – Will update the monster list display if True, will skip doing so if False.

  `get_active_id`() → str

    Retrieves the current ID of the active monster.

    Returns: | String ID of the active monster, or “-1” if none are selected.

  `get_active_id_int`() → int

    Retrieves the current integer ID of the active monster.

    Returns: | Integer ID of the active monster, or -1 if none are selected.

  `load_monster`(monster_dict: Union[dict, NoneType] = None, file_name: str = '', start_dir: Union[str, NoneType] = None, select_new_monster=True) → Union[encounter_ui_helpers.MonsterListItemControls, NoneType]

    Creates a monster builder panel from file or from a pre-supplied monster dictionary (as from file_utils._monster_to_dict()) and adds controls to manage it to the bottom of the mosnter list.

    Parameters: | monster_dict – Dictionary (as file_utils._monster_to_dict()) to load monster from. Will load from file if None. file_name – Path & file name to load monster from, will open an Open File dialog if blank. start_dir – The path to use as the “base path” when trying to load the file given in file_name. Defaults to current directory if not supplied. select_new_monster – If True (the default), will auto-select the loaded monster as the “active” monster.
    Returns: | The MonsterListItemControls object created as part of making the new monster.

  `move_monster_down`(monster_id: int)

    Moves the monster with the given ID down one slot on the list of monsters.

    Parameters: | monster_id – Integer ID of the monster to move.

  `move_monster_up`(monster_id: int)

    Moves the monster with the given ID up one slot on the list of monsters.

    Parameters: | monster_id – Integer ID of the monster to move.

  `new_monster`(select_new_monster=True) → encounter_ui_helpers.MonsterListItemControls

    Creates a new monster builder panel and adds controls to manage it to the bottom of the mosnter list.

    Parameters: | select_new_monster – If True (the default), will auto-select the new monster as the “active” monster.
    Returns: | The MonsterListItemControls object created as part of making the new monster.

  `next_monster_id` = 0
  `recalculate`()

    Calculates encounter XP based on monster XP & quantities.

  `remove_monster`(monster_id: int, prompt: bool = False)

    Removes a monster from the monster list.

    Parameters: | monster_id – The ID of the monster to remove. prompt – If True, will show a message box asking the user to confirm removing the monster. Default False.

  `repaint`()

    Makes all the monster list controls repaint themselves.

    Returns: |

  `reset`()

    Removes all monster controls from the list of monsters and resets monster management options.

  `reset_values`()

    Resets the monster controls to default, making them all included in the encounter w/ quantity 1, and selecting the first in the list.

  `select_monster`(monster_id: int)

    Sets the active viewed/edited monster to the one with the given ID, deselects the others in the list.

    Parameters: | monster_id – Integer monster ID to select.

  `select_replacement_monster`()

    Selects the next monster down in the list, or the previous if there is no next monster, or the blank monster if there aren’t any others to select.

    Assumed this is called during a remove_monster() or equivalent call.

  `should_monsters_save_to_files`() → bool

    Convenience method to check which monster saving method the user has selected.

    Returns: | True if monsters should save to their own files, False if they should only be saved in the encounter file.

  `update_ui`()

    Updates the display and calculations of all monster controls, presumably after something like a monster being loaded from file or the monster order changing externally.