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, IConfigValueEditorMetadata). 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 Details

    • configValue

      static <T> IConfigScreenValue<T> configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue, IConfigValueEditorMetadata<T> metadata)
      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.
      Parameters:
      metadata - the editor selection, validation, choices, and localized value text
      Since:
      0.6.0

    • configValue

      static <T> IConfigScreenValue<T> configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue, IConfigValueEditorMetadata<T> metadata, ConfigValueApplyMode applyMode)
      Adapt a MezzConfig-managed config value for display on a config screen.
      Parameters:
      metadata - the editor selection, validation, choices, and localized value text
      Since:
      0.6.0

    • configValue

      static <T> IConfigScreenValue<T> configValue(net.mezzdev.config.api.value.IConfigValue<T> configValue, IConfigValueEditorMetadata<T> metadata, ConfigValueApplyMode applyMode, net.mezzdev.config.api.value.editor.ConfigValueRestartRequirement restartRequirement)
      Adapt a MezzConfig-managed config value for display on a config screen.
      Parameters:
      metadata - the editor selection, validation, choices, and localized value text
      Since:
      0.6.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

      default net.mezzdev.config.api.value.serializer.IConfigValueSerializer<T> getSerializer()
      Get the helper for converting values to and from text.
      Throws:
      UnsupportedOperationException - if this value has no text serializer
      Since:
      0.1.0

    • getEditorMetadata

      IConfigValueEditorMetadata<T> getEditorMetadata()
      Get editor selection, validation, and localized text independently of string serialization.
      Returns:
      the editor metadata for this value
      Since:
      0.6.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