Settings - isXander/Settxi GitHub Wiki

The settings syntax is designed with simplicity in mind. You don't need to worry about any additional features/properties, they are purely optional.

Base Setting<T> class

Basic properties

These properties are available for every implementation of settings

  • name - required
  • category - required
  • description - optional but highly recommended for UX
  • shouldSave - optional (default: true). Only used in serialization modules to not export the value
val mySetting by setting(default) {
    name = "name goes here!"
    category = "category goes here!"
    description = "description goes here!"
}

Advanced features

Getter/setter

You can optionally provide a custom getter and setter to wrap around the stored value, for example, to convert in and out of a percentage decimal.

var mySetting by double(1.0) {
    get { value ->
        // would usually just return value
        value * 100.0
    }
    set { value ->
        // would usually just set to value
        value / 100.0
    }
}

This example would store the value as 1.0 but return as 100%

Migrator

When importing from for e.x. a file, the user may have updated to a newer version that changed a setting type (float -> double or option -> enum) which would break serialization as the type would be different. You can rectify this with a custom migrator.

var mySetting by enum(Alphabet.A) {
    migrator { type -> // Settxi's abstracted PrimitiveType contains either a string, number or boolean
        if (it.isString) {
            PrimitiveType.of(Alphabet.valueOf(it.string).ordinal)
        } else {
            it
        }
    }
}

In this example, the deprecated option setting is converted to an enum setting. NOTE: The above example is part of a utility function Migrators.optionToEnum<Alphabet>()

Default Settings

Boolean Setting

A simple setting that stores a boolean with no additional properties.

var myBoolean by boolean(true) {
    // ...
}

Double Setting

A simple setting that stores a double. This setting has a range property which coerces all set values into.

var myDouble by double(1.0) {
    range = 0.0..1.0
    // ...
}

Float Setting

A simple setting that stores a float. This setting has a range property which coerces all set values into.

var myFloat by float(1f) {
    range = 0f..1f
    // ...
}

Int Setting

A simple setting that stores an integer. This setting has a range property which coerces all set values into.

var myInt by int(1) {
    range = 0..100
    // ...
}

Long Setting

A simple setting that stores a long. This setting has a range property which coerces all set values into.

var myLong by long(1L) {
    range = 0L..100L
    // ...
}

Enum Setting

A simple setting that stores an enum.

There is a nameProvider property that maps the enum type to a string. This is only used in GUI implementations to display a friendly name for an enum. By default, Settxi relies on your enum implementing dev.isxander.settxi.impl.SettingDisplayName which has a string property called displayName

Note that this function is inline to get the reified type of the Enum

var myEnum by enum(Alphabet.A) {
    // ...
}

String Setting

A simple setting that stores a string with no additional properties.

var myString by string("Hello, World!") {
    // ...
}

File Setting

A simple setting that stores a java.io.File with no additional properties.

var myFile by file(File("C:/Users/Settxi")) {
    // ...
}

Path Setting

A simple setting that stores a java.nio.file.Path with no additional properties.

var myPath by path(Paths.get("C:/Users/Settxi")) {
    // ...
}
⚠️ **GitHub.com Fallback** ⚠️