Package megamek.common

Class Report

java.lang.Object
megamek.common.Report
All Implemented Interfaces:
Serializable, ReportEntry
public class Report extends Object implements ReportEntry
Report encapsulates a single game event report in MegaMek.

Each Report contains message text, formatting information, visibility settings, and the data needed to display the report to players. Reports are typically created by the server, then transmitted to clients for display.

The actual text of reports comes from the report-messages.properties resource file. Each report is identified by a numeric ID that corresponds to a message template in this file. The template can contain tags that will be replaced with data provided by the Report object:

  • <data> - Replaced with values added via add(String) or similar methods
  • <msg:id1,id2> - Conditionally shows one of two messages based on a boolean value
  • <list> - Lists all remaining data values, comma-separated
  • <newline> - Inserts a line break

Example usage: 

 // Create a report with ID 3455
 Report r = Report.subjectReport(3455, entity.getId());
 r.indent()
  .addDesc(entity)
  .add(6)
  .choose(true);
 vPhaseReport.addElement(r);

The corresponding entry in report-messages.properties might be: 

 3455::<data> (<data>) does <data> damage to the <msg:3456,3457>.
 3456::tank
 3457::building

This would produce output like: "Crusader (Bob) does 6 damage to the tank."

Reports can be public (visible to all) or hidden based on subject entity or player. They support HTML formatting, entity links, tooltips, and other rich text features.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_INDENTATION
    Number of spaces to use per indentation level.
    static final String
    ENTITY_LINK
    Prefix for entity hyperlinks
    Vector<Integer>
    extensions
    Additional sections to add to raw message prior to inserting tags
    static final int
    HIDDEN
    Report is only visible to those players who can see the subject.
    static int
    HIDDEN_ENTITY_NUM
     
    static final int
    MAX_INDENTATION
    Number of indentation levels allowed.
    int
    messageId
    Required - associates this object with its text.
    int
    newlines
    The number of newlines to add at the end of this report.
    static final int
    OBSCURED
    Report Type: visible to all players, but all data marked for obscuration remains hidden.
    static final String
    OBSCURED_STRING
    The string that appears in the report to obscure certain information.
    int
    player
    The player this report concerns, if applicable.
    static final int
    PLAYER
    Messages which should be sent only to the player indicated by "player"
    static final int
    PUBLIC
    Report Type: visible to all players.
    int
    subject
    The entity this report concerns, if applicable.
    static final int
    TESTING
    Testing only - remove me later.
    static final String
    TOOLTIP_LINK
    Prefix for tooltip text
    int
    type
    How this report is handled when double-blind play is in effect.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Report()
    Default constructor, note that using this means the messageId field must be explicitly set.
    Report(int id)
    Create a new report associated with the given report text.
    Report(int id, int type)
    Create a new report associated with the given report text and having the given type.
    Report(Report r)
    Create a new report which is an exact copy of the given report.

  • Method Summary

    Modifier and Type
    Method
    Description
    Report
    add(int data)
    Add the given int to the list of data that will be substituted for the <data> tags in the report.
    Report
    add(int data, boolean obscure)
    Add the given int to the list of data that will be substituted for the <data> tags in the report, and mark it as double-blind sensitive information if obscure is true.
    Report
    add(String data)
    Add the given String to the list of data that will be substituted for the <data> tags in the report.
    Report
    add(String data, boolean obscure)
    Add the given String to the list of data that will be substituted for the <data> tags in the report, and mark it as double-blind sensitive information if obscure is true.
    Report
    add(String data, String translate)
    Add the given string to the list of data that will be substituted for the <data> tags in the report.
    Report
    add(Roll diceRoll)
     
    Report
    add(TargetRoll targetRoll)
    Adds target roll to report with details available as a tooltip
    Report
    addDataWithTooltip(Integer data, String tooltip)
     
    Report
    addDataWithTooltip(String data, String tooltip)
    Adds a field to the report with additional data available as a tooltip
    Report
    addDesc(Entity entity)
    Shortcut method for adding entity name and owner data at the same time.
    Report
    addEntityName(Entity entity)
    Adds a unit's linked name alone, for a name inside a sentence: no owner, no crew nickname and no sprite, unlike addDesc(Entity).
    Report
    addEntityName(Entity entity, String displayName)
    Adds a unit's linked name alone, shown as the given text: no owner, no crew nickname and no sprite.
    static void
    addNewline(Vector<Report> v)
    Adds a newline to the last report in the given Vector.
    void
    addObscuredRecipient(String playerName)
    Internal method.
    ReportEntry
    addRoll(Roll roll)
    Adds the result of the given roll to this ReportEntry.
    String
    bgColor(Color color, String str)
    Deprecated, for removal: This API element is subject to removal in a future version.
    String
    bgColor(String hexColor, String str)
    Wraps text in a span with the given hex background color.
    static String
    bold(String str)
    Wraps text in a bold tag.
    Report
    choose(boolean choice)
    Indicate which of two possible messages should be substituted for the <msg:n,m> tag.
    int
    dataCount()
    Internal method.
    void
    extend(int id)
    Add an additional message id that will extend the base message
    String
    fgColor(Color color, String str)
    Wraps text in a span with the given foreground color.
    String
    fgColor(String hexColor, String str)
    Wraps text in a span with the given hex foreground color.
    Vector<Integer>
    getExtensions()
    Safety accessor for extensions
    void
    hideData(int index)
    Internal method.
    String
    href(String href, String str)
    Creates an HTML anchor tag.
    Report
    indent()
    Indent the report.
    Report
    indent(int n)
    Indent the report n times.
    static void
    indentAll(Vector<Report> reports, int amount)
    Sets the indentation for all reports of the given reports list to the given amount by calling indent(int)
    boolean
    isObscuredRecipient(String playerName)
    Internal method.
    boolean
    isValueObscured(int index)
    Internal method.
    Report
    makePublic()
    Set the report to be public (Report.PUBLIC).
    Report
    newLines(int newlines)
    Set the report to not add the given number of newlines at the end.
    Report
    noNL()
    Set the report to not add a newline at the end, so that the current line of text can be continued with another report.
    void
    obscureImg()
     
    static Report
    publicReport(int id)
    Returns a new report associated with the given report text (ID) and having the type Report.PUBLIC.
    void
    setShowImage(boolean showImage)
    Deprecated, for removal: This API element is subject to removal in a future version.
    static void
    setupStylesheet(JTextPane pane)
     
    static void
    setupStylesheet(StyleSheet styleSheet)
     
    String
    span(String name, String text)
    Wraps text in a span with the given class name.
    String
    span(String name, String text, String attributes)
     
    Report
    subject(int subjectId)
    Set the report's subject (Entity ID).
    static Report
    subjectReport(int id, int subjectId)
    Returns a new report associated with the given report text (ID) and having the given subject (Entity ID).
    String
    text()
    Get the report in its final form, with all the necessary substitutions made.
    String
    toString()
    Useful for debugging purposes.
    String
    warning(String text)
    Wraps text in a warning span.
    Report
    with(Entity entity)
    Set the report's subject and add its description.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • PUBLIC

      public static final int PUBLIC
      Report Type: visible to all players.
      See Also:

    • OBSCURED

      public static final int OBSCURED
      Report Type: visible to all players, but all data marked for obscuration remains hidden. Note: Not used at this time, since all reports are considered obscured unless explicitly marked public.
      See Also:

    • HIDDEN

      public static final int HIDDEN
      Report is only visible to those players who can see the subject. Note: Not used at this time, since all reports are considered obscured unless explicitly marked public.
      See Also:

    • TESTING

      public static final int TESTING
      Testing only - remove me later.
      See Also:

    • PLAYER

      public static final int PLAYER
      Messages which should be sent only to the player indicated by "player"
      See Also:

    • OBSCURED_STRING

      public static final String OBSCURED_STRING
      The string that appears in the report to obscure certain information.
      See Also:

    • DEFAULT_INDENTATION

      public static final int DEFAULT_INDENTATION
      Number of spaces to use per indentation level.
      See Also:

    • MAX_INDENTATION

      public static final int MAX_INDENTATION
      Number of indentation levels allowed. Currently, the same as the DEFAULT_INDENTATION value, to limit indentations to one level for a cleaner look of the report.
      See Also:

    • messageId

      public int messageId
      Required - associates this object with its text.

    • extensions

      public Vector<Integer> extensions
      Additional sections to add to raw message prior to inserting tags

    • newlines

      public int newlines
      The number of newlines to add at the end of this report. Defaults to one.

    • type

      public transient int type
      How this report is handled when double-blind play is in effect. See constants below for more details.

    • subject

      public transient int subject
      The entity this report concerns, if applicable. If this is left blank, then the report will be considered public.

    • player

      public transient int player
      The player this report concerns, if applicable. This should be filled in if this report is not public and still does not belong to a specific visible entity

    • HIDDEN_ENTITY_NUM

      public static int HIDDEN_ENTITY_NUM

  • Constructor Details

    • Report

      public Report()
      Default constructor, note that using this means the messageId field must be explicitly set.

    • Report

      public Report(int id)
      Create a new report associated with the given report text.
      Parameters:
      id - the int value of the report from report-messages.properties

    • Report

      public Report(int id, int type)
      Create a new report associated with the given report text and having the given type.
      Parameters:
      id - the int value of the report from report-messages.properties
      type - the constant specifying the visibility of the report (PUBLIC, OBSCURED, or HIDDEN)

    • Report

      public Report(Report r)
      Create a new report which is an exact copy of the given report.
      Parameters:
      r - the report to be copied

  • Method Details

    • publicReport

      public static Report publicReport(int id)
      Returns a new report associated with the given report text (ID) and having the type Report.PUBLIC.
      Parameters:
      id - the int value of the report from report-messages.properties
      Returns:
      A new Report

    • subjectReport

      public static Report subjectReport(int id, int subjectId)
      Returns a new report associated with the given report text (ID) and having the given subject (Entity ID). The Report will be the default type Report.HIDDEN.
      Parameters:
      id - the int value of the report from report-messages.properties
      subjectId - The Entity ID of the subject entity
      Returns:
      A new Report

    • makePublic

      public Report makePublic()
      Set the report to be public (Report.PUBLIC).
      Returns:
      This Report to allow chaining

    • newLines

      public Report newLines(int newlines)
      Set the report to not add the given number of newlines at the end.
      Returns:
      This Report to allow chaining

    • noNL

      public Report noNL()
      Set the report to not add a newline at the end, so that the current line of text can be continued with another report.
      Returns:
      This Report to allow chaining

    • extend

      public void extend(int id)
      Add an additional message id that will extend the base message

    • getExtensions

      public Vector<Integer> getExtensions()
      Safety accessor for extensions
      Returns:
      extensions Vector of integer values of report messages

    • subject

      public Report subject(int subjectId)
      Set the report's subject (Entity ID).
      Returns:
      This Report to allow chaining

    • with

      public Report with(Entity entity)
      Set the report's subject and add its description. This is equivalent to calling 
      
 report.subject(entity.getId());
 report.addDesc(entity);
      Typically used in reports that start with "<data> (<data>) ..."
      Returns:
      This Report to allow chaining

    • add

      public Report add(int data)
      Add the given int to the list of data that will be substituted for the <data> tags in the report. The order in which items are added must match the order of the tags in the report text.
      Parameters:
      data - the int to be substituted
      Returns:
      This Report to allow chaining

    • add

      public Report add(int data, boolean obscure)
      Add the given int to the list of data that will be substituted for the <data> tags in the report, and mark it as double-blind sensitive information if obscure is true. The order in which items are added must match the order of the tags in the report text.
      Parameters:
      data - the int to be substituted
      obscure - boolean indicating whether the data is double-blind sensitive
      Returns:
      This Report to allow chaining

    • add

      public Report add(String data)
      Add the given String to the list of data that will be substituted for the <data> tags in the report. The order in which items are added must match the order of the tags in the report text.
      Parameters:
      data - the String to be substituted
      Returns:
      This Report to allow chaining

    • add

      public Report add(String data, String translate)
      Add the given string to the list of data that will be substituted for the <data> tags in the report. The order in which items are added must match the order of the tags in the report text. The second string argument sets the translation flag to the string value.
      Parameters:
      data - the String to be substituted
      translate - the common Resource Bundle to be used for translation
      Returns:
      This Report to allow chaining

    • add

      public Report add(String data, boolean obscure)
      Add the given String to the list of data that will be substituted for the <data> tags in the report, and mark it as double-blind sensitive information if obscure is true. The order in which items are added must match the order of the tags in the report text.
      Parameters:
      data - the String to be substituted
      obscure - boolean indicating whether the data is double-blind sensitive
      Returns:
      This Report to allow chaining

    • add

      public Report add(TargetRoll targetRoll)
      Adds target roll to report with details available as a tooltip
      Parameters:
      targetRoll - the target roll
      Returns:
      This Report to allow chaining

    • add

      public Report add(Roll diceRoll)

    • addDataWithTooltip

      public Report addDataWithTooltip(Integer data, String tooltip)

    • addDataWithTooltip

      public Report addDataWithTooltip(String data, String tooltip)
      Adds a field to the report with additional data available as a tooltip
      Parameters:
      data - the data for the report field
      tooltip - the tooltip text
      Returns:
      This Report to allow chaining

    • choose

      public Report choose(boolean choice)
      Indicate which of two possible messages should be substituted for the <msg:n,m> tag. An argument of true would select message n while an argument of false would select m. In the future, this capability may be expanded to support more than two choices.
      Parameters:
      choice - boolean indicating which message to substitute
      Returns:
      This Report to allow chaining

    • span

      public String span(String name, String text, String attributes)

    • addDesc

      public Report addDesc(Entity entity)
      Shortcut method for adding entity name and owner data at the same time. Assumes that the entity name should be obscured, but the owner should not.
      Parameters:
      entity - the entity you wish to add
      Returns:
      This Report to allow chaining

    • addEntityName

      public Report addEntityName(Entity entity)
      Adds a unit's linked name alone, for a name inside a sentence: no owner, no crew nickname and no sprite, unlike addDesc(Entity).
      Parameters:
      entity - the entity to name
      Returns:
      This Report to allow chaining

    • addEntityName

      public Report addEntityName(Entity entity, String displayName)
      Adds a unit's linked name alone, shown as the given text: no owner, no crew nickname and no sprite.
      Parameters:
      entity - the entity to name
      displayName - the text of the link, such as the chassis alone
      Returns:
      This Report to allow chaining

    • setShowImage

      @Deprecated(since="0.51.0", forRemoval=true) public void setShowImage(boolean showImage)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Manually Toggle if the report should show an image of the entity

    • obscureImg

      public void obscureImg()

    • isValueObscured

      public boolean isValueObscured(int index)
      Internal method. Not for typical use.

      Tests whether the data value at the given index has been marked as obscured.

      Parameters:
      index - position of data value (indexes are chronological and start at zero)
      Returns:
      true if the data value was marked obscured

    • hideData

      public void hideData(int index)
      Internal method. Not for typical use.

      Remove the data value from the report. This operation is irreversible.

      Parameters:
      index - position of data value (indexes are chronological and start at zero

    • indent

      public Report indent()
      Indent the report. Equivalent to calling indent(int) with a parameter of 1.
      Returns:
      This Report to allow chaining

    • indent

      public Report indent(int n)
      Indent the report n times.
      Parameters:
      n - the number of times to indent the report
      Returns:
      This Report to allow chaining

    • dataCount

      public int dataCount()
      Internal method. Not for typical use.

      Get the total number of data values associated with this report. Note that this includes the true/false values added for <msg> tags as well.

      Returns:
      the number of data values

    • text

      public String text()
      Get the report in its final form, with all the necessary substitutions made.
      Specified by:
      text in interface ReportEntry
      Returns:
      a String with the final report

    • addRoll

      public ReportEntry addRoll(Roll roll)
      Description copied from interface: ReportEntry
      Adds the result of the given roll to this ReportEntry. Returns this ReportEntry to allow chaining calls.
      Specified by:
      addRoll in interface ReportEntry
      Parameters:
      roll - The roll to add
      Returns:
      this ReportEntry

    • addNewline

      public static void addNewline(Vector<Report> v)
      Adds a newline to the last report in the given Vector.
      Parameters:
      v - a Vector of Report objects

    • setupStylesheet

      public static void setupStylesheet(JTextPane pane)

    • setupStylesheet

      public static void setupStylesheet(StyleSheet styleSheet)

    • span

      public String span(String name, String text)
      Wraps text in a span with the given class name.
      Parameters:
      name - The class name.
      text - The text to wrap.
      Returns:
      The HTML string.

    • warning

      public String warning(String text)
      Wraps text in a warning span.
      Parameters:
      text - The text to wrap.
      Returns:
      The HTML string.

    • fgColor

      public String fgColor(Color color, String str)
      Wraps text in a span with the given foreground color.
      Parameters:
      color - The color to use.
      str - The text to wrap.
      Returns:
      The HTML string.

    • fgColor

      public String fgColor(String hexColor, String str)
      Wraps text in a span with the given hex foreground color.
      Parameters:
      hexColor - The hex color string (e.g., "#RRGGBB").
      str - The text to wrap.
      Returns:
      The HTML string.

    • bgColor

      @Deprecated(since="0.51.0", forRemoval=true) public String bgColor(Color color, String str)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Wraps text in a span with the given background color.
      Parameters:
      color - The color to use.
      str - The text to wrap.
      Returns:
      The HTML string.

    • bgColor

      public String bgColor(String hexColor, String str)
      Wraps text in a span with the given hex background color.
      Parameters:
      hexColor - The hex color string (e.g., "#RRGGBB").
      str - The text to wrap.
      Returns:
      The HTML string.

    • bold

      public static String bold(String str)
      Wraps text in a bold tag.
      Parameters:
      str - The text to wrap.
      Returns:
      The HTML string.

    • href

      public String href(String href, String str)
      Creates an HTML anchor tag.
      Parameters:
      href - The URL.
      str - The link text.
      Returns:
      The HTML string.

    • addObscuredRecipient

      public void addObscuredRecipient(String playerName)
      Internal method. Not for typical use.

      Adds the given player name to the report's list of players who received an obscured version of this report from the server at some time in the past.

      Parameters:
      playerName - the String containing the player's name

    • isObscuredRecipient

      public boolean isObscuredRecipient(String playerName)
      Internal method. Not for typical use.

      Tests whether the given player name is on the report's list of players who received an obscured version of this report from the server at some time in the past.

      Parameters:
      playerName - the String containing the player's name
      Returns:
      true if the player was sent an obscured version of this report

    • toString

      public String toString()
      Useful for debugging purposes.
      Overrides:
      toString in class Object
      Returns:
      a String of the form "Report(messageId=n)"

    • indentAll

      public static void indentAll(@Nullable Vector<Report> reports, int amount)
      Sets the indentation for all reports of the given reports list to the given amount by calling indent(int)
      Parameters:
      reports - A list of reports to be affected
      amount - The amount of indentation to give each report in the list