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, PropertyChangeListener, EventListener, AutoConfigurable, Buildable, Configurable, GameComponent, PlayerRoster.SideChangeListener, MutablePropertiesContainer, PropertyNameSource, PropertySource, ComponentDescription, ValidityChecker, Translatable, Auditable, 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, ComponentDescription

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Map.ChangeFormatConfig	Report format configurer for "modified on map"
static class	Map.CreateFormatConfig	Report format configurer for "created on map"
static class	Map.IconConfig	Autoconfigurer for map's icon used on its launch button
static class	Map.InsetLayout	The Layout responsible for arranging insets which overlay the Map InsetLayout currently is responsible for keeping the GlobalMap in the upper-left corner of the Map.View.
static class	Map.Merger	Implements default logic for merging pieces (into a Stack or Deck} at a given location within a map Returns a Command that merges the input GamePiece with an existing piece at the input position, provided the pieces are stackable, visible, in the same layer, etc.
static class	Map.MoveToFormatConfig	Report format configurer for "moved to map"
static class	Map.MoveWithinFormatConfig	Report format configurer for "moved within map"
static class	Map.UnmovedIconConfig	Autoconfigurer for mark-unmoved icon
static class	Map.UnmovedReportConfig	Report format configurer for clear movement history
static class	Map.View	The (JPanel-extending) component that represents the map itself

Nested classes/interfaces inherited from class VASSAL.build.AbstractToolbarItem

AbstractToolbarItem.FormattedStringConfig

Nested classes/interfaces inherited from interface VASSAL.build.AutoConfigurable

AutoConfigurable.Util

Nested classes/interfaces inherited from interface VASSAL.build.module.properties.MutablePropertiesContainer

MutablePropertiesContainer.Impl

Field Summary

Fields

Modifier and Type	Field	Description
static Map	activeMap
static final String	ALLOW_MULTIPLE
protected boolean	allowMultiple
static final String	BACKGROUND_COLOR
protected Color	bgColor
protected int[][]	boardHeights
protected List<Board>	boards
protected int[][]	boardWidths
static final String	BUTTON_NAME
static final String	CHANGE_FORMAT
protected String	changeFormat
protected static boolean	changeReportingEnabled
protected boolean	clearFirst
static final String	CREATE_FORMAT
protected String	createFormat
protected static final String	DEFAULT_EDGE_SCROLL_DELAY_PROPERTY
protected static final String	DEFAULT_EDGE_SCROLL_RATE_PROPERTY
protected static final String	DEFAULT_EDGE_SCROLL_ZONE_PROPERTY
protected String	description
static final String	DESCRIPTION
protected DragGestureListener	dragGestureListener
protected ArrayList<Drawable>	drawComponents
protected int	dx
protected int	dy
static final String	EDGE_HEIGHT
static double	EDGE_SCROLL_RATE
static final String	EDGE_WIDTH
protected Dimension	edgeBuffer
static final String	HIDE_KEY
protected boolean	hideCounters
protected NamedKeyStrokeListener	hideKeyListener
static final String	HIGHLIGHT_COLOR
static final String	HIGHLIGHT_THICKNESS
protected Highlighter	highlighter
protected ArrayList<Highlighter>	highlighters
static final String	HOTKEY
static final String	ICON
protected static final UniqueIdManager	idMgr
protected KeyBufferer	keyBufferer
protected LaunchButton	launchButton	Deprecated, for removal: This API element is subject to removal in a future version. use launch from the superclass
protected JLayeredPane	layeredPane
static final String	LOCATION
protected ComponentSplitter.SplitPane	mainWindowDock	Deprecated, for removal: This API element is subject to removal in a future version.
static final String	MAP_NAME
protected String	mapID
protected String	mapName
static final String	MARK_MOVED
static final String	MARK_UNMOVED_HOTKEY
static final String	MARK_UNMOVED_ICON
static final String	MARK_UNMOVED_REPORT
static final String	MARK_UNMOVED_TEXT
static final String	MARK_UNMOVED_TOOLTIP
protected String	markMovedOption
protected NamedKeyStroke	markUnmovedHotkey
protected String	markUnmovedIcon
protected String	markUnmovedReport
protected String	markUnmovedText
protected String	markUnmovedTooltip
static final String	MESSAGE
protected StackMetrics	metrics
protected ArrayList<MouseListener>	mouseListenerStack
static final String	MOVE_KEY
static final String	MOVE_TO_FORMAT
static final String	MOVE_WITHIN_FORMAT
protected NamedKeyStroke	moveKey
protected String	moveToFormat
protected String	moveWithinFormat
static final String	MOVING_STACKS_PICKUP_UNITS
protected MouseListener	multicaster
static final String	NAME
static final String	OLD_LOCATION
static final String	OLD_MAP
static final String	ONLY_REPORT_CHANGED_LOCATION
protected boolean	onlyReportChangedLocation
protected BoardPicker	picker
static final String	PIECE_NAME
protected PieceMover	pieceMover
protected float	pieceOpacity
protected PieceCollection	pieces
static final String	PREFERRED_EDGE_DELAY
static final int	PREFERRED_EDGE_SCROLL_DELAY
static final String	PREFERRED_EDGE_SCROLL_RATE
static final double	PREFERRED_EDGE_SCROLL_RATE_STANDARD_DEFAULT	The rate at which things scroll
static final int	PREFERRED_EDGE_SCROLL_ZONE_STANDARD_DEFAULT	The width of the hot zone for triggering autoscrolling.
static final String	PREFERRED_SCROLL_ZONE
protected Point	preferredCenter
protected MutablePropertiesContainer	propsContainer
protected PropertyChangeListener	repaintOnPropertyChange
protected KeyListener[]	saveKeyListeners
protected JScrollPane	scroll
static int	SCROLL_ZONE
protected org.jdesktop.animation.timing.Animator	scroller	The animator which controls autoscrolling.
static final String	SHOW_KEY
protected NamedKeyStrokeListener	showKeyListener
protected SplitPane	splitPane
static final String	SUPPRESS_AUTO
protected int	sx	The horizontal component of the autoscrolling vector, -1, 0, or 1.
protected int	sy	The vertical component of the autoscrolling vector, -1, 0, or 1.
protected JPanel	theMap
protected JToolBar	toolBar
protected String	tooltip
static final String	TOOLTIP
static final String	USE_LAUNCH_BUTTON
protected boolean	useLaunchButton
protected boolean	useLaunchButtonEdit
protected VisibilityCondition	visibilityCondition
protected Zoomer	zoom

