Merge pull request #12944 from rlament/piece_count

Add pieceCount to the map auto reporter

vassal-app/src/main/java/VASSAL/build/module/Map.java

@@ -612,7 +612,7 @@ else if (DESCRIPTION.equals(key)) {
 
   /**
    * @return a String representation of the XML buildFile attribute with the given name. When initializing a module,
-   * this String value will loaded from the XML and passed to {@link #setAttribute}. It is also frequently used for
+   * this String value is loaded from the XML and passed to {@link #setAttribute}. It is also frequently used for
    * checking the current value of an attribute.
    *
    * @param key the name of the attribute. Will be one of those listed in {@link #getAttributeNames}
@@ -1283,7 +1283,7 @@ public Point snapTo(Point p, boolean force, boolean onlyCenter) {
     snap.translate(r.x, r.y);
 
     //CC bugfix13409
-    // If we snapped to a point outside the board b, call sanpTo again with the board we landed into
+    // If we snapped to a point outside the board b, call snapTo again with the board we landed into
     final Board bSnappedTo = findBoard(snap);
     if (bSnappedTo != null && !b.equals(bSnappedTo)) {
       final Rectangle rSnappedTo = bSnappedTo.bounds();
@@ -2090,7 +2090,7 @@ public boolean isNotPieceDrag(Transferable trans) {
 
 
   /**
-   * Handles scrolling when dragging an gamepiece to the edge of the window
+   * Handles scrolling when dragging a game piece to the edge of the window
    * @param dtde DropTargetDragEvent
    */
   @Override
@@ -2117,7 +2117,7 @@ public void dropActionChanged(DropTargetDragEvent dtde) {
 
   /*
    * Cancel final scroll and repaint map
-   * @param dtde DropTargetDragEvent
+   * @param dte DropTargetEvent
    */
   @Override
   public void dragExit(DropTargetEvent dte) {
@@ -2127,7 +2127,7 @@ public void dragExit(DropTargetEvent dte) {
 
   /**
    * We put the "drop" in drag-n-drop!
-   * @param dtde DropTargetDragEvent
+   * @param dtde DropTargetDropEvent
    */
   @Override
   public void drop(DropTargetDropEvent dtde) {
@@ -3281,7 +3281,7 @@ public void removePiece(GamePiece p) {
   /**
    * Accepts the current actual center of the map as the new "preferred center" (e.g. if we scroll)
    * Just not if suppressed after a zoom level change (we don't want zoom level changes to cause us to
-   * lose track of the user's preferred ceter point)
+   * lose track of the user's preferred center point)
    */
   public void updateCenter() {
     if (!GameModule.getGameModule().isSuppressAutoCenterUpdate()) {
@@ -3490,7 +3490,7 @@ public String[] getAttributeDescriptions() {
    * Lists all the buildFile (XML) attribute names for this component.
    * If this component is ALSO an {@link AbstractConfigurable}, then this list of attributes determines the appropriate
    * attribute order for {@link AbstractConfigurable#getAttributeDescriptions()} and {@link AbstractConfigurable#getAttributeTypes()}.
-   * @return a list of all buildFile (XML) attribute names for this component
+   * @return an array of all the buildFile (XML) attribute names for this component
    * @see AbstractBuildable
    */
   @Override
@@ -3572,6 +3572,7 @@ public Class<?>[] getAttributeTypes() {
   public static final String OLD_MAP = "previousMap"; //$NON-NLS-1$
   public static final String MAP_NAME = "mapName"; //$NON-NLS-1$
   public static final String PIECE_NAME = "pieceName"; //$NON-NLS-1$
+  public static final String PIECE_COUNT = "pieceCount"; //$NON-NLS-1$
   public static final String MESSAGE = "message"; //$NON-NLS-1$
 
   /**
@@ -3600,7 +3601,7 @@ public Configurer getConfigurer(AutoConfigurable c, String key, String name) {
   public static class MoveWithinFormatConfig implements TranslatableConfigurerFactory {
     @Override
     public Configurer getConfigurer(AutoConfigurable c, String key, String name) {
-      return new PlayerIdFormattedExpressionConfigurer(key, name, new String[] { PIECE_NAME, LOCATION, MAP_NAME, OLD_LOCATION });
+      return new PlayerIdFormattedExpressionConfigurer(key, name, new String[] { PIECE_NAME, PIECE_COUNT, LOCATION, MAP_NAME, OLD_LOCATION });
     }
   }
 
@@ -3611,7 +3612,7 @@ public Configurer getConfigurer(AutoConfigurable c, String key, String name) {
   public static class MoveToFormatConfig implements TranslatableConfigurerFactory {
     @Override
     public Configurer getConfigurer(AutoConfigurable c, String key, String name) {
-      return new PlayerIdFormattedExpressionConfigurer(key, name, new String[] { PIECE_NAME, LOCATION, OLD_MAP, MAP_NAME, OLD_LOCATION });
+      return new PlayerIdFormattedExpressionConfigurer(key, name, new String[] { PIECE_NAME, PIECE_COUNT, LOCATION, OLD_MAP, MAP_NAME, OLD_LOCATION });
     }
   }
 
@@ -3631,7 +3632,7 @@ public Configurer getConfigurer(AutoConfigurable c, String key, String name) {
   public static class CreateFormatConfig implements TranslatableConfigurerFactory {
     @Override
     public Configurer getConfigurer(AutoConfigurable c, String key, String name) {
-      return new PlayerIdFormattedExpressionConfigurer(key, name, new String[] { PIECE_NAME, MAP_NAME, LOCATION });
+      return new PlayerIdFormattedExpressionConfigurer(key, name, new String[] { PIECE_NAME, PIECE_COUNT, MAP_NAME, LOCATION });
     }
   }
 
@@ -3726,7 +3727,7 @@ public String getMoveWithinFormat() {
   /**
    * List of subcomponents which can be added to a Map.
    *
-   * @return a list of valid sub-component Classes.  If a Class
+   * @return an array of valid sub-component Classes.  If a Class
    * appears in this list, then instances of that class may be added
    * to this component from the Editor's {@link ConfigureTree} window by
    * right-clicking on the component and selecting the appropriate "Add"
@@ -4010,7 +4011,7 @@ public Object visitStack(Stack s) {
     }
 
     /**
-     * @return a command to form a new stack with a piece found at the our location, provided all of the conditions to form a
+     * @return a command to form a new stack with a piece found at our location, provided all the conditions to form a
      * stack are met. Returns null if the necessary conditions aren't met.
      * @param piece piece to consider forming a new stack with.
      */

vassal-app/src/main/java/VASSAL/build/module/map/MovementReporter.java

@@ -198,6 +198,7 @@ else if (fromMap != toMap) {
         break;
       }
       format.setProperty(Map.PIECE_NAME, ms.getPieceName());
+      format.setProperty(Map.PIECE_COUNT, ms.getPieceCount());
       final String loc = getLocation(toMap, ms.getNewPosition());
       format.setProperty(Map.LOCATION, loc);
       if (fromMap != null) {
@@ -370,6 +371,10 @@ public String getPieceName() {
       }
       return names.toString();
     }
+
+    public String getPieceCount() {
+      return String.valueOf(pieces.size());
+    }
   }
 
   public static class HiddenMoveSummary extends MoveSummary {

vassal-doc/src/main/readme-referencemanual/ReferenceManual/Map.adoc

@@ -26,7 +26,7 @@ module to know whether Global Hotkeys sent to that map's components will current
 They are designed for holding pieces and cards that are private to one player or side.
 
 
-[width="100%",cols="50%a,50%a",]
+[width="100%",cols="50%a,50%a",grid=cols]
 |===
 |*Map name:*::  The name of this map window.
 
@@ -67,26 +67,49 @@ NOTE: changing this option will not take effect until the module has been reload
 
 *Hotkey to hide window:*:: A <<NamedKeyCommand.adoc#top,Keystroke or Named Command>> that hides the window.
 
-NOTE: The following reports are separate from, and in addition to, any reports the piece itself generates with <<ReportChanges.adoc#top,Report Action>> traits in response to the Key Command applied by the bottom field.
+NOTE: The following reports are separate from, and in addition to, any reports the piece itself generates with <<ReportChanges.adoc#top,Report Action>> traits in response to the Key Command applied by the <<#EndMovementKeyCommand,last field>>.
 
-*Only auto-report move "within this map" if piece's Location Name changed:*::  If selected, then movement "within this map" will only be auto-reported if the piece's LocationName property is changed by the move.
+*Only auto-report move "within this map" if piece's Location Name changed:*::  If checked, then movement "within this map" will be auto-reported only if the piece's _$location$_ property is changed by the move. Thus only displaying a message if the piece has actually changed location rather than merely being adjusted in its space.
+|image:images/Map.png[]
+image:images/Map2.png[]
 
-*Auto-report format for movement within this map:*::  A <<MessageFormat.adoc#top,Message Format>> that will be used to automatically report movement of pieces completely within this map window: _$pieceName$_ is the name of the piece being moved, _$location$_ is the location to which the piece is being moved (in the format specified below), _$previousLocation$_ is the location from which the piece is being moved.
+| *Auto-report format for movement within this map:*::  A <<MessageFormat.adoc#top,Message Format>> that will be used to automatically report movement of pieces completely within this map window. _$pieceName$_ is the name of the piece being moved, _$location$_ is the location to which the piece is being moved, _$previousLocation$_ is the location from which the piece is being moved. Refer to the <<AutoReportTable,Auto-report Table>> for a complete list of available properties.
++
+TIP: Click on the Insert drop-down menu, next to the textbox, for a list of available Properties. Selecting one of the Properties from the menu will insert it at the current cursor position. To enable the Insert drop-down, left-click in the associated textbox to set the insertion point.
 
-*Auto-report format for movement to this map:*::  A <<MessageFormat.adoc#top,Message Format>> that will be used to report movement of pieces to this map window from another map window: In addition to the properties noted for the above item, _$previousMap$_ is the name of the map from which the piece is being moved.
+*Auto-report format for movement to this map:*::  A <<MessageFormat.adoc#top,Message Format>> that will be used to report movement of pieces to this map window from another map window. Whether moving a single unit or a stack of units to this map, only one report will be generated. For a stack, the _$pieceName$_ property is a comma separated list of all the units in the stack. The _$pieceCount$_ property reports the number of units in the stack. _$previousMap$_ is the name of the map from which the piece is being moved. Refer to the <<AutoReportTable,Auto-report Table>> for a complete list of available properties.
 
-*Auto-report format for units created in this map:*::  A <<MessageFormat.adoc#top,Message Format>> that will be used to report pieces that are dragged to this map window directly from a <<PieceWindow.adoc#top,Game Piece Palette>>: The properties mentioned in the previous two items may be referenced as appropriate.
+*Auto-report format for units created in this map:*::  A <<MessageFormat.adoc#top,Message Format>> that will be used to report pieces that are dragged to this map window directly from a <<PieceWindow.adoc#top,Game Piece Palette>>. Refer to the <<AutoReportTable,Auto-report Table>> for a complete list of available properties.
 
-*Auto-report format for units modified on this map:*::  When a <<ReportChanges.adoc#top,Report Action>> trait of a Game Piece on this map is activated, this <<MessageFormat.adoc#top,Message Format>> will be used to format the message that trait requests to display.
-_$message$_ is the text message from the Report Action trait.
-It could optionally be modified to include e.g.
-the name of this Map.
+*Auto-report format for units modified on this map:*::  When a <<ReportChanges.adoc#top,Report Action>> trait of a Game Piece on this map is activated, this <<MessageFormat.adoc#top,Message Format>> will be used to format the message that that trait requests to display. _$message$_ is the text message from the Report Action trait. It could be modified, for example, to include the name of this map. Refer to the <<AutoReportTable,Auto-report Table>> for a complete list of available properties.
 
+[#EndMovementKeyCommand]
 *Key Command to apply to all units ending movement on this map:* :: The Key Command or <<NamedKeyCommand.adoc#top,Named Key Command>> to be automatically applied to each piece that ends movement on this map, whether it is moved by drag-and-drop or by a <<SendToLocation.adoc#top,Send To Location>> trait.
 +
-This Key Command can be used, for example, to trigger actions that need to be taken when a piece enters or leaves a new space (for example maintaining piece type counts in a Zone -- see Example 4 in the <<TriggerAction.adoc#top,Trigger Action>> trait), or to generate more elaborate <<ReportChanges.adoc#top,Report Action>> chat log messages than can be created with the Auto-report format (for example, ensuring that the message is only displayed if the piece has actually changed regions rather than merely being adjusted in its space). |image:images/Map.png[]
-
-image:images/Map2.png[]
+This Key Command can be used, for example, to trigger actions that need to be taken when a piece enters or leaves a new space (for example maintaining piece type counts in a Zone -- see Example 1 in the <<TriggerAction.adoc#top,Trigger Action>> trait), or to generate more elaborate <<ReportChanges.adoc#top,Report Action>> chat log messages than can be created with the Auto-report format (for example, ensuring that the message is only displayed if the piece has actually changed regions rather than merely being adjusted in its space).
+|
+[#AutoReportTable]
+[caption=""]
+.Available Auto-report Properties By Report
+[cols="3a,1a,1a,1a,1a]
+!===
+!*Property* !*Movement Within Map* !*Movement To Map* !*Create Unit* !*Modify Unit*
+
+!*PlayerName*      ! X ! X ! X ! X
+!*PlayerSide*      ! X ! X ! X ! X
+!*PlayerId*        ! X ! X ! X ! X
+!*pieceName*       ! X ! X ! X ! 
+!*oldPieceName*    !   !   !   ! X
+!*newPieceName*    !   !   !   ! X
+!*pieceCount*      ! X ! X ! X !  
+!*location*        ! X ! X ! X ! X
+!*previousLocation*! X ! X !   !  
+!*mapName*         ! X ! X ! X ! X
+!*previousMap*     ! X ! X !   !  
+!*menuCommand*     !   !   !   ! X
+!*message*         !   !   !   ! X
+!===
+Property names are case sensitive and must be entered exactly as shown.
 |===
 
 '''''