Package gamedata

Class Expansion

  • All Implemented Interfaces:
    IconProvider, java.lang.Comparable<Expansion>
    public final class Expansion
extends java.lang.Object
implements java.lang.Comparable<Expansion>, IconProvider
    The expansion class represents an expansion for a Game. Components can include a symbol to indicate that they are from a given expansion. This can be done automatically, if certain keys are set for the component and appropriate graphics are registered along with the expansion. Alternatively, a flag can be set when registering an expansion to indicate that it is drawn using custom code (the component is responsible for drawing).
    Since:
    3.0a14
    Author:
    Chris Jennings

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String EXPANSION_SETTING_KEY
      This key is updated on a component's private settings when a new expansion is selected.
      static RegistrationEventSource<Expansion> Listeners
      Listeners that will receive notification of new registrations.
      static java.lang.String VARIANT_SETTING_KEY
      This key is updated on a component's private settings when a new symbol variant is selected.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      int compareTo​(Expansion o)
      Sorts groups of expansions by game and then by expansion name.
      static java.lang.String generateEndUserIdentifier​(Game game)
      Generates a unique expansion identifier.
      static Expansion get​(java.lang.String id)
      Return the expansion with the requested identifier, or null if there is no such expansion.
      static Expansion getBaseGameExpansion()
      Returns the base game "expansion".
      java.lang.String getCode()
      Returns the unique code for this expansion.
      static java.util.Set<Expansion> getComponentExpansionSymbols​(GameComponent gc)
      Returns a new, modifiable set of the expansions set on a game component by reading the value of the component's EXPANSION_SETTING_KEY private setting.
      static Expansion[] getExpansions()
      Returns an array of all registered expansions.
      static Expansion[] getExpansionsForGame​(Game game, boolean includeGenerics)
      Returns an array of the expansions that have been registered for a specific game.
      Game getGame()
      Returns the game that this expansion belongs to.
      java.lang.String getGameName()
      Returns the expansion's name in the game locale.
      javax.swing.Icon getIcon()
      Returns the icon used to represent the expansion in the interface.
      java.awt.image.BufferedImage getSymbol​(boolean inverse)
      Deprecated.
      This method is provided to ease migration from SE 2.x.
      java.awt.image.BufferedImage getSymbol​(int customSymbolIndex)
      Returns a symbol that is associated with this expansion.
      java.lang.String getUIName()
      Returns the expansion's name in the interface locale.
      static Expansion register​(Game forGame, java.lang.String code, java.lang.String uiName, java.lang.String gameName, java.awt.image.BufferedImage iconImage, java.awt.image.BufferedImage[] symbols)
      Deprecated.
      static Expansion register​(Game forGame, java.lang.String code, java.lang.String uiName, java.lang.String gameName, java.lang.String iconResource, java.awt.image.BufferedImage[] symbols)  
      static Expansion register​(Game forGame, java.lang.String code, java.lang.String nameKey, java.lang.String iconResource, java.lang.String normalSymbol, java.lang.String inverseSymbol)
      Deprecated.
      This method is provided to ease migration from SE 2.x.
      static Expansion register​(Game forGame, java.lang.String code, java.lang.String uiName, java.lang.String gameName, javax.swing.Icon icon, java.awt.image.BufferedImage[] symbols)  
      static void setComponentExpansionSymbols​(GameComponent gc, java.util.Set<Expansion> exps)
      Sets the expansion symbols associated with a game component by modifying the component's EXPANSION_SETTING_KEY private setting.
      static void setGameForExpansion​(java.lang.String expansion, java.lang.String game)
      Deprecated.
      This method is used only to allow backwards compatibility with script code from SE 2.x.
      java.lang.String toString()
      Returns a string representation of the expansion.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EXPANSION_SETTING_KEY

        public static final java.lang.String EXPANSION_SETTING_KEY
        This key is updated on a component's private settings when a new expansion is selected.
        See Also:
        Constant Field Values

      • VARIANT_SETTING_KEY

        public static final java.lang.String VARIANT_SETTING_KEY
        This key is updated on a component's private settings when a new symbol variant is selected.
        See Also:
        Constant Field Values

    • Method Detail

      • getCode

        public java.lang.String getCode()
        Returns the unique code for this expansion.
        Returns:
        the code used to register the expansion

      • getGame

        public Game getGame()
        Returns the game that this expansion belongs to. If the expansion does not belong to any particular game, then the special "all games" game is returned.
        Returns:
        the game that the expansion expands upon

      • getGameName

        public java.lang.String getGameName()
        Returns the expansion's name in the game locale.
        Returns:
        the localized game name

      • getUIName

        public java.lang.String getUIName()
        Returns the expansion's name in the interface locale.
        Returns:
        the localized interface name

      • getIcon

        public javax.swing.Icon getIcon()
        Returns the icon used to represent the expansion in the interface.
        Specified by:
        getIcon in interface IconProvider
        Returns:
        the expansion's icon

      • toString

        public java.lang.String toString()
        Returns a string representation of the expansion. This is identical to getUIName().
        Overrides:
        toString in class java.lang.Object
        Returns:
        the interface name of the expansion

      • getSymbol

        @Deprecated