Fields inherited from class VASSAL.build.AbstractToolbarItem

BUTTON_TEXT, CAN_DISABLE, canDisable, DISABLED_ICON, disabledIconConfig, HIDE_WHEN_DISABLED, hideWhenDisabled, launch, property, PROPERTY_GATE, propertyGate, showDisabledOptions

Fields inherited from class VASSAL.build.AbstractConfigurable

changeSupport, config, localizedName, myI18nData, name

Fields inherited from class VASSAL.build.AbstractBuildable

buildComponents, validator

Fields inherited from interface VASSAL.build.Configurable

NAME_PROPERTY

Constructor Summary

Constructors

Constructor	Description
Map()

Method Summary

Modifier and Type	Method	Description
void	addDrawComponent(Drawable theComponent)	Registers a Drawable component to this map.
void	addHighlighter(Highlighter h)
void	addLocalImageNames(Collection<String> s)	In case reports use HTML and refer to any image files
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.
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.
void	addMutableProperty(String key, MutableProperty p)	Adds a new Global Property to this map.
void	addPiece(GamePiece p)	Adds a GamePiece to this map's list of pieces.
void	addTo(Buildable b)	Registers this Map as a child of another buildable component, usually the GameModule.
void	appendToTitle(String s)	Deprecated, for removal: This API element is subject to removal in a future version. use updateTitleBar()
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.
Rectangle	boundingBoxOf(GamePiece p)
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.
void	centerAt(Point p)	Center the map at given map coordinates within its JScrollPane container
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.
static void	clearActiveMap()	Repaints the current ActiveMap (see setActiveMap(VASSAL.build.module.Map)) and unmarks it.
protected void	clearMapBorder(Graphics g)	Clears the map border region, if any.
Point	componentCoordinates(Point p)	Deprecated, for removal: This API element is subject to removal in a future version. Use mapToComponent(Point)
Rectangle	componentRectangle(Rectangle r)	Deprecated, for removal: This API element is subject to removal in a future version. Use mapToComponent(Rectangle)
int	componentToDrawing(int c, double os_scale)	Converts an integer value from Component coordinates system to Drawing coordinates for rendering.
Point	componentToDrawing(Point p, double os_scale)	Converts a Point from Component coordinates to Drawing coordinates for rendering.
Rectangle	componentToDrawing(Rectangle r, double os_scale)	Converts a Rectangle from Component coordinates to Drawing coordinates for rendering.
int	componentToMap(int c)	Converts an integer value from swing Component coordinates to the Map's coordinate system.
Point	componentToMap(Point p)	Converts a Point from swing Component coordinates to the Map's coordinate system.
Rectangle	componentToMap(Rectangle r)	Converts a Rectangle from swing Component coordinates to the Map's coordinate system.
protected Window	createParentFrame()	Creates the top-level window for this map.
void	disableKeyListeners()	Restore the previously disabled KeyListeners
void	dragEnter(DropTargetDragEvent dtde)
void	dragExit(DropTargetEvent dte)
void	dragOver(DropTargetDragEvent dtde)	Handles scrolling when dragging an gamepiece to the edge of the window
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
void	drawBoardsInRegion(Graphics g, Rectangle visibleRect)	For each Board overlapping the given region, update the appropriate section of the board image.
void	drawBoardsInRegion(Graphics g, Rectangle visibleRect, Component c)	For each Board overlapping the given region, update the appropriate section of the board image.
void	drawDrawable(Graphics g, boolean aboveCounters)	Draws all of our "Drawable" components.
int	drawingToComponent(int c, double os_scale)	Converts an integer value from Drawing coordinates to swing Component coordinates.
Point	drawingToComponent(Point p, double os_scale)	Converts a Point from Drawing coordinates to swing Component coordinates.
Rectangle	drawingToComponent(Rectangle r, double os_scale)	Converts a Rectangle from Drawing coordinates to swing Component coordinates.
int	drawingToMap(int c, double os_scale)	Converts an integer value from Drawing coordinates to the Map's coordinate system.
Point	drawingToMap(Point p, double os_scale)	Converts a Point from Drawing coordinates to the Map's coordinate system.
Rectangle	drawingToMap(Rectangle r, double os_scale)	Converts a Rectangle from Drawing coordinates to the Map's coordinate system.
void	drawPieces(Graphics g, int xOffset, int yOffset)	Draws the map pieces at a given offset
void	drawPiecesInRegion(Graphics g, Rectangle visibleRect)	Draws all pieces visible in a rectangular area of the map
void	drawPiecesInRegion(Graphics g, Rectangle visibleRect, Component c)	Draws all pieces visible in a rectangular area of the map
void	drop(DropTargetDropEvent dtde)	We put the "drop" in drag-n-drop!
void	dropActionChanged(DropTargetDragEvent dtde)
void	enableKeyListeners()	Save all current Key Listeners and remove them from the map.
void	ensureVisible(Rectangle r)	Ensure that the given region (in map coordinates) is visible.
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.
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.
GamePiece	findPiece(Point pt, PieceFinder finder)	Use the provided PieceFinder instance to locate a visible piece at the given location
Region	findRegion(String name)	Search on all boards for a Region (location on an Irregular Grid) with the given name
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.
Zone	findZone(String name)	Search on all boards for a Zone with the given name
Class<?>[]	getAllowableConfigureComponents()	List of subcomponents which can be added to a Map.
GamePiece[]	getAllPieces()
String[]	getAttributeDescriptions()	This getAttributeDescriptions() will return the items specific to the Toolbar Button - classes extending this should add their own items as well.
String[]	getAttributeNames()	Lists all the buildFile (XML) attribute names for this component.
Class<?>[]	getAttributeTypes()	This getAttributeTypes() will return the items specific to the Toolbar Button - classes extending this should add their own items as well.
String	getAttributeValueString(String key)	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.
VisibilityCondition	getAttributeVisibility(String name)	By default, all attributes are visible
Board	getBoardByName(String name)	Searches our list of boards for one with the given name
int	getBoardCount()
BoardPicker	getBoardPicker()	Every map must include a BoardPicker as one of its build components.
Collection<Board>	getBoards()
Point	getCenter()
String	getChangeFormat()
String	getChangeFormat(boolean noSuppress)
Component	getComponent()	The component to be added to the control window toolbar
static String	getConfigureTypeName()	Gets the generic name for this type of class across all instances of it.
String	getCreateFormat()
String	getDeckNameAt(Point p)	Return the name of the Deck whose position is precisely p
String	getDeckNameContaining(Point p)
protected String	getDefaultWindowTitle()
String	getDescription()
DragGestureListener	getDragGestureListener()
Dimension	getEdgeBuffer()
List<String>	getFormattedStringList()	SearchTarget
HelpFile	getHelpFile()
Highlighter	getHighlighter()
Iterator<Highlighter>	getHighlighters()
String	getId()	Each Map must have a unique String id
String	getIdentifier()	Make a best guess for a unique identifier for the target.
KeyBufferer	getKeyBufferer()
JLayeredPane	getLayeredPane()
String	getLocalizedDeckNameAt(Point p)	Return the localized name of the Deck whose position is precisely p
String	getLocalizedMapName()
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.
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
Point	getLocation(Board b, double zoom)	Gets the location of a board in Map space, based on a passed zoom factor
protected Point2D	getLocation2D(int column, int row, double zoom)
Point2D	getLocation2D(Board b, double zoom)
static Map	getMapById(String id)	Find the map that corresponds to a known unique id
static List<Map>	getMapList()	Utility method to return a List of all map components (on all maps!) in the module.
String	getMapName()
int	getMaxPixelsPerRangeUnit(Point p)
List<String>	getMenuTextList()	SearchTarget
KeyStroke	getMoveKey()	Return the apply-on-move key.
String	getMoveToFormat()
String	getMoveWithinFormat()
String	getMutablePropertiesContainerId()	Return a unique Id for the container
MutableProperty	getMutableProperty(String name)	Find a contained Global Property (variable) by name.
List<NamedKeyStroke>	getNamedKeyStrokeList()	SearchTarget
PieceCollection	getPieceCollection()
PieceMover	getPieceMover()
float	getPieceOpacity()
GamePiece[]	getPieces()
Point	getPreferredCenter()
Dimension	getPreferredSize()
Object	getProperty(Object key)	Gets the value of a map-level global property.
List<String>	getPropertyNames()	Override this method to provide a list of properties to be exposed for use by expressions in the module.
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).
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
JToolBar	getToolBar()	Every map window has a toolbar, and this method returns swing toolbar component for this map.
JComponent	getView()
Rectangle	getVisibleRect()
double	getZoom()	If the map has a Zoomer (see setZoomer(VASSAL.build.module.map.Zoomer)), then returns the Zoomer's current zoom factor.
Zoomer	getZoomer()	A map may include a Zoomer as one of its build components.
void	hideMap()
int	indexOf(GamePiece s)	Returns the index of a piece.
boolean	isAnyMouseoverDrawn()
static boolean	isChangeReportingEnabled()
boolean	isDrawingMouseOver()
boolean	isFirstMap()
boolean	isLocationRestricted(Point p)
boolean	isMarkMoved()
boolean	isNotPieceDrag(Transferable trans)
boolean	isOnlyReportChangedLocation()
boolean	isPiecesVisible()
boolean	isVisibleToAll()	Is this map visible to all players?
String	localizedLocationName(Point p)
String	locationName(Point p)
Point	mapCoordinates(Point p)	Deprecated, for removal: This API element is subject to removal in a future version. Use componentToMap(Point)
Rectangle	mapRectangle(Rectangle r)	Deprecated, for removal: This API element is subject to removal in a future version. Use componentToMap(Rectangle)
Dimension	mapSize()
int	mapToComponent(int c)	Converts an integer value from the Map's coordinate system to Component coordinates used for interactions between swing components.
Point	mapToComponent(Point p)	Converts a Point from the Map's coordinate system to Component coordinates used for interactions between swing components.
Rectangle	mapToComponent(Rectangle r)	Converts a Rectangle from the Map's coordinate system to Component coordinates used for interactions between swing components.
int	mapToDrawing(int c, double os_scale)	Converts an integer value from the Map's coordinate system to Drawing coordinates for rendering.
Point	mapToDrawing(Point p, double os_scale)	Converts a point from the Map's coordinate system to Drawing coordinates for rendering.
Rectangle	mapToDrawing(Rectangle r, double os_scale)	Converts a rectangle from the Map's coordinate system to Drawing coordinates for rendering.
void	mouseClicked(MouseEvent e)	Mouse events are first translated into map coordinates.
void	mouseDragged(MouseEvent e)	Mouse motion events are not forwarded to LocalMouseListeners or to listeners on the stack.
void	mouseEntered(MouseEvent e)
void	mouseExited(MouseEvent e)
void	mouseMoved(MouseEvent e)	Mouse motion events are not forwarded to LocalMouseListeners or to listeners on the stack
void	mousePressed(MouseEvent e)	Mouse events are first translated into map coordinates.
void	mouseReleased(MouseEvent e)	Mouse events are first translated into map coordinates.
void	paintRegion(Graphics g, Rectangle visibleRect)	Paints a specific region of the map, denoted by a Rectangle.
void	paintRegion(Graphics g, Rectangle visibleRect, Component c)	Paints a specific region of the map, denoted by a Rectangle.
Command	placeAt(GamePiece piece, Point pt)	Place a piece at the destination point.
Command	placeOrMerge(GamePiece p, Point pt)	Move a piece to the destination point.
void	popMouseListener()	MouseListeners on a map may be pushed and popped onto a stack.
void	popMouseListener(MouseListener l)	Remove the most recently pushed mouse listener only if it is the supplied listener
Point	positionOf(GamePiece p)
void	pushMouseListener(MouseListener l)	MouseListeners on a map may be pushed and popped onto a stack.
void	removeDrawComponent(Drawable theComponent)	Unregister a Drawable component from this map
void	removeFrom(Buildable b)	Unregisters this Map from its Buildable parent (usually a GameModule), reversing the process of addTo(VASSAL.build.Buildable).
void	removeHighlighter(Highlighter h)
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.
MutableProperty	removeMutableProperty(String key)	Removes a new Global Property from this map.
void	removePiece(GamePiece p)	Removes a piece from the map
void	repaint()	Repaints the map.
void	repaint(boolean cf)	Repaints the map.
void	repaint(Rectangle r)	Repaint the given area, specified in map coordinates
protected int	scale(int c, double zoom)	Scales an integer value to a zoom factor
protected Point	scale(Point p, double zoom)	Scales a point to a zoom factor
protected Rectangle	scale(Rectangle r, double zoom)	Scales a Rectangle to a zoom factor
void	scroll(int dx, int dy)	Scrolls the map in the containing JScrollPane.
void	scrollAtEdge(Point evtPt, int dist)	Begin autoscrolling the map if the given point is within the given distance from a viewport edge.
Rectangle	selectionBoundsOf(GamePiece p)
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.
void	setAnyMouseoverDrawn(boolean flag)
void	setAttribute(String key, Object value)	Sets a buildFile (XML) attribute value for this component.
protected void	setBoardBoundaries()	Adjusts the bounds() rectangle to account for the Board's relative position to other boards.
void	setBoardPicker(BoardPicker picker)	Every map must include a single BoardPicker as one of its build components.
void	setBoards(Collection<Board> c)	Set the boards for this map.
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.
void	setDragGestureListener(DragGestureListener dragGestureListener)	This listener will be notified when a drag event is initiated, assuming that no MouseListeners are on the stack.
void	setDrawingMouseOver(boolean flag)
void	setHighlighter(Highlighter h)
void	setId(String id)	Each Map must have a unique String id Sets our unique ID (among Maps), so that e.g.
void	setKeyBufferer(KeyBufferer kb)	Registers the keyBufferer for this map (old way of scanning through components to find one is silly)
void	setMapName(String s)
void	setPieceCollection(PieceCollection pieces)
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.
void	setPieceOpacity(float pieceOpacity)
void	setPiecesVisible(boolean show)
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.
void	setup(boolean show)	When a game is started, create a top-level window, if none exists.
void	setUpView()	Common view setup code for Map and PrivateMap, which confusingly have different View classes that sharing the same name
void	setZoomer(Zoomer z)	A map may include a single Zoomer as one of its build components.
boolean	shouldDockIntoMainWindow()	If this map shows with its own special button, it does not dock into the main window.
void	showMap()
void	sideChanged(String oldSide, String newSide)	Takes action when the local player has switched sides.
Point	snapTo(Point p)
Point	snapTo(Point p, boolean force)
Point	snapTo(Point p, boolean force, boolean onlyCenter)
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.
void	updateCenter()	Accepts the current actual center of the map as the new "preferred center" (e.g.
void	updateTitleBar()	Updates the title bar of the current window

Methods inherited from class VASSAL.build.AbstractToolbarItem

addPropertyGateListener, addPropertyGateListener, checkDisabled, disableIfTrue, getLaunchButton, getNameKey, getPropertyList, isShowDisabledOptions, makeLaunchButton, propertyChange, removePropertyGateListener, setButtonTextKey, setHotKeyKey, setIconKey, setLaunchButton, setNameKey, setNamePrompt, setShowDisabledOptions, setTooltipKey

Methods inherited from class VASSAL.build.AbstractConfigurable

add, addPropertyChangeListener, getConfigureComponents, getConfigureName, getConfigurer, getExpressionList, getI18nData, getI18nPrefix, getLocalizedConfigureName, getTypeName, remove, removePropertyChangeListener, setAllAttributesUntranslatable, setAttributeTranslatable, setConfigureName

Methods inherited from class VASSAL.build.AbstractBuildable

addImageNamesRecursively, buildString, getAllDescendantComponentsOf, getAncestor, getBuildables, getBuildComponents, getBuildElement, getComponents, getComponentsOf, getNonFolderAncestor, setAncestor, validate

Methods inherited from class VASSAL.search.AbstractImageFinder

getAllImageNames, getLocalImageNames

Methods inherited from class java.lang.Object

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

Methods inherited from interface VASSAL.script.expression.Auditable

getComponentName, getComponentTypeName

Methods inherited from interface VASSAL.build.Buildable

add, getBuildElement, isMandatory, isMovable, isUnique

Methods inherited from interface VASSAL.build.Configurable

addPropertyChangeListener, getConfigureComponents, getConfigureName, getConfigurer, remove

Methods inherited from interface VASSAL.tools.ToolBarComponent

updateToolbarButtons

Methods inherited from interface VASSAL.i18n.Translatable

getI18nData

Methods inherited from interface VASSAL.tools.UniqueIdManager.Identifyable

getConfigureName

Field Details

changeReportingEnabled

protected static boolean changeReportingEnabled

mapID

protected String mapID

mapName

protected String mapName

idMgr

protected static final UniqueIdManager idMgr

theMap

protected JPanel theMap

drawComponents

protected ArrayList<Drawable> drawComponents

layeredPane

protected JLayeredPane layeredPane

scroll

protected JScrollPane scroll

mainWindowDock

@Deprecated(since="2020-11-05",
            forRemoval=true)
protected ComponentSplitter.SplitPane mainWindowDock

Deprecated, for removal: This API element is subject to removal in a future version.

splitPane

protected SplitPane splitPane

picker

protected BoardPicker picker

toolBar

protected JToolBar toolBar

zoom

protected Zoomer zoom

metrics

protected StackMetrics metrics

edgeBuffer

protected Dimension edgeBuffer

bgColor

protected Color bgColor

launchButton

@Deprecated(since="2021-04-03",
            forRemoval=true)
protected LaunchButton launchButton

Deprecated, for removal: This API element is subject to removal in a future version.

use launch from the superclass

useLaunchButton

protected boolean useLaunchButton

useLaunchButtonEdit

protected boolean useLaunchButtonEdit

markMovedOption

protected String markMovedOption

markUnmovedIcon

protected String markUnmovedIcon

markUnmovedText

protected String markUnmovedText

markUnmovedTooltip

protected String markUnmovedTooltip

markUnmovedHotkey

protected NamedKeyStroke markUnmovedHotkey

markUnmovedReport

protected String markUnmovedReport

multicaster

protected MouseListener multicaster

mouseListenerStack

protected ArrayList<MouseListener> mouseListenerStack

boards

protected List<Board> boards

boardWidths

protected int[][] boardWidths

boardHeights

protected int[][] boardHeights

pieces

protected PieceCollection pieces

highlighter

protected Highlighter highlighter

highlighters

protected ArrayList<Highlighter> highlighters

clearFirst

protected boolean clearFirst

hideCounters

protected boolean hideCounters

pieceOpacity

protected float pieceOpacity

allowMultiple

protected boolean allowMultiple

visibilityCondition

protected VisibilityCondition visibilityCondition

dragGestureListener

protected DragGestureListener dragGestureListener

onlyReportChangedLocation

protected boolean onlyReportChangedLocation

moveWithinFormat

protected String moveWithinFormat

moveToFormat

protected String moveToFormat

createFormat

protected String createFormat

changeFormat

protected String changeFormat

moveKey

protected NamedKeyStroke moveKey

tooltip

protected String tooltip

propsContainer

protected MutablePropertiesContainer propsContainer

repaintOnPropertyChange

protected PropertyChangeListener repaintOnPropertyChange

pieceMover

protected PieceMover pieceMover

keyBufferer

protected KeyBufferer keyBufferer

saveKeyListeners

protected KeyListener[] saveKeyListeners

showKeyListener

protected NamedKeyStrokeListener showKeyListener

hideKeyListener

protected NamedKeyStrokeListener hideKeyListener

description

protected String description

preferredCenter

protected Point preferredCenter

NAME

public static final String NAME

See Also:

• Constant Field Values

DESCRIPTION

public static final String DESCRIPTION

See Also:

• Constant Field Values

MARK_MOVED

public static final String MARK_MOVED

See Also:

• Constant Field Values

MARK_UNMOVED_ICON

public static final String MARK_UNMOVED_ICON

See Also:

• Constant Field Values

MARK_UNMOVED_TEXT

public static final String MARK_UNMOVED_TEXT

See Also:

• Constant Field Values

MARK_UNMOVED_TOOLTIP

public static final String MARK_UNMOVED_TOOLTIP

See Also:

• Constant Field Values

MARK_UNMOVED_HOTKEY

public static final String MARK_UNMOVED_HOTKEY

See Also:

• Constant Field Values

MARK_UNMOVED_REPORT

public static final String MARK_UNMOVED_REPORT

See Also:

• Constant Field Values

EDGE_WIDTH

public static final String EDGE_WIDTH

See Also:

• Constant Field Values

EDGE_HEIGHT

public static final String EDGE_HEIGHT

See Also:

• Constant Field Values

BACKGROUND_COLOR

public static final String BACKGROUND_COLOR

See Also:

• Constant Field Values

HIGHLIGHT_COLOR

public static final String HIGHLIGHT_COLOR

See Also:

• Constant Field Values

HIGHLIGHT_THICKNESS

public static final String HIGHLIGHT_THICKNESS

See Also:

• Constant Field Values

ALLOW_MULTIPLE

public static final String ALLOW_MULTIPLE

See Also:

• Constant Field Values

USE_LAUNCH_BUTTON

public static final String USE_LAUNCH_BUTTON

See Also:

• Constant Field Values

BUTTON_NAME

public static final String BUTTON_NAME

See Also:

• Constant Field Values

TOOLTIP

public static final String TOOLTIP

See Also:

• Constant Field Values

ICON

public static final String ICON

See Also:

• Constant Field Values

HOTKEY

public static final String HOTKEY

See Also:

• Constant Field Values

SUPPRESS_AUTO

public static final String SUPPRESS_AUTO

See Also:

• Constant Field Values

ONLY_REPORT_CHANGED_LOCATION

public static final String ONLY_REPORT_CHANGED_LOCATION

See Also:

• Constant Field Values

MOVE_WITHIN_FORMAT

public static final String MOVE_WITHIN_FORMAT

See Also:

• Constant Field Values

MOVE_TO_FORMAT

public static final String MOVE_TO_FORMAT

See Also:

• Constant Field Values

CREATE_FORMAT

public static final String CREATE_FORMAT

See Also:

• Constant Field Values

CHANGE_FORMAT

public static final String CHANGE_FORMAT

See Also:

• Constant Field Values

MOVE_KEY

public static final String MOVE_KEY

See Also:

• Constant Field Values

MOVING_STACKS_PICKUP_UNITS

public static final String MOVING_STACKS_PICKUP_UNITS

See Also:

• Constant Field Values

SHOW_KEY

public static final String SHOW_KEY

See Also:

• Constant Field Values

HIDE_KEY

public static final String HIDE_KEY

See Also:

• Constant Field Values

activeMap

public static Map activeMap

DEFAULT_EDGE_SCROLL_DELAY_PROPERTY

protected static final String DEFAULT_EDGE_SCROLL_DELAY_PROPERTY

See Also:

• Constant Field Values

DEFAULT_EDGE_SCROLL_ZONE_PROPERTY

protected static final String DEFAULT_EDGE_SCROLL_ZONE_PROPERTY

See Also:

• Constant Field Values

DEFAULT_EDGE_SCROLL_RATE_PROPERTY

protected static final String DEFAULT_EDGE_SCROLL_RATE_PROPERTY

See Also:

• Constant Field Values

PREFERRED_EDGE_SCROLL_DELAY

public static final int PREFERRED_EDGE_SCROLL_DELAY

See Also:

• Constant Field Values

PREFERRED_EDGE_DELAY

public static final String PREFERRED_EDGE_DELAY

See Also:

• Constant Field Values

PREFERRED_EDGE_SCROLL_ZONE_STANDARD_DEFAULT

public static final int PREFERRED_EDGE_SCROLL_ZONE_STANDARD_DEFAULT

The width of the hot zone for triggering autoscrolling.

See Also:

• Constant Field Values

SCROLL_ZONE

public static int SCROLL_ZONE

PREFERRED_SCROLL_ZONE

public static final String PREFERRED_SCROLL_ZONE

See Also:

• Constant Field Values

PREFERRED_EDGE_SCROLL_RATE_STANDARD_DEFAULT

public static final double PREFERRED_EDGE_SCROLL_RATE_STANDARD_DEFAULT

The rate at which things scroll

See Also:

• Constant Field Values

EDGE_SCROLL_RATE

public static double EDGE_SCROLL_RATE

PREFERRED_EDGE_SCROLL_RATE

public static final String PREFERRED_EDGE_SCROLL_RATE

See Also:

• Constant Field Values

sx

protected int sx

The horizontal component of the autoscrolling vector, -1, 0, or 1.

sy

protected int sy

The vertical component of the autoscrolling vector, -1, 0, or 1.

dx

protected int dx

dy

protected int dy

scroller

protected org.jdesktop.animation.timing.Animator scroller

The animator which controls autoscrolling.

LOCATION

public static final String LOCATION

See Also:

• Constant Field Values

OLD_LOCATION

public static final String OLD_LOCATION

See Also:

• Constant Field Values

OLD_MAP

public static final String OLD_MAP

See Also:

• Constant Field Values

MAP_NAME

public static final String MAP_NAME

See Also:

• Constant Field Values

PIECE_NAME

public static final String PIECE_NAME

See Also:

• Constant Field Values

MESSAGE

public static final String MESSAGE

See Also:

• Constant Field Values

Constructor Details

Map

public Map()

Method Details

isAnyMouseoverDrawn

public boolean isAnyMouseoverDrawn()

setAnyMouseoverDrawn

public void setAnyMouseoverDrawn(boolean flag)

isDrawingMouseOver

public boolean isDrawingMouseOver()

setDrawingMouseOver

public void setDrawingMouseOver(boolean flag)

showMap

public void showMap()

hideMap

public void hideMap()

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)

