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.
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!"
}
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%
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>()
A simple setting that stores a boolean with no additional properties.
var myBoolean by boolean(true) {
// ...
}
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
// ...
}
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
// ...
}
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
// ...
}
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
// ...
}
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) {
// ...
}
A simple setting that stores a string with no additional properties.
var myString by string("Hello, World!") {
// ...
}
A simple setting that stores a java.io.File
with no additional properties.
var myFile by file(File("C:/Users/Settxi")) {
// ...
}
A simple setting that stores a java.nio.file.Path
with no additional properties.
var myPath by path(Paths.get("C:/Users/Settxi")) {
// ...
}