# Class ChoiceConfigKey<T>

java.lang.Object
uk.ac.starlink.ttools.plot2.config.ConfigKey<T>
uk.ac.starlink.ttools.plot2.config.ChoiceConfigKey<T>

Direct Known Subclasses:
  `ColorConfigKey, DashConfigKey, ShaderConfigKey`

public abstract class ChoiceConfigKey<T> extends ConfigKey<T>
ConfigKey that allows named choices from a given list, and optionally provides other ways of specifying values from string descriptions.

Since:
  10 Sep 2014
Author:
  Mark Taylor

## Constructor Summary

Constructors
Constructor
Description
`ChoiceConfigKey(ConfigMeta meta, Class<T> clazz, T dflt, boolean nullPermitted)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`void`
`addOption(T option)`
Adds an option to the permitted list.
`abstract T`
`decodeString(String sval)`
Takes a string, and attempts to turn it into an object which may be a value for this key.
`Map<String,T>`
`getOptionMap()`
Returns a mutable map giving the currently available known options and their string values.
`abstract String`
`stringifyValue(T value)`
Takes an object which may be a value of this key, and attempts to turn it into a string for reporting purposes.
`T`
`stringToValue(String sval)`
Decodes a string value to the value type of this key.
`String`
`valueToString(T value)`
Reports a value as a string.

### Methods inherited from class ConfigKey

`cast, createSpecifier, getDefaultValue, getMeta, getValueClass, toString`

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### ChoiceConfigKey

public ChoiceConfigKey(ConfigMeta meta, Class<T> clazz, T dflt, boolean nullPermitted)
Constructor.

Parameters:
  `meta` - metadata
  `clazz` - value class
  `dflt` - default value
  `nullPermitted` - true iff null is a permitted value

## Method Details

### addOption

public void addOption(T option)
Adds an option to the permitted list. Its name is obtained using the `stringifyValue(T)` method, which must return a non-null value.

For more flexibility, you can manipulate the return value of `getOptionMap()` directly.

Parameters:
  `option` - option to add

### getOptionMap

public Map<String,T> getOptionMap()
Returns a mutable map giving the currently available known options and their string values.

Returns:
  current name->value map of known options

### decodeString

public abstract T decodeString(String sval)
Takes a string, and attempts to turn it into an object which may be a value for this key. If the string is not of a recognised form, null is returned.

This method should be the opposite of `stringifyValue(T)`, but does not need to be consistent with `stringToValue` or `valueToString`.

Parameters:
  `sval` - string representation
Returns:
  typed object represented by sval, or null

### stringifyValue

public abstract String stringifyValue(T value)
Takes an object which may be a value of this key, and attempts to turn it into a string for reporting purposes.

This method should if possible be the opposite of `decodeString(String)`, but does not need to be consistent with `stringToValue` or `valueToString`. If no round-trippable value is available, null should be returned.

Parameters:
  `value` - typed object
Returns:
  string representing object, or null

### stringToValue

public T stringToValue(String sval) throws ConfigException
Description copied from class: `ConfigKey`
Decodes a string value to the value type of this key. An empty string should be interpreted as a null value, but this may cause an exception if null is not a permissible value for this key.

Specified by:
  `stringToValue` in class `ConfigKey<T>`
Parameters:
  `sval` - string representation of value
Returns:
  value
Throws:
  `ConfigException`

### valueToString

public String valueToString(T value)
Description copied from class: `ConfigKey`
Reports a value as a string. If at all possible the roundtripping should be possible, so `stringToValue(valueToString(v)).equals(v)`. A null value, if permitted, should be represented as an empty string.

Specified by:
  `valueToString` in class `ConfigKey<T>`
Parameters:
  `value` - possible value associated with this key
Returns:
  string representation