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 ofAbstractGameComponent
.- Author:
- Chris Jennings
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
clearAll()
Sets this component's content to an empty state.GameComponent
clone()
Returns a deep copy of this game component.default void
convertFrom(ConversionSession session)
Called on a component that is being converted into another component type.default void
convertTo(ConversionSession session)
Called on the replacement component when converting a component to another component type.void
coreCheck()
Checks if all required libraries and extensions are installed.AbstractGameComponentEditor<? extends GameComponent>
createDefaultEditor()
Creates an editor capable of modifying this component.Sheet[]
createDefaultSheets()
Creates a set of default sheets that are compatible with this component and associates them with the component as if by callingsetSheets(ca.cgjennings.apps.arkham.sheet.Sheet[])
.default UpgradeConversionTrigger
createUpgradeConversionTrigger()
Returns theConversionSession
created when the component type no longer handles the component.default java.lang.String
getClassName()
Returns the standard class map name that describes this component.java.lang.String
getComment()
Returns the design rationale comments associated with this component.java.lang.String
getFullName()
Returns the "full name" of this component.java.lang.String
getName()
Returns the name of this component.Settings
getSettings()
Returns aSettings
instance that will return this component's private settings.Sheet[]
getSheets()
Returns the sheets attached to this component to draw its faces, ornull
if no sheets are attached.java.lang.String[]
getSheetTitles()
Returns human-readable names for the sheets used by this component.boolean
hasChanged()
Returnstrue
if this component has been modified since the last call tohasChanged()
.boolean
hasUnsavedChanges()
Returns the value of this component's unsaved changes flag.boolean
isDeckLayoutSupported()
Returnstrue
if components of this type can be placed in a deck.void
markChanged(int sheetIndex)
Called to signal that changes have been made that require thei
the sheet to be redrawn.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.void
markUnsavedChanges()
This method sets the component's unsaved changes flag.void
setSheets(Sheet[] sheets)
Sets the sheets that are attached to this component to draw its faces.
-
-
-
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 isdiy:
followed by the resource path of the script file. If the component was created from ascript:
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 asgetName()
, butgetName()
may optionally return a shorter name. For example, a component that represents a human character might return the character's first name fromgetName()
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 aSettings
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 therelevant 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, ornull
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, ornull
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 callingsetSheets(ca.cgjennings.apps.arkham.sheet.Sheet[])
. As withgetSheets()
, 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()
-
createDefaultEditor
AbstractGameComponentEditor<? extends GameComponent> createDefaultEditor()
Creates an editor capable of modifying this component.- Returns:
- a new editor that can be added to the application window to edit this component
- See Also:
StrangeEonsAppWindow.addEditor(ca.cgjennings.apps.arkham.StrangeEonsEditor)
-
markChanged
void markChanged(int sheetIndex)
Called to signal that changes have been made that require thei
the 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 isnull
), set a flag for use byhasChanged()
, and then callmarkUnsavedChanges()
.- Parameters:
sheetIndex
- the index of the sheet that needs to be redrawn
-
hasChanged
boolean hasChanged()
Returnstrue
if this component has been modified since the last call tohasChanged()
.- 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 frommarkChanged(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()
Returnstrue
if components of this type can be placed in a deck. Typically, only components that don't have faces returnfalse
. (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 bysuper.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 timesThis 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 theConversionSession
created when the component type no longer handles the component. This method is called after a component is read from file. Should returnnull
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 onecontext
- 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 replacedcontext
- the conversion context
-
-