Class ConversionSession


  • public class ConversionSession
    extends java.lang.Object
    A ConversionSession instance is created by #convertGameComponent(ConversionTrigger, GameComponent) in order to perform the conversion of a GameComponent into another component type. The class has several methods to help with the conversion process. Most return the instance itself, so that they can be chained easily.
    Since:
    3.3
    Author:
    Henrik Rostedt
    • Method Detail

      • getSource

        public GameComponent getSource()
        Returns the original component that is being converted. This component should not be modified during the conversion process.
        Returns:
        the source component
      • getTarget

        public GameComponent getTarget()
        Returns the new component that will become the converted component. In most cases it will be easier to use the session methods to copy data, rather than modifying the target directly.
        Returns:
        the target component
      • cancel

        public void cancel​(java.lang.String reason)
        Can be called to cancel the conversion process. This will prevent a converted component from being created.
        Parameters:
        reason - a description of why the conversion was cancelled
      • copyName

        public ConversionSession copyName()
        Copies the name of the old component to the new. The new component type must extend AbstractGameComponent. This action is automatically performed by default.
        Returns:
        this conversion session
      • copyComment

        public ConversionSession copyComment()
        Copies the comments of the old component to the new. The new component type must extend AbstractGameComponent. This action is automatically performed by default.
        Returns:
        this conversion session
      • copySettings

        public ConversionSession copySettings​(java.lang.String... keys)
        Copies the settings for the given keys from the old component to the new.
        Parameters:
        keys - the settings keys to copy
        Returns:
        this conversion session
      • copyAllSettings

        public ConversionSession copyAllSettings()
        Copies all settings from the old component to the new. Keys inherited from parent settings are not copied.
        Returns:
        this conversion session
      • copyAllSettingsExcept

        public ConversionSession copyAllSettingsExcept​(java.lang.String... excludedKeys)
        Copies all settings from the old component to the new, except for the given keys. Keys inherited from parent settings are not copied.
        Parameters:
        excludedKeys - the settings keys to exclude
        Returns:
        this conversion session
      • moveSettings

        public ConversionSession moveSettings​(java.lang.String... pairs)
        Copies settings from the old component to the new, based on the given key pairs. The setting for the first key in the pair is fetched from the old component and stored using the second key in the new component.
        Parameters:
        pairs - the pairs of keys to copy
        Returns:
        this conversion session
        Throws:
        java.lang.IllegalArgumentException - if the array of key name pairs has an odd length
      • setSettings

        public ConversionSession setSettings​(java.lang.String... keyValuePairs)
        Sets one or more settings on the new component, based on the given (key, value) pairs.
        Parameters:
        keyValuePairs -
        Returns:
        this conversion session
        Throws:
        java.lang.IllegalArgumentException - if the array of setting pairs has an odd length
      • copyExpansions

        public ConversionSession copyExpansions()
        Copies the expansions from the old component to the new. This action is automatically performed by default.
        Returns:
        this conversion session
      • copyPortrait

        public ConversionSession copyPortrait​(int sourceIndex,
                                              int targetIndex,
                                              boolean copyLayout)
        Copies a portrait from the old component to the new. Both component types must extend PortraitProvider. If the source image file can not be found, a temporary file is used for the conversion. Calling this method will disable automatic portrait copying.
        Parameters:
        sourceIndex - the index of the portrait in the source component
        targetIndex - the index of the portrait in the target component
        copyLayout - whether to copy the adjustments of the portrait or not
        Returns:
        this conversion session
      • copyPortrait

        public ConversionSession copyPortrait​(int index,
                                              boolean copyLayout)
        Copies a portrait from the old component to the new. Both component types must extend PortraitProvider. If the source image file can not be found, a temporary file is used for the conversion. Calling this method will disable automatic portrait copying.
        Parameters:
        index - the index of the portrait
        copyLayout - whether to copy the adjustments of the portrait or not
        Returns:
        this conversion session
      • copyAllPortraits

        public ConversionSession copyAllPortraits​(boolean copyLayouts)
        Copies the portraits from the old component to the new. Both component types must extend PortraitProvider. If the source image file for a portrait can not be found, a temporary file is used for the conversion. This action is automatically performed by default.
        Parameters:
        copyLayouts - whether to copy the individual adjustments of the portraits or not
        Returns:
        this conversion session
      • disableAutomaticCopyBasics

        public ConversionSession disableAutomaticCopyBasics()
        Disables the automatic conversion for component name, comments and expansions. Needs to be called if changing any of these on the target component manually.
        Returns:
        this conversion session
      • disableAutomaticCopyPortraits

        public ConversionSession disableAutomaticCopyPortraits()
        Disables the automatic conversion for component portraits. Needs to be called if modifying portraits on the target component manually.
        Returns:
        this conversion session
      • disableAutomaticConversion

        public ConversionSession disableAutomaticConversion()
        Disables all automatic conversion steps.
        Returns:
        this conversion session
      • performAutomaticConversion

        public ConversionSession performAutomaticConversion()
        Performs the enabled automatic conversion steps, then disables all conversion steps. This method is automatically called before the conversion is completed. It can be called before manually modifying the target component, so the changes are not overwritten.
        Returns:
        this conversion session
      • convertGameComponent

        public static GameComponent convertGameComponent​(ConversionTrigger trigger,
                                                         GameComponent source,
                                                         boolean interactive)
                                                  throws ConversionException
        Creates a new GameComponent which represents the given component converted to another component type. The old component should remain unchanged after the conversion is performed. First a new game component is created based on the provided ConversionTrigger and a ConversionSession is created. Then the old and new components each get the opportunity to modify the new component. Lastly, some automatic conversion steps may be performed.
        Parameters:
        trigger - the trigger for the conversion
        source - the component to be converted
        interactive - whether user interaction is allowed or not
        Returns:
        the new converted component
        Throws:
        ConversionException - if the conversion was unsuccessful