public java.awt.image.BufferedImage getSymbol​(boolean inverse)
        Deprecated.
        This method is provided to ease migration from SE 2.x. It is equivalent to calling getSymbol( inverse ? 1 : 0 ).
        Returns a symbol that is associated with this expansion.
        Parameters:
        inverse - if true, return the symbol for dark backgrounds
        Returns:
        the 0th (if false) or 1st (if true) symbol for the expansion
        See Also:
        getSymbol(int)

      • getSymbol

        public java.awt.image.BufferedImage getSymbol​(int customSymbolIndex)
        Returns a symbol that is associated with this expansion. This method can be used to retrieve extra symbols beyond the standard two types used by the default expansion symbol painting mechanism. Under that mechanism, index 0 is the standard symbol while index 1 is the inverse symbol. However, custom painting methods may assign any interpretation they wish to these indices. If the requested symbol is not defined for this expansion, the symbol at index 0 is returned instead.
        Parameters:
        customSymbolIndex - the index into the passed in array of custom symbols
        Returns:
        the requested symbol, or null if there is no symbol at that index
        Throws:
        java.lang.IllegalArgumentException - if customSymbolIndex is less than 0

      • getExpansions

        public static Expansion[] getExpansions()
        Returns an array of all registered expansions. The returned array will not be shared (that is, the caller can freely modify the contents).
        Returns:
        a new array of the currently registered expansions

      • getExpansionsForGame

        public static Expansion[] getExpansionsForGame​(Game game,
                                               boolean includeGenerics)
        Returns an array of the expansions that have been registered for a specific game. If includeGenerics is true, then expansions registered for all games will also be included.
        Parameters:
        game - the game to find expansions for
        includeGenerics - whether to include generic "all games" expansions
        Returns:
        an array of matching expansions
        Throws:
        java.lang.NullPointerException - if the game is null
        See Also:
        Game.getAllGamesInstance()

      • compareTo

        public int compareTo​(Expansion o)
        Sorts groups of expansions by game and then by expansion name.
        Specified by:
        compareTo in interface java.lang.Comparable<Expansion>
        Parameters:
        o - the expansion to compare this expansion to
        Returns:
        a negative integer, zero, or a positive integer as this expansion is less than, equal to, or greater than the parameter in terms of sort order

      • getBaseGameExpansion

        public static Expansion getBaseGameExpansion()
        Returns the base game "expansion". This is an expansions code that is used to represent no expansion. It is registered for all games, has a blank icon, and null expansion symbol images.
        Returns:
        the shared base game expansion that represents the base version of any game with no expansions

      • get

        public static Expansion get​(java.lang.String id)
        Return the expansion with the requested identifier, or null if there is no such expansion.
        Parameters:
        id - the identifier to look up
        Returns:
        the expansion registered with that identifier, or null

      • register

        @Deprecated