isMarkMoved

public boolean isMarkMoved()

Returns:

true if the map marks pieces as moved

isOnlyReportChangedLocation

public boolean isOnlyReportChangedLocation()

Returns:

true if auto-reporting moves should only happen if location changed

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

getPieceMover

public PieceMover getPieceMover()

Returns:

Our pieceMover

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

getKeyBufferer

public KeyBufferer getKeyBufferer()

Returns:

KeyBufferer (if any) for this map.

setKeyBufferer

public void setKeyBufferer(KeyBufferer kb)

Registers the keyBufferer for this map (old way of scanning through components to find one is silly)

Parameters:

kb - KeyBufferer

getDescription

public String getDescription()

Specified by:

getDescription in interface ComponentDescription

Returns:

Map's description field

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.

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

getMaxPixelsPerRangeUnit

public int getMaxPixelsPerRangeUnit(Point p)

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,
 boolean force,
 boolean onlyCenter)

Returns:

the nearest allowable point according to the MapGrid on the Board at this point

See Also:

• Board.snapTo(java.awt.Point, boolean, boolean)
• MapGrid.snapTo(java.awt.Point)

snapTo

public Point snapTo(Point p,
 boolean force)

snapTo

public Point snapTo(Point p)

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.

Use 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 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 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 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 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 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 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 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 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 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 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 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 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 Deck 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 Deck 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

