Package ca.cgjennings.apps.arkham.component

Interface GameComponent

  • All Superinterfaces:
    java.lang.Cloneable, java.io.Serializable
    All Known Subinterfaces:
    LegacyDesignSupport.Provider
    All Known Implementing Classes:
    AbstractGameComponent, Deck, DIY, Marker
    public interface GameComponent
extends java.io.Serializable, java.lang.Cloneable
    This interface defines common methods for all supported types of "components": paper gaming elements that may consist of one or more faces (sides). Concrete custom component implementations will typically be subclasses of AbstractGameComponent.
    Author:
    Chris Jennings

    • Method Detail

      • getClassName

        default java.lang.String getClassName()
        Returns the standard class map name that describes this component. For a compiled component this is the fully qualified name of the class. For a standard DIY component, it is diy: followed by the resource path of the script file. If the component was created from a script: class map entry, that will not be returned. The name of the true underlying type that was ultimately created by the script is returned instead.
        Returns:
        the class map type of this instance

      • getName

        java.lang.String getName()
        Returns the name of this component. This is not the name of the component type, but the name of the specific component. For example, a component that represents a game item would return the name of the item.
        Returns:
        the component's name; possibly a shortened version of the full name
        See Also:
        getFullName()

      • getFullName

        java.lang.String getFullName()
        Returns the "full name" of this component. Typically this is the same as getName(), but getName() may optionally return a shorter name. For example, a component that represents a human character might return the character's first name from getName() and their full name from this method.
        Returns:
        the full name of the component
        See Also:
        getName()

      • getComment

        java.lang.String getComment()
        Returns the design rationale comments associated with this component. If there are no comments, it should return an empty string.
        Returns:
        design comments supplied by the user of the component

      • getSettings

        Settings getSettings()
        Returns a Settings instance that will return this component's private settings. A component's private settings are saved along with the component when it is written to a file. This can be used to override the default settings for component (which are determined by the the shared game settings for the game associated with the component) as a way to "hack" existing component designs. It can also be used by the component itself to store arbitrary information. DIY components generally use the component's private settings to store the current user-configurable state of the component.

        Note that setting the key with the name Game.GAME_SETTING_KEY ("game") will change the parent scope of the private settings to the relevant game's settings for that game whose code matches the new value. (The initial value of this key is normally set on the component's half using the game code specified in the component's class map entry.)

        Returns:
        the private settings that can be used to override settings for this component

      • clearAll

        void clearAll()
        Sets this component's content to an empty state. Typically, this is called from an editor when the user wishes to erase their work and start over.

      • getSheets

        Sheet[] getSheets()
        Returns the sheets attached to this component to draw its faces, or null if no sheets are attached. The returned array is owned by the game component and must not be modified.
        Returns:
        the sheets that will be updated by calls to markChanged(int).
        See Also:
        getSheets()

      • setSheets

        void setSheets​(Sheet[] sheets)
        Sets the sheets that are attached to this component to draw its faces. Once set, the array is owned by the component and must not be modified.
        Parameters:
        sheets - the sheets to associate with the component, or null to clear the associated sheets
        See Also:
        getSheets(), createDefaultSheets()

      • createDefaultSheets

        Sheet[] createDefaultSheets()
        Creates a set of default sheets that are compatible with this component and associates them with the component as if by calling setSheets(ca.cgjennings.apps.arkham.sheet.Sheet[]). As with getSheets(), the returned sheets are owned by the component and must not be modified.
        Returns:
        the newly created sheets

      • getSheetTitles

        java.lang.String[] getSheetTitles()
        Returns human-readable names for the sheets used by this component. A typical result would be something like ["Front Face", "Back Face"], localized for the user interface language.

        Implementations should assume that the titles are for the same kinds and number of sheets that are returned by createDefaultSheets(). (In other words, if a user of this class decides to use their own sheet implementations, you are not responsible for ensuring the sheet titles are accurate.)

        Note: The returned sheet name may be shared with any number of callers. The values must be considered read-only unless otherwise stated by the subclass documentation.

        Returns:
        an array of sheet titles matching the assigned sheets, or null if there are no sheets attached
        See Also:
        createDefaultSheets()

      • markChanged

        void markChanged​(int sheetIndex)
        Called to signal that changes have been made that require the ithe sheet to be redrawn. This is typically not called directly. Instead, calling a method like "setName" should check if the name being set is actually different, and if so then call this method for each sheet that may have changed as a result. Plug-ins that customize an existing component may also call this method as needed to reflect new features that they have added.

        Implementations of this method will typically call the Sheet.markChanged() method of the relevant sheet (unless the sheet set is null), set a flag for use by hasChanged(), and then call markUnsavedChanges().

        Parameters:
        sheetIndex - the index of the sheet that needs to be redrawn

      • hasChanged

        boolean hasChanged()
        Returns true if this component has been modified since the last call to hasChanged().
        Returns:
        true if the component has changed since this was last called

      • hasUnsavedChanges

        boolean hasUnsavedChanges()
        Returns the value of this component's unsaved changes flag.
        Returns:
        true if this component has unsaved changes

      • markUnsavedChanges

        void markUnsavedChanges()
        This method sets the component's unsaved changes flag. It is typically called from markChanged(int).

      • markSaved

        void markSaved()
        This method is called by the component's editor when the the component is saved to clear the component's unsaved changes flag.

      • isDeckLayoutSupported

        boolean isDeckLayoutSupported()
        Returns true if components of this type can be placed in a deck. Typically, only components that don't have faces return false. (Decks themselves, for example, cannot be placed inside other decks.)
        Returns:
        true if and only if this component can be added to a deck
        See Also:
        createDefaultSheets(), Deck.isDeckLayoutSupported(java.io.File)

      • clone

        GameComponent clone()
        Returns a deep copy of this game component. The default clone implementation provided by super.clone() will return a shallow copy of the object. This will correctly clone all of this instance's fields that have primitive types. It is then up to you to clone any object fields where the field is not of an immutable type. Images used to store portraits, although not technically immutable, are treated as immutable by Strange Eons. So long as you also follow this convention, you can save memory by sharing the shallow copy of the image.

        Debugging tip: One operation that makes use of the clone() method is the Spin Off command. If you apply this command, make changes to the copied component, redraw the original component, and notice that changes in the copy have carried over to the original, then you are using a shallow copy rather than a deep copy. (That is, you are sharing a reference to the same mutable object rather than making a copy of the mutable object during the cloning.)

        Returns:
        a deep copy of this component

      • coreCheck

        void coreCheck()
        Checks if all required libraries and extensions are installed. If a required library is not install This method is called when the component is read from a file, and possibly at other times

        This can safely be implemented as an empty method. However, implementing it correctly improves the user experience since they can be notified of which plug-ins they need to install to correctly use the component. In the case of a required but not installed library, the library can actually be downloaded and installed on demand and the component can then be successfully opened.

        Throws:
        CoreComponents.MissingCoreComponentException - if a required plug-in is missing or out of date and the user cannot or will not install it on demand
        See Also:
        CoreComponents

      • createUpgradeConversionTrigger

        default UpgradeConversionTrigger createUpgradeConversionTrigger()
        Returns the ConversionSession created when the component type no longer handles the component. This method is called after a component is read from file. Should return null when no conversion is needed.
        Returns:
        a conversion context if the upgrade requires a conversion
        See Also:
        ConversionSession

      • convertFrom

        default void convertFrom​(ConversionSession session)
        Called on a component that is being converted into another component type. Based on the conversion strategy, the old component may modify the new component directly, or modify the conversion context, or do nothing. This method is called before calling #convertTo(GameComponent, ConversionContext) on the target, and before any automatic conversion steps.
        Parameters:
        target - the new component that will replace this one
        context - the conversion context

      • convertTo

        default void convertTo​(ConversionSession session)
        Called on the replacement component when converting a component to another component type. Based on the conversion strategy, the new component may modify itself directly, or modify the conversion context, or do nothing. This method is called after calling #convertFrom(GameComponent, ConversionContext) on the source, but before any automatic conversion steps.
        Parameters:
        source - the old component that will be replaced
        context - the conversion context