Package net.mezzdev.config.gui.api

Interface IConfigScreenValue<T>

Type Parameters:
T - the value type
public interface IConfigScreenValue<T>
Represents a value shown on a config screen.

MezzConfig-managed values can be adapted with configValue(IConfigValue). Screen-only values can implement this interface directly without implementing MezzConfig's non-extendable IConfigValue. Platform-native config adapters, such as the native NeoForge config adapter, should also implement this interface directly and use the ByName methods on IConfigScreenCategoryBuilder for GUI customization.

Values returned by this interface, passed to listeners, and accepted by set(Object) must be effectively immutable snapshots with stable equality. Mutable native config collections must never be exposed directly because the GUI keeps values while edits are staged and while applied changes remain undoable.

Since:
0.1.0

  • Method Summary

    Modifier and Type
    Method
    Description
    Runnable
    addListener(Consumer<T> listener)
    Add a listener that is called with the new value when this config screen value changes.
    static <T> IConfigScreenValue<T>
    configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue)
    Adapt a MezzConfig-managed config value for display on a config screen.
    static <T> IConfigScreenValue<T>
    configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue, ConfigValueApplyMode applyMode)
    Adapt a MezzConfig-managed config value for display on a config screen.
    static <T> IConfigScreenValue<T>
    configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue, ConfigValueApplyMode applyMode, net.mezzdev.config.api.value.editor.ConfigValueRestartRequirement restartRequirement)
    Adapt a MezzConfig-managed config value for display on a config screen.
    default ConfigValueApplyMode
    getApplyMode()
    Get when the config GUI should save edits for this value.
    default Optional<net.mezzdev.config.api.value.IConfigValue<T>>
    getConfigValue()
    Get the backing MezzConfig value, if this screen value adapts one.
    T
    getDefaultValue()
    Get the default value.
    default Object
    getIdentityKey()
    Get the reference-stable identity key used to match and deduplicate this value.
    String
    getLocalizationKey()
    Get the translation key used for this config screen value's name.
    String
    getName()
    Get the stable name of this config screen value.
    default net.mezzdev.config.api.value.editor.ConfigValueRestartRequirement
    getRestartRequirement()
    Get the restart or reload required after this value is saved.
    net.mezzdev.config.api.value.serializer.IConfigValueSerializer<T>
    getSerializer()
    Get the helper for serializing values to and from Strings, and validating values.
    T
    getValue()
    Get the current value.
    boolean
    set(T value)
    Set the value.
    static <T> IConfigScreenValue<T>
    withApplyMode(IConfigScreenValue<T> configValue, ConfigValueApplyMode applyMode)
    Override when the config GUI saves edits for one config screen value.
    static <T> IConfigScreenValue<T>
    withRestartRequirement(IConfigScreenValue<T> configValue, net.mezzdev.config.api.value.editor.ConfigValueRestartRequirement restartRequirement)
    Override the restart or reload required after this config screen value is saved.

  • Method Details

    • configValue

      static <T> IConfigScreenValue<T> configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue)
      Adapt a MezzConfig-managed config value for display on a config screen. Restart-required config values display their pending saved value while their effective value remains fixed until the applicable lifecycle boundary.
      Since:
      0.1.0

    • configValue

      static <T> IConfigScreenValue<T> configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue, ConfigValueApplyMode applyMode)
      Adapt a MezzConfig-managed config value for display on a config screen.
      Since:
      0.1.0

    • configValue

      static <T> IConfigScreenValue<T> configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue, ConfigValueApplyMode applyMode, net.mezzdev.config.api.value.editor.ConfigValueRestartRequirement restartRequirement)
      Adapt a MezzConfig-managed config value for display on a config screen.
      Since:
      0.1.0

    • withApplyMode

      static <T> IConfigScreenValue<T> withApplyMode(IConfigScreenValue<T> configValue, ConfigValueApplyMode applyMode)
      Override when the config GUI saves edits for one config screen value.
      Since:
      0.1.0

    • withRestartRequirement

      static <T> IConfigScreenValue<T> withRestartRequirement(IConfigScreenValue<T> configValue, net.mezzdev.config.api.value.editor.ConfigValueRestartRequirement restartRequirement)
      Override the restart or reload required after this config screen value is saved.
      Since:
      0.1.0

    • getName

      String getName()
      Get the stable name of this config screen value.
      Since:
      0.1.0

    • getLocalizationKey

      String getLocalizationKey()
      Get the translation key used for this config screen value's name.
      Since:
      0.1.0

    • getValue

      T getValue()
      Get the current value.

      Returned values must be effectively immutable. In particular, collection-backed implementations must return a snapshot instead of exposing mutable native config storage.

      Since:
      0.1.0

    • getDefaultValue

      T getDefaultValue()
      Get the default value.

      Returned values must be effectively immutable and have stable Object.equals(Object) behavior.

      Since:
      0.1.0

    • set

      boolean set(T value)
      Set the value.
      Parameters:
      value - the new value
      Returns:
      true when the stored value changed, or false when the value was valid but unchanged
      Throws:
      IllegalArgumentException - when the value is invalid
      RuntimeException - when the value cannot be stored or saved
      Since:
      0.1.0

    • addListener

      Runnable addListener(Consumer<T> listener)
      Add a listener that is called with the new value when this config screen value changes.

      Callbacks run synchronously on the thread applying or loading the change; implementations must not dispatch them to another thread. Implementations must notify listeners for successful changes made through set(Object) and for external reload or change events exposed by their backing storage. The GUI subscribes while its screen is active and dispatches callbacks to the Minecraft client thread before updating widgets.

      Returns:
      a callback that removes this listener
      Since:
      0.1.0

    • getApplyMode

      default ConfigValueApplyMode getApplyMode()
      Get when the config GUI should save edits for this value.
      Since:
      0.1.0

    • getRestartRequirement

      default net.mezzdev.config.api.value.editor.ConfigValueRestartRequirement getRestartRequirement()
      Get the restart or reload required after this value is saved.
      Since:
      0.1.0

    • getIdentityKey

      default Object getIdentityKey()
      Get the reference-stable identity key used to match and deduplicate this value.

      Keys are compared by reference, not with Object.equals(Object). Decorators must return the wrapped value's key. Values that share a key must represent the same logical value and type. The default gives direct implementations identity for the lifetime of the object.

      Since:
      0.1.0

    • getSerializer

      net.mezzdev.config.api.value.serializer.IConfigValueSerializer<T> getSerializer()
      Get the helper for serializing values to and from Strings, and validating values.
      Since:
      0.1.0

    • getConfigValue

      default Optional<net.mezzdev.config.api.value.IConfigValue<T>> getConfigValue()
      Get the backing MezzConfig value, if this screen value adapts one. Platform-native and screen-only values should leave this empty. Value matching uses getIdentityKey().
      Since:
      0.1.0