Package VASSAL.build.module

Class Map

java.lang.Object
VASSAL.search.AbstractImageFinder
VASSAL.build.AbstractBuildable
VASSAL.build.AbstractConfigurable
VASSAL.build.AbstractToolbarItem
VASSAL.build.module.Map
All Implemented Interfaces:
DropTargetListener, MouseListener, MouseMotionListener, EventListener, AutoConfigurable, Buildable, Configurable, GameComponent, PlayerRoster.SideChangeListener, MutablePropertiesContainer, PropertyNameSource, PropertySource, ValidityChecker, Translatable, ImageSearchTarget, SearchTarget, ToolBarComponent, UniqueIdManager.Identifyable
Direct Known Subclasses:
PrivateMap, WidgetMap
public class Map extends AbstractToolbarItem implements GameComponent, MouseListener, MouseMotionListener, DropTargetListener, Configurable, UniqueIdManager.Identifyable, ToolBarComponent, MutablePropertiesContainer, PropertySource, PlayerRoster.SideChangeListener
The Map is the main component for displaying and containing GamePieces during play. Pieces are displayed on the map's Board(s) and moved by clicking and dragging. Keyboard events are forwarded to selected pieces. Multiple map windows are supported in a single game, with dragging between windows allowed. To a map's Board subcomponent(s), various forms of grid can be added: (ZonedGrid (aka Multi-zone Grid), HexGrid, SquareGrid (aka Rectangular Grid), and RegionGrid (aka Irregular Grid). These can be used to determine where pieces are allowed to move, and also for filling properties (e.g. LocationName, CurrentZone, CurrentBoard, CurrentMap) to allow the module to keep track of pieces and react to their movements. A Map may contain many different Buildable subcomponents. Components which are addable uniquely to a Map are contained in the VASSAL.build.module.map package. Some of the most common Map subcomponents include Zoomer for Zoom Capability, CounterDetailViewer aka Mouse-over Stack Viewer, HidePiecesButton, and SelectionHighlighters. Map also contain several critical subcomponents which are automatically added and are not configurable at the module level. These include PieceMover which handles dragging and dropping of pieces, KeyBufferer which tracks which pieces are currently "selected" and forwards key commands to them, MenuDisplayer which listens for "right clicks" and provides "context menu" services, and StackMetrics which handles the "stacking" of game pieces.

  • Field Details

  • Constructor Details

    • Map

      public Map()

  • Method Details

    • getComponent

      public Component getComponent()
      Description copied from class: AbstractToolbarItem
      The component to be added to the control window toolbar
      Overrides:
      getComponent in class AbstractToolbarItem
      Returns:
      Map's main visual interface swing component (its JPanel)

    • setChangeReportingEnabled

      public static void setChangeReportingEnabled​(boolean b)
      Global Change Reporting control - used by Global Key Commands (see GlobalCommand) to temporarily disable reporting while they run, if their "Suppress individual reports" option is selected.
      Parameters:
      b - true to turn global change reporting on, false to turn it off.

    • isChangeReportingEnabled

      public static boolean isChangeReportingEnabled()
      Returns:
      true if change reporting is currently enabled, false if it is presently being suppressed by a Global Key Command.

    • setAttribute

      public void setAttribute​(String key, Object value)
      Sets a buildFile (XML) attribute value for this component.
      Specified by:
      setAttribute in interface AutoConfigurable
      Specified by:
      setAttribute in interface Translatable
      Overrides:
      setAttribute in class AbstractToolbarItem
      Parameters:
      key - the name of the attribute. Will be one of those listed in getAttributeNames()
      value - If the value parameter is a String, it will be the value returned by getAttributeValueString(java.lang.String) for the same key. Since Map extends AbstractConfigurable, then value can also be an instance of the corresponding Class listed in getAttributeTypes().

    • getAttributeValueString

      public String getAttributeValueString​(String key)
      Description copied from class: AbstractToolbarItem
      Classes extending AbstractToolbarItem can call this as a super() method after checking for their own keys, to avoid needing to deal with the nitty gritty of the toolbar button.
      Specified by:
      getAttributeValueString in interface AutoConfigurable
      Specified by:
      getAttributeValueString in interface Translatable
      Overrides:
      getAttributeValueString in class AbstractToolbarItem
      Parameters:
      key - the name of the attribute. Will be one of those listed in getAttributeNames()
      Returns:
      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 setAttribute(java.lang.String, java.lang.Object). It is also frequently used for checking the current value of an attribute.

    • build

      public void build​(Element e)
      Builds the map's component hierarchy from a given XML element, or a null one is given initializes a brand new default "new map" hierarchy.
      Specified by:
      build in interface Buildable
      Overrides:
      build in class AbstractBuildable
      Parameters:
      e - XML element to build from, or null to build the default hierarchy for a brand new Map

    • setBoardPicker

      public void setBoardPicker​(BoardPicker picker)
      Every map must include a single BoardPicker as one of its build components. This will contain the map's Board (or Boards), which will in turn contain any grids, zones, and location information.
      Parameters:
      picker - BoardPicker to register to the map. This method unregisters any previous BoardPicker.

    • getBoardPicker

      public BoardPicker getBoardPicker()
      Every map must include a BoardPicker as one of its build components. This contains the map's Board (or Boards), which will in turn contain any grids, zones, and location information.
      Returns:
      the BoardPicker for this map (if none exist, this method will add one and return it)

    • setZoomer

      public void setZoomer​(Zoomer z)
      A map may include a single Zoomer as one of its build components. This adds zoom in/out capability to the map.
      Parameters:
      z - Zoomer to register

    • getZoomer

      public Zoomer getZoomer()
      A map may include a Zoomer as one of its build components. This adds zoom in/out capability to the map.
      Returns:
      the Zoomer for this map, if one is registered, or null if none.

    • getZoom

      public double getZoom()
      If the map has a Zoomer (see setZoomer(VASSAL.build.module.map.Zoomer)), then returns the Zoomer's current zoom factor. If no Zoomer exists, returns 1.0 as the zoom factor.
      Returns:
      the current zoom factor for the map

    • setStackMetrics

      public void setStackMetrics​(StackMetrics sm)
      Every map must include a single StackMetrics as one of its build components, which governs the visuals of stacking of GamePieces on the map.
      Parameters:
      sm - StackMetrics component to register

    • getStackMetrics

      public StackMetrics getStackMetrics()
      Every map must include a single StackMetrics object as one of its build components, which governs the visuals of stacking of GamePieces on the map
      Returns:
      the StackMetrics for this map

    • setPieceMover

      public void setPieceMover​(PieceMover mover)
      Every map must include a single PieceMover component as one of its build components, which handles drag-and-drop behavior for the map.
      Parameters:
      mover - PieceMover component to register

    • getToolBar

      public JToolBar getToolBar()
      Every map window has a toolbar, and this method returns swing toolbar component for this map.
      Specified by:
      getToolBar in interface ToolBarComponent
      Returns:
      the swing toolbar component (JToolBar for this map's window.

    • addDrawComponent

      public void addDrawComponent​(Drawable theComponent)
      Registers a Drawable component to this map. Components can implement the Drawable interface (and register themselves here) if they have a graphical component that should be drawn whenever the Map is drawn. Standard examples include CounterDetailViewers (aka Mouse-over Stack Viewers), GlobalMaps (aka Overview Maps), LOS_Threads, MapShaders, and the KeyBufferer (to show which pieces are selected).

    • removeDrawComponent

      public void removeDrawComponent​(Drawable theComponent)
      Unregister a Drawable component from this map

    • addTo

      public void addTo​(Buildable b)
      Registers this Map as a child of another buildable component, usually the GameModule. Determines a unique id for this Map. Registers itself as KeyStrokeSource. Registers itself as a GameComponent. Registers itself as a drop target and drag source. If the map is to be removed or otherwise shutdown, it can be deregistered, reversing this process, by removeFrom(VASSAL.build.Buildable)
      Specified by:
      addTo in interface Buildable
      Overrides:
      addTo in class AbstractToolbarItem
      Parameters:
      b - parent Buildable to add this component to as a subcomponent.
      See Also:
      getId(), DragBuffer

    • removeFrom

      public void removeFrom​(Buildable b)
      Unregisters this Map from its Buildable parent (usually a GameModule), reversing the process of addTo(VASSAL.build.Buildable).
      Specified by:
      removeFrom in interface Configurable
      Overrides:
      removeFrom in class AbstractToolbarItem
      Parameters:
      b - parent Buildable to deregister from

    • sideChanged

      public void sideChanged​(String oldSide, String newSide)
      Takes action when the local player has switched sides. Because Map implements PlayerRoster.SideChangeListener, this method will automatically be called whenever the local player switches sides.
      Specified by:
      sideChanged in interface PlayerRoster.SideChangeListener
      Parameters:
      oldSide - side the local player is switching away from
      newSide - side the local player is switching to

    • setBoards

      public void setBoards​(Collection<Board> c)
      Set the boards for this map. Each map may contain more than one Board.
      Parameters:
      c - Collection of Boards to be used.

    • setBoards

      @Deprecated(since="2020-08-05", forRemoval=true) public void setBoards​(Enumeration<Board> boardList)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use setBoards(Collection) instead.
      Set the boards for this map. Each map may contain more than one Board.

    • findBoard

      public Board findBoard​(Point p)
      Since a map can have multiple boards in use at once (laid out above and beside each other), this method accepts a Point in the map's coordinate space and will return the Board which contains that point, or null if none.
      Returns:
      the Board on this map containing the argument point

    • findZone

      public Zone findZone​(Point p)
      If the given point in the map's coordinate space is within a Zone on a board with a ZonedGrid (aka Multi-zoned Grid), returns the Zone. Otherwise returns null.
      Returns:
      the Zone on this map containing the argument point

    • findZone

      public Zone findZone​(String name)
      Search on all boards for a Zone with the given name
      Parameters:
      name - Zone Name
      Returns:
      Located zone, or null if not found

    • findRegion

      public Region findRegion​(String name)
      Search on all boards for a Region (location on an Irregular Grid) with the given name
      Parameters:
      name - Region name
      Returns:
      Located region, or null if none

    • getBoardByName

      public Board getBoardByName​(String name)
      Searches our list of boards for one with the given name
      Parameters:
      name - Board Name
      Returns:
      located board, or null if no such board found

    • getPreferredSize

      public Dimension getPreferredSize()
      Returns:
      Dimension for map window's "preferred size"

    • mapSize

      public Dimension mapSize()
      Returns:
      the size of the map in pixels at 100% zoom, including the edge buffer

    • isLocationRestricted

      public boolean isLocationRestricted​(Point p)
      Returns:
      true if the given point may not be a legal location. I.e., if this grid will attempt to snap it to the nearest grid location

    • snapTo

      public Point snapTo​(Point p)
      Returns:
      the nearest allowable point according to the MapGrid on the Board at this point
      See Also:
      Board.snapTo(java.awt.Point), MapGrid.snapTo(java.awt.Point)

    • getEdgeBuffer

      public Dimension getEdgeBuffer()
      Returns:
      The buffer of empty space around the boards in the Map window, in component coordinates at 100% zoom

    • mapCoordinates

      @Deprecated(since="2020-08-05", forRemoval=true) public Point mapCoordinates​(Point p)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use componentToMap(Point)
      Translate a point from component coordinates (i.e., x,y position on the JPanel) to map coordinates (i.e., accounting for zoom factor).
      See Also:
      componentCoordinates(java.awt.Point)

    • mapRectangle

      @Deprecated(since="2020-08-05", forRemoval=true) public Rectangle mapRectangle​(Rectangle r)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use componentToMap(Rectangle)

    • componentCoordinates

      @Deprecated(since="2020-08-05", forRemoval=true) public Point componentCoordinates​(Point p)
      Deprecated, for removal: This API element is subject to removal in a future version.
      mapToComponent(Point)
      Translate a point from map coordinates to component coordinates
      See Also:
      mapCoordinates(java.awt.Point)

    • componentRectangle

      @Deprecated(since="2020-08-05", forRemoval=true) public Rectangle componentRectangle​(Rectangle r)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use mapToComponent(Rectangle)

    • scale

      protected int scale​(int c, double zoom)
      Scales an integer value to a zoom factor
      Parameters:
      c - value to be scaled
      zoom - zoom factor
      Returns:
      scaled value result

    • scale

      protected Point scale​(Point p, double zoom)
      Scales a point to a zoom factor
      Parameters:
      p - point to be scaled
      zoom - zoom factor
      Returns:
      scaled point result

    • scale

      protected Rectangle scale​(Rectangle r, double zoom)
      Scales a Rectangle to a zoom factor
      Parameters:
      r - Rectangle to be zoomed
      zoom - zoom factor
      Returns:
      scaled Rectangle result

    • mapToDrawing

      public int mapToDrawing​(int c, double os_scale)
      Converts an integer value from the Map's coordinate system to Drawing coordinates for rendering. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors) as well as the Map's zoom factor. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: Drawing a line between two points on a map (see LOS_Thread.draw(java.awt.Graphics, VASSAL.build.module.Map). Drawing a piece on the map (see StackMetrics.draw(VASSAL.counters.Stack, java.awt.Graphics, int, int, java.awt.Component, double).
      Parameters:
      c - value in Map coordinate space to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled value in Drawing coordinate space

    • mapToDrawing

      public Point mapToDrawing​(Point p, double os_scale)
      Converts a point from the Map's coordinate system to Drawing coordinates for rendering. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors) as well as the Map's zoom factor. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: Drawing a line between two points on a map (see LOS_Thread.draw(java.awt.Graphics, VASSAL.build.module.Map). Drawing a piece on the map (see StackMetrics.draw(VASSAL.counters.Stack, java.awt.Graphics, int, int, java.awt.Component, double).
      Parameters:
      p - point in Map coordinates to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled point in Drawing coordinates

    • mapToDrawing

      public Rectangle mapToDrawing​(Rectangle r, double os_scale)
      Converts a rectangle from the Map's coordinate system to Drawing coordinates for rendering. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors) as well as the Map's zoom factor. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: Drawing a line between two points on a map (see LOS_Thread.draw(java.awt.Graphics, VASSAL.build.module.Map). Drawing a piece on the map (see StackMetrics.draw(VASSAL.counters.Stack, java.awt.Graphics, int, int, java.awt.Component, double).
      Parameters:
      r - rectangle in Map coordinates to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled rectangle in Drawing coordinates

    • mapToComponent

      public int mapToComponent​(int c)
      Converts an integer value from the Map's coordinate system to Component coordinates used for interactions between swing components. Basically this scales by the map's zoom factor. Note that although drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: activating a popup menu at a piece's location on a map (see MenuDisplayer#maybePopup). Drag and drop operations (see dragGestureRecognizedPrep in PieceMover).
      Parameters:
      c - value in Map coordinate system to scale
      Returns:
      scaled value in Component coordinate system

    • mapToComponent

      public Point mapToComponent​(Point p)
      Converts a Point from the Map's coordinate system to Component coordinates used for interactions between swing components. Basically this scales by the map's zoom factor. Note that although drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: activating a popup menu at a piece's location on a map (see MenuDisplayer#maybePopup). Drag and drop operations (see dragGestureRecognizedPrep in PieceMover).
      Parameters:
      p - Point in Map coordinates to scale
      Returns:
      scaled Point in Component coordinates

    • mapToComponent

      public Rectangle mapToComponent​(Rectangle r)
      Converts a Rectangle from the Map's coordinate system to Component coordinates used for interactions between swing components. Basically this scales by the map's zoom factor. Note that although drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: activating a popup menu at a piece's location on a map (see MenuDisplayer#maybePopup). Drag and drop operations (see dragGestureRecognizedPrep in PieceMover).
      Parameters:
      r - Rectangle in Map coordinates to scale
      Returns:
      scaled Rectangle in Component coordinates

    • componentToDrawing

      public int componentToDrawing​(int c, double os_scale)
      Converts an integer value from Component coordinates system to Drawing coordinates for rendering. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors), which accounts entirely for the difference in these two coordinate systems. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with Component coordinates, on HiDPI monitors it will not. Examples: see Footprint.draw(java.awt.Graphics, int, int, java.awt.Component, double) - checking a map component's "visible" clipping rect, and using it in the context of drawing move trails.
      Parameters:
      c - value in Component coordinate space to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled value in Drawing coordinate space

    • componentToDrawing

      public Point componentToDrawing​(Point p, double os_scale)
      Converts a Point from Component coordinates to Drawing coordinates for rendering. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors), which accounts entirely for the difference in these two coordinate systems. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with Component coordinates, on HiDPI monitors it will not. Examples: see Footprint.draw(java.awt.Graphics, int, int, java.awt.Component, double) - checking a map component's "visible" clipping rect, and using it in the context of drawing move trails.
      Parameters:
      p - Point in Component coordinate space to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled Point in Drawing coordinate space

    • componentToDrawing

      public Rectangle componentToDrawing​(Rectangle r, double os_scale)
      Converts a Rectangle from Component coordinates to Drawing coordinates for rendering. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors), which accounts entirely for the difference in these two coordinate systems. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with Component coordinates, on HiDPI monitors it will not. Examples: see Footprint.draw(java.awt.Graphics, int, int, java.awt.Component, double) - checking a map component's "visible" clipping rect, and using it in the context of drawing move trails.
      Parameters:
      r - Rectangle in Component coordinate space to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled Rectangle in Drawing coordinate space

    • componentToMap

      public int componentToMap​(int c)
      Converts an integer value from swing Component coordinates to the Map's coordinate system. Basically this scales by the inverse of the map's zoom factor. Note that although drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: Checking if the mouse is currently overlapping a game piece KeyBufferer.mouseReleased(MouseEvent), CounterDetailViewer#getDisplayablePieces.
      Parameters:
      c - value in Component coordinates to scale
      Returns:
      scaled value in Map coordinates

    • componentToMap

      public Point componentToMap​(Point p)
      Converts a Point from swing Component coordinates to the Map's coordinate system. Basically this scales by the inverse of the map's zoom factor. Note that although drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: Checking if the mouse is currently overlapping a game piece KeyBufferer.mouseReleased(MouseEvent), CounterDetailViewer#getDisplayablePieces.
      Parameters:
      p - Point in Component coordinates to scale
      Returns:
      scaled Point in Map coordinates

    • componentToMap

      public Rectangle componentToMap​(Rectangle r)
      Converts a Rectangle from swing Component coordinates to the Map's coordinate system. Basically this scales by the inverse of the map's zoom factor. Note that although drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not. Examples: Checking if the mouse is currently overlapping a game piece KeyBufferer.mouseReleased(MouseEvent), CounterDetailViewer#getDisplayablePieces.
      Parameters:
      r - Rectangle in Component coordinates to scale
      Returns:
      scaled Rectangle in Map coordinates

    • drawingToMap

      public int drawingToMap​(int c, double os_scale)
      Converts an integer value from Drawing coordinates to the Map's coordinate system. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors) as well as the Map's zoom factor, scaling by the inverse of both of these scale factors. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not.
      Parameters:
      c - value in Drawing coordinate space to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled value in Map coordinates

    • drawingToMap

      public Point drawingToMap​(Point p, double os_scale)
      Converts a Point from Drawing coordinates to the Map's coordinate system. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors) as well as the Map's zoom factor, scaling by the inverse of both of these scale factors. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not.
      Parameters:
      p - Point in Drawing coordinate space to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled point in Map coordinates

    • drawingToMap

      public Rectangle drawingToMap​(Rectangle r, double os_scale)
      Converts a Rectangle from Drawing coordinates to the Map's coordinate system. Takes into account the operating system's scale factor (needed to deal with HiDPI monitors) as well as the Map's zoom factor, scaling by the inverse of both of these scale factors. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with component coordinates, on HiDPI monitors it will not.
      Parameters:
      r - Rectangle in Drawing coordinate space to be scaled
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled Rectangle in Map coordinates

    • drawingToComponent

      public int drawingToComponent​(int c, double os_scale)
      Converts an integer value from Drawing coordinates to swing Component coordinates. Takes into account the inverse of the operating system's scale factor (needed to deal with HiDPI monitors), which accounts entirely for the difference in these two coordinate systems. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with Component coordinates, on HiDPI monitors it will not.
      Parameters:
      c - value in Drawing coordinates
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled value in Component coordinates

    • drawingToComponent

      public Point drawingToComponent​(Point p, double os_scale)
      Converts a Point from Drawing coordinates to swing Component coordinates. Takes into account the inverse of the operating system's scale factor (needed to deal with HiDPI monitors), which accounts entirely for the difference in these two coordinate systems. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with Component coordinates, on HiDPI monitors it will not.
      Parameters:
      p - Point in Drawing coordinates
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled Point in Component coordinates

    • drawingToComponent

      public Rectangle drawingToComponent​(Rectangle r, double os_scale)
      Converts a Rectangle from Drawing coordinates to swing Component coordinates. Takes into account the inverse of the operating system's scale factor (needed to deal with HiDPI monitors), which accounts entirely for the difference in these two coordinate systems. Although Drawing coordinates may sometimes have the traditional 1-to-1 relationship with Component coordinates, on HiDPI monitors it will not.
      Parameters:
      r - Rectangle in Drawing coordinates
      os_scale - Operating system's scale factor, (obtained from {@link Graphics2D#getDeviceConfiguration().getDefaultTransform().getScaleX()})
      Returns:
      scaled Rectangle in Component coordinates

    • locationName

      public String locationName​(Point p)
      Returns:
      a String name for the given location on the map. Checks first for a Deck, then for a Board that is able to provide a name from one of its grids. If no matches, returns "offboard" string.
      See Also:
      Board.locationName(java.awt.Point)

    • localizedLocationName

      public String localizedLocationName​(Point p)
      Returns:
      a translated-if-available String name for the given location on the map. Checks first for a Deck, then for a Board that is able to provide a name from one of its grids. If no matches, returns "offboard" string.
      See Also:
      Board.locationName(java.awt.Point)

    • isVisibleToAll

      public boolean isVisibleToAll()
      Is this map visible to all players?
      Returns:
      true if this map either (a) isn't a PrivateMap or (b) does have its visible-to-all flag set

    • getDeckNameContaining

      public String getDeckNameContaining​(Point p)
      Returns:
      the name of the Deck whose bounding box contains point p

    • getDeckNameAt

      public String getDeckNameAt​(Point p)
      Return the name of the Deck whose position is precisely p
      Parameters:
      p - Point to look for Deck
      Returns:
      Name of whose position is precisely p

    • getLocalizedDeckNameAt

      public String getLocalizedDeckNameAt​(Point p)
      Return the localized name of the Deck whose position is precisely p
      Parameters:
      p - Point to look for Deck
      Returns:
      Name of whose position is precisely p

    • addLocalMouseListener

      public void addLocalMouseListener​(MouseListener l)
      Because MouseEvents are received in Component coordinates, it is inconvenient for MouseListeners on the map to have to translate to Map coordinates. MouseListeners added with this method will receive mouse events with points already translated into Map coordinates. addLocalMouseListenerFirst inserts the new listener at the start of the chain.
      Parameters:
      l - MouseListener to add

    • addLocalMouseListenerFirst

      public void addLocalMouseListenerFirst​(MouseListener l)
      Because MouseEvents are received in Component coordinates, it is inconvenient for MouseListeners on the map to have to translate to Map coordinates. MouseListeners added with this method will receive mouse events with points already translated into Map coordinates. addLocalMouseListenerFirst inserts the new listener at the start of the chain.
      Parameters:
      l - MouseListener to add

    • removeLocalMouseListener

      public void removeLocalMouseListener​(MouseListener l)
      Because MouseEvents are received in Component coordinates, it is inconvenient for MouseListeners on the map to have to translate to Map coordinates. MouseListeners added with this method will receive mouse events with points already translated into Map coordinates. addLocalMouseListenerFirst inserts the new listener at the start of the chain.
      Parameters:
      l - MouseListener to add

    • pushMouseListener

      public void pushMouseListener​(MouseListener l)
      MouseListeners on a map may be pushed and popped onto a stack. Only the top listener on the stack receives mouse events.
      Parameters:
      l - MouseListener to push onto stack.

    • popMouseListener

      public void popMouseListener()
      MouseListeners on a map may be pushed and popped onto a stack. Only the top listener on the stack receives mouse events. The pop method removes the most recently pushed mouse listener.

    • popMouseListener

      public void popMouseListener​(MouseListener l)
      Remove the most recently pushed mouse listener only if it is the supplied listener
      Parameters:
      l - Listener

    • mouseEntered

      public void mouseEntered​(MouseEvent e)
      Specified by:
      mouseEntered in interface MouseListener
      Parameters:
      e - MouseEvent

    • mouseExited

      public void mouseExited​(MouseEvent e)
      Specified by:
      mouseExited in interface MouseListener
      Parameters:
      e - MouseEvent

    • translateEvent

      public MouseEvent translateEvent​(MouseEvent e)
      Because MouseEvents are received in Component coordinates, it is inconvenient for MouseListeners on the map to have to translate to Map coordinates. MouseListeners added with this method will receive mouse events with points already translated into Map coordinates. addLocalMouseListenerFirst inserts the new listener at the start of the chain.
      Parameters:
      e - MouseEvent in Component coordinates
      Returns:
      MouseEvent translated into Map coordinates

    • mouseClicked

      public void mouseClicked​(MouseEvent e)
      Mouse events are first translated into map coordinates. Then the event is forwarded to the top MouseListener in the stack, if any, otherwise forwarded to all LocalMouseListeners
      Specified by:
      mouseClicked in interface MouseListener
      Parameters:
      e - MouseEvent from system
      See Also:
      pushMouseListener(java.awt.event.MouseListener), popMouseListener(), addLocalMouseListener(java.awt.event.MouseListener)

    • setActiveMap

      public static void setActiveMap​(Map m)
      Marks an ActiveMap for certain drag and drop operations, so that the map can be repainted when the operation is complete.
      Parameters:
      m - Map to be considered active.

    • clearActiveMap

      public static void clearActiveMap()
      Repaints the current ActiveMap (see setActiveMap(VASSAL.build.module.Map)) and unmarks it.

    • mousePressed

      public void mousePressed​(MouseEvent e)
      Mouse events are first translated into map coordinates. Then the event is forwarded to the top MouseListener in the stack, if any, otherwise forwarded to all LocalMouseListeners
      Specified by:
      mousePressed in interface MouseListener
      Parameters:
      e - MouseEvent from system
      See Also:
      pushMouseListener(java.awt.event.MouseListener), popMouseListener(), addLocalMouseListener(java.awt.event.MouseListener)

    • mouseReleased

      public void mouseReleased​(MouseEvent e)
      Mouse events are first translated into map coordinates. Then the event is forwarded to the top MouseListener in the stack, if any, otherwise forwarded to all LocalMouseListeners
      Specified by:
      mouseReleased in interface MouseListener
      Parameters:
      e - MouseEvent from system
      See Also:
      pushMouseListener(java.awt.event.MouseListener), popMouseListener(), addLocalMouseListener(java.awt.event.MouseListener)

    • enableKeyListeners

      public void enableKeyListeners()
      Save all current Key Listeners and remove them from the map. Used by Traits that need to prevent Key Commands at certain times.

    • disableKeyListeners

      public void disableKeyListeners()
      Restore the previously disabled KeyListeners

    • setDragGestureListener

      public void setDragGestureListener​(DragGestureListener dragGestureListener)
      This listener will be notified when a drag event is initiated, assuming that no MouseListeners are on the stack.
      Parameters:
      dragGestureListener - Listener
      See Also:
      pushMouseListener(java.awt.event.MouseListener)

    • getDragGestureListener

      public DragGestureListener getDragGestureListener()
      Returns:
      current dragGestureListener that handles normal drag events (assuming no MouseListeners are on the stack)
      See Also:
      pushMouseListener(java.awt.event.MouseListener)

    • dragEnter

      public void dragEnter​(DropTargetDragEvent dtde)
      Specified by:
      dragEnter in interface DropTargetListener
      Parameters:
      dtde - DropTargetDragEvent

    • dragOver

      public void dragOver​(DropTargetDragEvent dtde)
      Handles scrolling when dragging an gamepiece to the edge of the window
      Specified by:
      dragOver in interface DropTargetListener
      Parameters:
      dtde - DropTargetDragEvent

    • dropActionChanged

      public void dropActionChanged​(DropTargetDragEvent dtde)
      Specified by:
      dropActionChanged in interface DropTargetListener
      Parameters:
      dtde - DropTargetDragEvent

    • dragExit

      public void dragExit​(DropTargetEvent dte)
      Specified by:
      dragExit in interface DropTargetListener

    • drop

      public void drop​(DropTargetDropEvent dtde)
      We put the "drop" in drag-n-drop!
      Specified by:
      drop in interface DropTargetListener
      Parameters:
      dtde - DropTargetDragEvent

    • mouseMoved

      public void mouseMoved​(MouseEvent e)
      Mouse motion events are not forwarded to LocalMouseListeners or to listeners on the stack
      Specified by:
      mouseMoved in interface MouseMotionListener
      Parameters:
      e - MouseEvent from system

    • mouseDragged

      public void mouseDragged​(MouseEvent e)
      Mouse motion events are not forwarded to LocalMouseListeners or to listeners on the stack. The map scrolls when dragging the mouse near the edge.
      Specified by:
      mouseDragged in interface MouseMotionListener
      Parameters:
      e - MouseEvent from system

    • scrollAtEdge

      public void scrollAtEdge​(Point evtPt, int dist)
      Begin autoscrolling the map if the given point is within the given distance from a viewport edge.
      Parameters:
      evtPt - Point to check
      dist - Distance to check

    • repaint

      public void repaint​(boolean cf)
      Repaints the map. Accepts parameter about whether to clear the display first.
      Parameters:
      cf - true if display should be cleared before drawing the map

    • repaint

      public void repaint()
      Repaints the map.

    • paintRegion

      public void paintRegion​(Graphics g, Rectangle visibleRect)
      Paints a specific region of the map, denoted by a Rectangle.
      Parameters:
      g - Graphics object where map should be painted
      visibleRect - region of map to repaint

    • paintRegion

      public void paintRegion​(Graphics g, Rectangle visibleRect, Component c)
      Paints a specific region of the map, denoted by a Rectangle.
      Parameters:
      g - Graphics object where map should be painted
      visibleRect - region of map to repaint
      c - observer component

    • drawBoardsInRegion

      public void drawBoardsInRegion​(Graphics g, Rectangle visibleRect, Component c)
      For each Board overlapping the given region, update the appropriate section of the board image.
      Parameters:
      g - Graphics object where map should be painted
      visibleRect - region of map to repaint
      c - observer component

    • drawBoardsInRegion

      public void drawBoardsInRegion​(Graphics g, Rectangle visibleRect)
      For each Board overlapping the given region, update the appropriate section of the board image.
      Parameters:
      g - Graphics object where map should be painted
      visibleRect - region of map to repaint

    • drawPiecesInRegion

      public void drawPiecesInRegion​(Graphics g, Rectangle visibleRect, Component c)
      Draws all pieces visible in a rectangular area of the map
      Parameters:
      g - Graphics object where map should be painted
      visibleRect - region of map to repaint
      c - observer component

    • drawPiecesInRegion

      public void drawPiecesInRegion​(Graphics g, Rectangle visibleRect)
      Draws all pieces visible in a rectangular area of the map
      Parameters:
      g - Graphics object where map should be painted
      visibleRect - region of map to repaint

    • drawPieces

      public void drawPieces​(Graphics g, int xOffset, int yOffset)
      Draws the map pieces at a given offset
      Parameters:
      g - Target graphics object
      xOffset - x offset
      yOffset - y offset

    • drawDrawable

      public void drawDrawable​(Graphics g, boolean aboveCounters)
      Draws all of our "Drawable" components. Standard examples include CounterDetailViewers (aka Mouse-over Stack Viewers), GlobalMaps (aka Overview Maps), LOS_Threads, MapShaders, and the KeyBufferer (to show which pieces are selected).
      Parameters:
      g - target graphics object
      aboveCounters - true means we should draw only the drawables that go above the counters; false means we should draw only the ones that go below

    • getHighlighter

      public Highlighter getHighlighter()
      Returns:
      Current selection highlighter

    • setHighlighter

      public void setHighlighter​(Highlighter h)
      Parameters:
      h - selection highlighter to set active

    • addHighlighter

      public void addHighlighter​(Highlighter h)
      Parameters:
      h - selection highlighter to add to our list

    • removeHighlighter

      public void removeHighlighter​(Highlighter h)
      Parameters:
      h - selection highlighter to remove from our list

    • getHighlighters

      public Iterator<Highlighter> getHighlighters()
      Returns:
      an Iterator for all of our highlighters

    • getBoards

      public Collection<Board> getBoards()
      Returns:
      a Collection of all Boards on the Map

    • getAllBoards

      @Deprecated(since="2020-08-05", forRemoval=true) public Enumeration<Board> getAllBoards()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getBoards() instead.
      Returns:
      an Enumeration of all Boards on the map

    • getBoardCount

      public int getBoardCount()
      Returns:
      number of Boards on this map

    • boundingBoxOf

      public Rectangle boundingBoxOf​(GamePiece p)
      Returns:
      the boundingBox of a GamePiece accounting for the offset of a piece within its parent stack. Return null if this piece is not on the map
      See Also:
      GamePiece.boundingBox()

    • selectionBoundsOf

      public Rectangle selectionBoundsOf​(GamePiece p)
      Returns:
      the selection bounding box of a GamePiece accounting for the offset of a piece within a stack
      See Also:
      GamePiece.getShape()

    • positionOf

      public Point positionOf​(GamePiece p)
      Returns:
      the position of a GamePiece accounting for the offset within a parent stack, if any

    • getPieces

      public GamePiece[] getPieces()
      Returns:
      an array of all GamePieces on the map, subject to visibility, and sorted in order of visual layers. This is a read-only copy. Altering the array does not alter the pieces on the map.

    • getAllPieces

      public GamePiece[] getAllPieces()
      Returns:
      an array of all GamePieces on the map, regardless of visibility, and sorted in order of visual layer. This is a read-only copy. Altering the array does not alter the pieces on the map.

    • setPieceCollection

      public void setPieceCollection​(PieceCollection pieces)
      Parameters:
      pieces - Sets the PieceCollection for this map (usually a LayeredPieceCollection a/k/a "Game Piece Layer Control"), which keeps the pieces/stacks/decks sorted by visual layer, and within each layer by back-to-front draw order

    • getPieceCollection

      public PieceCollection getPieceCollection()
      Returns:
      piece collection for this map (a/k/a its LayeredPieceCollection or "Game Piece Layer Control"), which maintains a list of all the pieces/stacks/decks on the map sorted by visual layer, and within each layer by back-to-front draw order

    • clearMapBorder

      protected void clearMapBorder​(Graphics g)
      Clears the map border region, if any. If the clearFirst flag is set, wipe the map image too.
      Parameters:
      g - target graphics object

    • setBoardBoundaries

      protected void setBoardBoundaries()
      Adjusts the bounds() rectangle to account for the Board's relative position to other boards. In other words, if Board A is N pixels wide and Board B is to the right of Board A, then the origin of Board B will be adjusted N pixels to the right.

    • getLocation

      protected Point getLocation​(Board b, double zoom)
      Gets the location of a board in Map space, based on a passed zoom factor
      Parameters:
      b - Board to find location
      zoom - zoom factor to use
      Returns:
      Relative position of the board at given scale

    • getLocation

      protected Point getLocation​(int column, int row, double zoom)
      Finds the location of a board (in Map space) at a particular column and row, based on passed zoom factor
      Parameters:
      column - number of board to find
      row - number of board to find
      zoom - zoom factor to use
      Returns:
      location of the board in Map space

    • drawBoards

      public void drawBoards​(Graphics g, int xoffset, int yoffset, double zoom, Component obs)
      Draw the boards of the map at the given point and zoom factor onto the given Graphics object
      Parameters:
      g - target Graphics object
      xoffset - x offset to draw at
      yoffset - y offset to draw at
      zoom - zoom factor for drawing the boards
      obs - observer Component

    • repaint

      public void repaint​(Rectangle r)
      Repaint the given area, specified in map coordinates
      Parameters:
      r - Rectangle specifying region to repaint in map coordinates

    • setPiecesVisible

      public void setPiecesVisible​(boolean show)
      Parameters:
      show - if true, enable drawing of GamePieces. If false, don't draw any GamePieces when painting the map

    • isPiecesVisible

      public boolean isPiecesVisible()
      Returns:
      true if GamePieces should be drawn when painting the map

    • getPieceOpacity

      public float getPieceOpacity()
      Returns:
      current pieceOpacity for drawing

    • setPieceOpacity

      public void setPieceOpacity​(float pieceOpacity)
      Parameters:
      pieceOpacity - sets opacity for piece drawing, 0 to 1.0

    • getProperty

      public Object getProperty​(Object key)
      Gets the value of a map-level global property. If a "Global Property" entry is not found at the map level, then module-level properties are checked, which includes identification information for the local player.
      Specified by:
      getProperty in interface PropertySource
      Parameters:
      key - identifies the global property to be returned
      Returns:
      value of designated global property

    • getLocalizedProperty

      public Object getLocalizedProperty​(Object key)
      Gets the value of map-level global property, or a module-level one if a map-level one is not found. The localized aspect presently only applies to permanent module-level objects which can be localized (e.g. player sides)
      Specified by:
      getLocalizedProperty in interface PropertySource
      Parameters:
      key - Name of the property to get the value of
      Returns:
      Localized/translated name of the named property, if one is available, otherwise returns the non-localized name

    • getMoveKey

      public KeyStroke getMoveKey()
      Return the apply-on-move key. It may be named, so just return the allocated KeyStroke.
      Returns:
      apply-on-move keystroke

    • createParentFrame

      protected Window createParentFrame()
      Creates the top-level window for this map. Could be a JDialog or a JFrame depending on whether we are set to use a single window or have our own window.
      Returns:
      the top-level window containing this map

    • shouldDockIntoMainWindow

      public boolean shouldDockIntoMainWindow()
      If this map shows with its own special button, it does not dock into the main window. Likewise if we have no combined window setting. Otherwise the *first* non-button-launched map we find will be the one we dock.
      Returns:
      whether this map should dock into the main window

    • setup

      public void setup​(boolean show)
      When a game is started, create a top-level window, if none exists. When a game is ended, remove all boards from the map.
      Specified by:
      setup in interface GameComponent
      Parameters:
      show - true if a game is starting, false if a game is ending
      See Also:
      GameComponent

    • getRestoreCommand

      public Command getRestoreCommand()
      As a GameComponent, Map does not have any action inherently needing to be taken for "restoring" itself for load/save and network play purposes (the locations of pieces, etc, are stored in the pieces, and are restored from GameState in its GameState.getRestorePiecesCommand() method, which creates an AddPiece command for each piece). Map's interest in GameComponent is entirely for game start/stop purposes (see setup(boolean), above).
      Specified by:
      getRestoreCommand in interface GameComponent
      Returns:
      null since no restore command needed.

    • appendToTitle

      @Deprecated(since="2020-09-16", forRemoval=true) public void appendToTitle​(String s)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use updateTitleBar()
      Parameters:
      s - String to append to title

    • updateTitleBar

      public void updateTitleBar()
      Updates the title bar of the current window

    • getDefaultWindowTitle

      protected String getDefaultWindowTitle()
      Returns:
      The correct current default window title

    • findPiece

      public GamePiece findPiece​(Point pt, PieceFinder finder)
      Use the provided PieceFinder instance to locate a visible piece at the given location
      Parameters:
      pt - Point at which to find visible pieces
      finder - PieceFinder to use
      Returns:
      a visible piece at the given location, or null if none.

    • findAnyPiece

      public GamePiece findAnyPiece​(Point pt, PieceFinder finder)
      Use the provided PieceFinder instance to locate any piece at the given location, regardless of whether it is visible or not.
      Parameters:
      pt - Point at which to find pieces
      finder - PieceFinder to use
      Returns:
      a piece at the given location, regardless of visibility, or null if none.

    • placeAt

      public Command placeAt​(GamePiece piece, Point pt)
      Place a piece at the destination point. If necessary, remove the piece from its parent Stack or Map
      Parameters:
      piece - GamePiece to place
      pt - location to place the piece
      Returns:
      a Command that reproduces this action

    • apply

      public Command apply​(PieceVisitorDispatcher commandFactory)
      Attempts to apply the provided PieceVisitorDispatcher to all pieces on this map, until it finds one that returns a non-null Command.
      Parameters:
      commandFactory - The PieceVisitorDispatcher to apply
      Returns:
      the first non-null Command returned by commandFactory

    • placeOrMerge

      public Command placeOrMerge​(GamePiece p, Point pt)
      Move a piece to the destination point. If a piece is at the point (i.e. has a location exactly equal to it), merge into a Stack with the piece by forwarding to StackMetrics.merge(VASSAL.counters.GamePiece, VASSAL.counters.GamePiece). Otherwise, place by forwarding to placeAt()
      Parameters:
      p - GamePiece to place/merge
      pt - Point location on the map to place/merge the piece.
      Returns:
      a Command that will duplicate this action on other clients
      See Also:
      StackMetrics.merge(VASSAL.counters.GamePiece, VASSAL.counters.GamePiece)

    • addPiece

      public void addPiece​(GamePiece p)
      Adds a GamePiece to this map's list of pieces. Removes the piece from its parent Stack and from its current map, if different from this map.
      Parameters:
      p - Game Piece to add

    • reposition

      @Deprecated(since="2020-08-05", forRemoval=true) public void reposition​(GamePiece s, int pos)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use PieceCollection.moveToFront(VASSAL.counters.GamePiece)
      Reorder the argument GamePiece to the new index. When painting the map, pieces are drawn in order of index

    • indexOf

      public int indexOf​(GamePiece s)
      Returns the index of a piece. When painting the map, pieces are drawn in order of index Return -1 if the piece is not on this map
      Parameters:
      s - GamePiece to find the index of
      Returns:
      index of the piece on the map, or -1 if the piece is not on this map

    • removePiece

      public void removePiece​(GamePiece p)
      Removes a piece from the map
      Parameters:
      p - GamePiece to remove from map

    • centerAt

      public void centerAt​(Point p)
      Center the map at given map coordinates within its JScrollPane container
      Parameters:
      p - Point to center

    • centerAt

      public void centerAt​(Point p, int dx, int dy)
      Center the map at the given map coordinates, if the point is not already within (dx,dy) of the center.
      Parameters:
      p - point to center
      dx - x tolerance for nearness to center
      dy - y tolerance for nearness to center

    • ensureVisible

      public void ensureVisible​(Rectangle r)
      Ensure that the given region (in map coordinates) is visible. Uses player preference to determine how sensitive to be about when to re-center.
      Parameters:
      r - Rectangle demarking region to ensure is visible

    • scroll

      public void scroll​(int dx, int dy)
      Scrolls the map in the containing JScrollPane.
      Parameters:
      dx - number of pixels to scroll horizontally
      dy - number of pixels to scroll vertically

    • getConfigureTypeName

      public static String getConfigureTypeName()
      Gets the generic name for this type of class across all instances of it. Appears in the Editor window in [..] as e.g. [Map], [Prototype], etc.
      Returns:
      The generic name for this kind of component, i.e. the part appearing [In Brackets] in the Editor's ConfigureTree.

    • getMapName

      public String getMapName()
      Returns:
      the name of this map, for internal purposes

    • getLocalizedMapName

      public String getLocalizedMapName()
      Returns:
      the localized name of this map, for display purposes

    • setMapName

      public void setMapName​(String s)
      Parameters:
      s - Sets the name of the map.

    • getHelpFile

      public HelpFile getHelpFile()
      Specified by:
      getHelpFile in interface Configurable
      Returns:
      a HelpFile describing how to use and configure this component

    • getAttributeDescriptions

      public String[] getAttributeDescriptions()
      Description copied from class: AbstractToolbarItem
      This getAttributeDescriptions() will return the items specific to the Toolbar Button - classes extending this should add their own items as well. If the "nameKey" is blank, then no "name" configure entry will be generated. Extending classes can use ArrayUtils.addAll(super.getAttributeDescriptions(), key1, ..., keyN), or supply their own order from scratch.
      Specified by:
      getAttributeDescriptions in interface AutoConfigurable
      Overrides:
      getAttributeDescriptions in class AbstractToolbarItem
      Returns:
      an array of Strings describing the buildFile (XML) attributes of this component. These strings are used as prompts in the Properties window for this object, when the component is configured in the Editor. The order of descriptions should be the same as the order of names in AbstractBuildable.getAttributeNames()
      See Also:
      AbstractConfigurable

    • getAttributeNames

      public String[] getAttributeNames()
      Lists all the buildFile (XML) attribute names for this component. If this component is ALSO an AbstractConfigurable, then this list of attributes determines the appropriate attribute order for AbstractConfigurable.getAttributeDescriptions() and AbstractConfigurable.getAttributeTypes().
      Specified by:
      getAttributeNames in interface AutoConfigurable
      Overrides:
      getAttributeNames in class AbstractToolbarItem
      Returns:
      a list of all buildFile (XML) attribute names for this component
      See Also:
      AbstractBuildable

    • getAttributeTypes

      public Class<?>[] getAttributeTypes()
      Description copied from class: AbstractToolbarItem
      This getAttributeTypes() will return the items specific to the Toolbar Button - classes extending this should add their own items as well. If the "nameKey" is blank, then no "name" configure entry will be generated. Extending classes can use ArrayUtils.addAll(super.getAttributeTypes(), key1, ..., keyN), or supply their own order from scratch.
      Specified by:
      getAttributeTypes in interface AutoConfigurable
      Overrides:
      getAttributeTypes in class AbstractToolbarItem
      Returns:
      the Class for the buildFile (XML) attributes of this component. Valid classes include: String, Integer, Double, Boolean, Image, Color, and KeyStroke, along with any class for which a Configurer exists in VASSAL.configure. The class determines, among other things, which type of AutoConfigurer will be used to configure the attribute when the object is configured in the Editor. The order of classes should be the same as the order of names in AbstractBuildable.getAttributeNames()
      See Also:
      AbstractConfigurable

    • getCreateFormat

      public String getCreateFormat()
      Returns:
      "created on map" format string

    • getChangeFormat

      public String getChangeFormat()
      Returns:
      "changed on map" format string

    • getMoveToFormat

      public String getMoveToFormat()
      Returns:
      "moved to map" format string

    • getMoveWithinFormat

      public String getMoveWithinFormat()
      Returns:
      "moved within map" format string

    • getAllowableConfigureComponents

      public Class<?>[] getAllowableConfigureComponents()
      List of subcomponents which can be added to a Map.
      Specified by:
      getAllowableConfigureComponents in interface Configurable
      Returns:
      a list 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 ConfigureTree window by right-clicking on the component and selecting the appropriate "Add" option.
      See Also:
      Configurable

    • getAttributeVisibility

      public VisibilityCondition getAttributeVisibility​(String name)
      Description copied from class: AbstractConfigurable
      By default, all attributes are visible
      Specified by:
      getAttributeVisibility in interface AutoConfigurable
      Overrides:
      getAttributeVisibility in class AbstractConfigurable
      Parameters:
      name - Name (key) of one of this component's attributes
      Returns:
      Visibility condition for the corresponding component

    • setId

      public void setId​(String id)
      Each Map must have a unique String id Sets our unique ID (among Maps), so that e.g. commands sent to different maps don't inadvertently get confused when we send commands to other clients.
      Specified by:
      setId in interface UniqueIdManager.Identifyable
      Parameters:
      id - Sets our unique ID

    • getId

      public String getId()
      Each Map must have a unique String id
      Specified by:
      getId in interface UniqueIdManager.Identifyable
      Returns:
      the id for this map

    • getMapById

      public static Map getMapById​(String id)
      Find the map that corresponds to a known unique id
      Parameters:
      id - unique id of the map to find
      Returns:
      Map object corresponding to that unique id

    • getMapList

      public static List<Map> getMapList()
      Utility method to return a List of all map components (on all maps!) in the module.
      Returns:
      the list of Maps components

    • getAllMaps

      @Deprecated(since="2020-08-05", forRemoval=true) public static Iterator<Map> getAllMaps()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getMapList() instead.
      Utility method to return a list of all map components in the module
      Returns:
      Iterator over all maps

    • getMutableProperty

      public MutableProperty getMutableProperty​(String name)
      Find a contained Global Property (variable) by name. Does NOT search at the Module level.
      Specified by:
      getMutableProperty in interface MutablePropertiesContainer
      Parameters:
      name - Name of Global Property to find
      Returns:
      Mutable property corresponding to the name given

    • addMutableProperty

      public void addMutableProperty​(String key, MutableProperty p)
      Adds a new Global Property to this map.
      Specified by:
      addMutableProperty in interface MutablePropertiesContainer
      Parameters:
      key - Name of the new property
      p - The property object to add

    • removeMutableProperty

      public MutableProperty removeMutableProperty​(String key)
      Removes a new Global Property from this map.
      Specified by:
      removeMutableProperty in interface MutablePropertiesContainer
      Parameters:
      key - Name of the property to be removed
      Returns:
      the object just removed

    • getMutablePropertiesContainerId

      public String getMutablePropertiesContainerId()
      Description copied from interface: MutablePropertiesContainer
      Return a unique Id for the container
      Specified by:
      getMutablePropertiesContainerId in interface MutablePropertiesContainer
      Returns:
      The container ID for map-level Global Properties on this object (just uses the map name)

    • getIdentifier

      public String getIdentifier()
      Make a best guess for a unique identifier for the target. Use UniqueIdManager.Identifyable.getConfigureName() if non-null, otherwise use UniqueIdManager.Identifyable.getId()
      Returns:
      Unique Identifier

    • getView

      public JComponent getView()
      Returns:
      the Swing component representing the map

    • getLayeredPane

      public JLayeredPane getLayeredPane()
      Returns:
      the JLayeredPane holding map insets

    • getFormattedStringList

      public List<String> getFormattedStringList()
      SearchTarget
      Specified by:
      getFormattedStringList in interface SearchTarget
      Overrides:
      getFormattedStringList in class AbstractConfigurable
      Returns:
      a list of any Message Format strings referenced in the Configurable, if any (for search)

    • getMenuTextList

      public List<String> getMenuTextList()
      SearchTarget
      Specified by:
      getMenuTextList in interface SearchTarget
      Overrides:
      getMenuTextList in class AbstractToolbarItem
      Returns:
      a list of any Menu/Button/Tooltip Text strings referenced in the Configurable, if any (for search)

    • getNamedKeyStrokeList

      public List<NamedKeyStroke> getNamedKeyStrokeList()
      SearchTarget
      Specified by:
      getNamedKeyStrokeList in interface SearchTarget
      Overrides:
      getNamedKeyStrokeList in class AbstractToolbarItem
      Returns:
      a list of any Named KeyStrokes referenced in the Configurable, if any (for search)

    • addLocalImageNames

      public void addLocalImageNames​(Collection<String> s)
      In case reports use HTML and refer to any image files
      Specified by:
      addLocalImageNames in interface ImageSearchTarget
      Overrides:
      addLocalImageNames in class AbstractToolbarItem
      Parameters:
      s - Collection to add image names to