Package VASSAL.counters

Class Stack

java.lang.Object
VASSAL.search.AbstractImageFinder
VASSAL.counters.Stack
All Implemented Interfaces:
PropertySource, GamePiece, StateMergeable, ImageSearchTarget
Direct Known Subclasses:
Deck
public class Stack extends AbstractImageFinder implements GamePiece, StateMergeable
A Stack is a collection of pieces in the same location that can often be moved with a single drag-and-drop. Because it implements the GamePiece interface, a Stack is formally a kind of GamePiece itself, which can lead to confusion when the terms pieces, GamePieces, etc are used loosely/interchangeably. The kind of "pieces" a Stack contains are the "regular" kind of pieces that have a BasicPiece plus an optional group of Decorator traits.

A standard Stack will only contain pieces that are "stackable" (i.e. doesn't have a "Does Not Stack" Immobilized trait, so that Properties.NO_STACK is false) and share the same X/Y position on the same Map, and all stackable pieces on a Map will always be part of some Stack -- even single stackable pieces will have a Stack created to contain them. Stacks should contain only pieces from the same visual layer (see LayeredPieceCollection), but presently bad behaviors can still develop (e.g. a piece uses a Dynamic Property to control its Game Piece Layer, and ends up changing layers without the Stack noticing) -- ideally we should straighten that out in future versions.

Deck is a further extension of Stack which utilizes the piece-grouping code but overrides other aspects (e.g. can allow pieces regardless of their "stackability", has different drag-and-drop behavior, etc) to create a different kind of grouping.

  • Field Details

  • Constructor Details

    • Stack

      public Stack()

    • Stack

      public Stack​(GamePiece p)
      Creates a Stack to contain a specific stackable piece.
      Parameters:
      p - piece to make a stack for

  • Method Details

    • getPiecesIterator

      public Iterator<GamePiece> getPiecesIterator()

    • getPieces

      @Deprecated(since="2020-08-06", forRemoval=true) public Enumeration<GamePiece> getPieces()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use asList()
      Returns:
      an Enumeration of the pieces in the stack, from the bottom up This is a clone of the contents so add/remove operations during read won't affect it.

    • asList

      public List<GamePiece> asList()
      A list of the pieces in the stack.
      Returns:
      a List which is a defensive copy of GamePieces contained in this Stack

    • getPiecesReverseIterator

      public Iterator<GamePiece> getPiecesReverseIterator()

    • getPiecesInReverseOrder

      @Deprecated(since="2020-08-06", forRemoval=true) public Enumeration<GamePiece> getPiecesInReverseOrder()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getPiecesInVisibleOrderIterator()
      Return an enumeration of the pieces in the start, from the top down
      Returns:
      Reverse order Enumerator

    • getPiecesInVisibleOrderIterator

      public Iterator<GamePiece> getPiecesInVisibleOrderIterator()
      Returns pieces in the order in which they are visible to the player -- topmost first In other words, selected pieces first, then unselected pieces from the top to the bottom.
      Returns:
      iterator

    • getPiecesInVisibleOrder

      @Deprecated(since="2020-08-06", forRemoval=true) public Enumeration<GamePiece> getPiecesInVisibleOrder()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getPiecesInVisibleOrderIterator()
      Returns pieces in the order in which they are visible to the player -- topmost first In other words, selected pieces first, then unselected pieces from the top to the bottom.

    • getLayer

      public int getLayer()
      Returns:
      the visual layer we're bound to, or LAYER_NOT_SET if it we haven't been bound yet. Keeps the stack oriented to its correct Game Piece Layer - see LayeredPieceCollection

    • remove

      public void remove​(GamePiece p)
      Parameters:
      p - Piece to remove from the stack

    • removePieceAt

      protected void removePieceAt​(int index)
      Parameters:
      index - Index of piece to remove from the stack

    • pieceRemoved

      public Command pieceRemoved​(GamePiece p)
      Perform some action on a GamePiece that has just been removed this Stack
      Parameters:
      p - GamePiece
      Returns:
      a Command that performs the equivalent action when executed

    • insertPieceAt

      protected void insertPieceAt​(GamePiece p, int index)
      Insert a piece at a particular point in the stack
      Parameters:
      p - piece to insert
      index - place to insert it

    • removeAll

      public void removeAll()
      Marks the stack as empty

    • indexOf

      public int indexOf​(GamePiece p)
      Finds the index of a piece in the stack
      Parameters:
      p - Piece to locate
      Returns:
      The index of the piece, or -1 if it is not present in the stack

    • getPieceAt

      public GamePiece getPieceAt​(int index)
      Parameters:
      index - Index in the stack
      Returns:
      the piece at the specified index

    • add

      public void add​(GamePiece c)
      Adds a piece to the stack. If the piece already exists in the stack, moves it to the top
      Parameters:
      c - Stack to add piece to

    • insertChild

      public void insertChild​(GamePiece child, int index)
      Adds a GamePiece to this Stack. Slightly more efficient than insert(VASSAL.counters.GamePiece, int) because it assumes the piece does not already belong to this Stack.
      Parameters:
      child - GamePiece to insert
      index - Insert Index

    • getPieceCount

      public int getPieceCount()
      Returns:
      the number of pieces in the stack

    • getMaximumVisiblePieceCount

      public int getMaximumVisiblePieceCount()
      Return the number of pieces that could possible be drawn in the stack, regardless of visibility to any particular player
      Returns:
      Piece Count

    • insert

      public void insert​(GamePiece p, int pos)
      Inserts a child GamePiece at a given index. If the child piece already belongs to this Stack, it will be repositioned to the given index.
      Parameters:
      p - GamePiece to insert
      pos - Insert position

    • pieceAdded

      public Command pieceAdded​(GamePiece p)
      Perform some action on a GamePiece that has just been added to this Stack
      Parameters:
      p - Game Piece
      Returns:
      a Command that performs the equivalent action when executed

    • draw

      public void draw​(Graphics g, int x, int y, Component obs, double zoom)
      If the obs parameter is a Map, delegate drawing of this Stack to the StackMetrics of that Map. If obs is not a Map, use the default StackMetrics
      Specified by:
      draw in interface GamePiece
      Parameters:
      g - target Graphics object
      x - x-location of the center of the piece
      y - y-location of the center of the piece
      obs - the Component on which this piece is being drawn
      zoom - the scaling factor.
      See Also:
      StackMetrics.draw(VASSAL.counters.Stack, java.awt.Graphics, int, int, java.awt.Component, double), getDefaultMetrics()

    • getName

      public String getName​(boolean localized)
      Parameters:
      localized - if true, use the localized names
      Returns:
      a comma-separated list of the names of the pieces in this Stack

    • getName

      public String getName()
      Description copied from interface: GamePiece
      The plain English name for this piece
      Specified by:
      getName in interface GamePiece
      Returns:
      a comma-separated list of the (non-localized) names of the pieces in this Stack

    • getLocalizedName

      public String getLocalizedName()
      Description copied from interface: GamePiece
      And the translated name for this piece
      Specified by:
      getLocalizedName in interface GamePiece
      Returns:
      a comma-separated list of the (localized) names of the pieces in this Stack

    • boundingBox

      public Rectangle boundingBox()
      Specified by:
      boundingBox in interface GamePiece
      Returns:
      bounding box for the stack (minimum rectangle to contain the bounding boxes of all the pieces inside)

    • getShape

      public Shape getShape()
      Specified by:
      getShape in interface GamePiece
      Returns:
      shape for the stack (shape to contain the shapes of all the pieces inside)

    • selectNext

      public void selectNext​(GamePiece c)
      Finds and selects (in the UI) the next piece in the stack after this one
      Parameters:
      c - Starting piece

    • getPieceBeneath

      public GamePiece getPieceBeneath​(GamePiece p)
      Finds the piece "underneath" the one provided
      Parameters:
      c - Starting piece
      Returns:
      piece underneath it, or null if none.

    • getPieceAbove

      public GamePiece getPieceAbove​(GamePiece p)
      Finds the piece "above" the one provided
      Parameters:
      c - Starting piece
      Returns:
      piece above it, or null if none.

    • topPiece

      public GamePiece topPiece()
      CAUTION: returns the top VISIBLE piece in the stack, or null if none is visible.
      Returns:
      the top visible piece in this stack

    • topPiece

      public GamePiece topPiece​(String playerId)
      Parameters:
      playerId - Player Id to check
      Returns:
      the top piece in this stack that is visible to the player with the given id
      See Also:
      GameModule.getUserId()

    • bottomPiece

      public GamePiece bottomPiece​(String playerId)
      Parameters:
      playerId - Player Id to Check
      Returns:
      the bottom piece in this stack that is visible to the player with the given id
      See Also:
      GameModule.getUserId()

    • bottomPiece

      public GamePiece bottomPiece()
      Returns:
      the bottom visible piece in this stack

    • nVisible

      protected int nVisible()
      Returns:
      Number of GamePieces that are visible to me

    • keyEvent

      public Command keyEvent​(KeyStroke stroke)
      Processes a key command for this stack, by sending it to the top visible piece in the stack.
      Specified by:
      keyEvent in interface GamePiece
      Parameters:
      stroke - keystroke to process
      Returns:
      Command encapsulating anything that happened as a result
      See Also:
      ForwardToKeyBuffer

    • isExpanded

      public boolean isExpanded()
      Returns:
      true if stack has been visually expanded by the player

    • setExpanded

      public void setExpanded​(boolean b)
      Sets the expansion state of the stack. Players can expand (and un-expand) stacks by e.g. double-clicking on them. Expanded stacks are generally shown with the pieces drawn further apart, the better to see the individual pieces. When a stack is expanded, drag-and-drop operations can affect an individual piece rather than only the whole group.
      Parameters:
      b - true if stack should be expanded, false if not

    • getState

      public String getState()
      Encodes the game state information of the stack into a string
      Specified by:
      getState in interface GamePiece
      Returns:
      Current encoded "game state" string for the stack

    • setState

      public void setState​(String s)
      Decodes the game state information of the stack from a string
      Specified by:
      setState in interface GamePiece
      Parameters:
      s - Game state information to be loaded into the stack

    • mergeState

      public void mergeState​(String newState, String oldState)
      Compute the difference between newState and oldState and apply that difference to the current state
      Specified by:
      mergeState in interface StateMergeable
      Parameters:
      newState - New State
      oldState - Old State

    • getType

      public String getType()
      Specified by:
      getType in interface GamePiece
      Returns:
      the encoding type
      See Also:
      BasicCommandEncoder

    • setProperty

      public void setProperty​(Object key, Object val)
      Stacks themselves ignore property sets -- use setPropertyOnContents(java.lang.Object,java.lang.Object) to apply a property to the members of a stack.
      Specified by:
      setProperty in interface GamePiece
      Parameters:
      key - String key of property to be changed
      val - Object containing new value of the property

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      string list of stack contents, for debugging-type purposes

    • setPropertyOnContents

      public void setPropertyOnContents​(Object key, Object val)
      Calls setProperty() on each piece in this stack
      Parameters:
      key - Property Key
      val - Property Value

    • getProperty

      public Object getProperty​(Object key)
      Stacks themselves do not have any properties, so always return null.
      Specified by:
      getProperty in interface GamePiece
      Specified by:
      getProperty in interface PropertySource
      Parameters:
      key - String key of property to be returned
      Returns:
      always null

    • getLocalizedProperty

      public Object getLocalizedProperty​(Object key)
      Stacks themselves do not have any properties, so always return null.
      Specified by:
      getLocalizedProperty in interface PropertySource
      Parameters:
      key - String key of property to be returned
      Returns:
      always null

    • setMap

      public void setMap​(Map map)
      Specified by:
      setMap in interface GamePiece
      Parameters:
      map - Each stack belongs to a single Map

    • getMap

      public Map getMap()
      Specified by:
      getMap in interface GamePiece
      Returns:
      the map for this Stack

    • getPosition

      public Point getPosition()
      Specified by:
      getPosition in interface GamePiece
      Returns:
      current X/Y position of stack

    • setPosition

      public void setPosition​(Point p)
      Specified by:
      setPosition in interface GamePiece
      Parameters:
      p - Sets the location of this stack on its Map

    • getParent

      public Stack getParent()
      Stacks cannot contain other stacks/decks, nor be contained in them, so parent is always null.
      Specified by:
      getParent in interface GamePiece
      Returns:
      always null

    • setParent

      public void setParent​(Stack s)
      Required for interface but won't be needed for stacks
      Specified by:
      setParent in interface GamePiece
      Parameters:
      s - sets the Stack to which this piece belongs.

    • getId

      public String getId()
      Description copied from interface: GamePiece
      Each GamePiece must have a unique String identifier
      Specified by:
      getId in interface GamePiece
      Returns:
      stack's unique ID
      See Also:
      GameState.getNewPieceId()

    • setId

      public void setId​(String id)
      Description copied from interface: GamePiece
      Each GamePiece must have a unique String identifier
      Specified by:
      setId in interface GamePiece
      Parameters:
      id - sets unique ID for this piece
      See Also:
      GameState.getNewPieceId()

    • setDefaultMetrics

      public static void setDefaultMetrics​(StackMetrics s)
      StackMetrics encapsulate information on how to draw expanded/unexpanded views of stacks. This method sets the default metrics for the module, but each map can have its own configuration, which can be found in the [Stacking options] subcomponent of the Map in the Editor.
      Parameters:
      s - default stack metrics for the module

    • getStackMetrics

      public StackMetrics getStackMetrics​(Map m)
      StackMetrics encapsulate information on how to draw expanded/unexpanded views of stacks. This method retrieves the appropriate stack metrics to use for a given map
      Parameters:
      m - a map
      Returns:
      stack metrics for the map, if provided, or the default one for the module.

    • getStackMetrics

      public StackMetrics getStackMetrics()
      StackMetrics encapsulate information on how to draw expanded/unexpanded views of stacks. This method retrieves the appropriate stack metrics to use the stack, based on its map
      Returns:
      stack metrics for the map, if provided, or the default one for the module.

    • getDefaultMetrics

      public StackMetrics getDefaultMetrics()
      StackMetrics encapsulate information on how to draw expanded/unexpanded views of stacks. This method retrieves the default stack metrics for the module.
      Returns:
      default stack metrics for the module

    • addImageNamesRecursively

      public void addImageNamesRecursively​(Collection<String> s)
      See AbstractImageFinder Tells each of the pieces in the stack to add its images to the collection
      Specified by:
      addImageNamesRecursively in interface ImageSearchTarget
      Overrides:
      addImageNamesRecursively in class AbstractImageFinder
      Parameters:
      s - Collection to add image names to