isNotPieceDrag

public boolean isNotPieceDrag(Transferable trans)

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

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

public 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

getLocation2D

public Point2D getLocation2D(Board b,
 double zoom)

getLocation2D

protected Point2D getLocation2D(int column,
 int row,
 double zoom)

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

getPropertyNames

public List<String> getPropertyNames()

Description copied from class: AbstractBuildable

Override this method to provide a list of properties to be exposed for use by expressions in the module.

Specified by:

getPropertyNames in interface PropertyNameSource

Overrides:

getPropertyNames in class AbstractBuildable

Returns:

Default implementation of PropertyNameSource - No properties exposed

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

isFirstMap

public boolean isFirstMap()

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

Overrides:

setup in class AbstractToolbarItem

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

Overrides:

getRestoreCommand in class AbstractToolbarItem

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

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

updateCenter

public void updateCenter()

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)

getPreferredCenter

public Point getPreferredCenter()

Returns:

last location the player has requested to be the center of the map (eg by manually clicking or scrolling)

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

getVisibleRect

public Rectangle getVisibleRect()

Returns:

the current visible rect of our map

getCenter

public Point getCenter()

Returns:

the point our map's view is currently centered on

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

getChangeFormat

public String getChangeFormat(boolean noSuppress)

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 AbstractToolbarItem

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

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

setUpView

public void setUpView()

Common view setup code for Map and PrivateMap, which confusingly have different View classes that sharing the same name

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