public static Expansion register​(Game forGame,
                                 java.lang.String code,
                                 java.lang.String nameKey,
                                 java.lang.String iconResource,
                                 java.lang.String normalSymbol,
                                 java.lang.String inverseSymbol)
        Deprecated.
        This method is provided to ease migration from SE 2.x. It should not be called by plug-in authors.
        Registers an expansion with "regular" and "inverse" versions of a symbol.
        Parameters:
        forGame - the game to register for, or null for all games
        code - the expansion code
        nameKey - the string table key to use for the name
        iconResource - the location of the icon image to use
        normalSymbol - the location of the normal (dark on light) symbol image
        inverseSymbol - the location of the inverse (light on dark) symbol image, or null to generate one from the normal symbol
        Returns:
        the newly registered expansion
        See Also:
        register(gamedata.Game, java.lang.String, java.lang.String, java.lang.String, java.awt.image.BufferedImage, java.awt.image.BufferedImage[])

      • register

        @Deprecated
public static Expansion register​(Game forGame,
                                 java.lang.String code,
                                 java.lang.String uiName,
                                 java.lang.String gameName,
                                 java.awt.image.BufferedImage iconImage,
                                 java.awt.image.BufferedImage[] symbols)
        Deprecated.
        Register an expansion for a game. The game must have already be registered. Each expansion must have a unique identifier string. An easy way to construct such identifiers is to append the number of the expansion to the game's identifier (e.g., TAL1, TAL2 are the first two expansions for the game with identifier TAL, namely Talisman). Alternatively, you could append a hyphen and short mnemonic for the name of the expansion (TAL-TD, TAL-FM, and so on).

        Note that there is a common "base game" expansion that all games share to indicate that no expansion applies. There is no need to register an expansion for this purpose.

        Parameters:
        forGame - the game to which the expansion belongs, or all games if null
        code - a short unique code string for the expansion, usually 2-6 capital letters
        uiName - the name of the expansion, in the user interface locale
        gameName - the name of the expansion, in the game locale
        iconImage - an image to use to represent the expansion, may be null in which case a default image is used
        symbols - an array of symbol images used to represent the expansion on components
        Returns:
        the registered expansion
        Throws:
        java.lang.NullPointerException - if the code is null
        java.lang.IllegalArgumentException - if the code is empty or contains characters not allowed in a file name, or if an expansion with the same code is already registered and the database is locked
        See Also:
        getBaseGameExpansion()

      • register

        public static Expansion register​(Game forGame,
                                 java.lang.String code,
                                 java.lang.String uiName,
                                 java.lang.String gameName,
                                 java.lang.String iconResource,
                                 java.awt.image.BufferedImage[] symbols)

      • register

        public static Expansion register​(Game forGame,
                                 java.lang.String code,
                                 java.lang.String uiName,
                                 java.lang.String gameName,
                                 javax.swing.Icon icon,
                                 java.awt.image.BufferedImage[] symbols)

      • generateEndUserIdentifier

        public static java.lang.String generateEndUserIdentifier​(Game game)
        Generates a unique expansion identifier. This is not meant for use by plug-ins that are registering standard expansions. Rather, it is intended for use by tools that help end users create their own custom expansions.
        Parameters:
        game - the game that the expansion will be for
        Returns:
        an identifier that is highly likely to be unique across all Strange Eons users, and definitely unique for the current user and session

      • setGameForExpansion

        @Deprecated
public static void setGameForExpansion​(java.lang.String expansion,
                                       java.lang.String game)
        Deprecated.
        This method is used only to allow backwards compatibility with script code from SE 2.x. It should not be called by plug-in authors.
        Sets the game associated with an expansion.
        Parameters:
        expansion - code for the expansion
        game - code for the game to associate it with

      • setComponentExpansionSymbols

        public static void setComponentExpansionSymbols​(GameComponent gc,
                                                java.util.Set<Expansion> exps)
        Sets the expansion symbols associated with a game component by modifying the component's EXPANSION_SETTING_KEY private setting. If the expansion set is null or empty, then the base game expansion will be used.
        Parameters:
        gc - the game component to modify
        exps - a set of the expansions to associate with the component
        See Also:
        getBaseGameExpansion()