org.crosswire.common.config

## Interface Choice

- All Known Subinterfaces:
    MappedChoice<K,V>, MultipleChoice
  All Known Implementing Classes:
    AbstractReflectedChoice, BooleanChoice, ClassChoice, DirectoryChoice, FileChoice, FontChoice, IntOptionsChoice, MappedOptionsChoice, NumberChoice, PathChoice, StringArrayChoice, StringChoice, StringOptionsChoice

      public interface Choice

  Choice is the fundamental building block of the config system. Every Choice must be able to:
  - get and set itself using a String
  - provide some simple help about itself
  - elect a user level for itself (Beginner, Intermediate, Advanced)
  - provide a GUI editor for itself
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Class<? extends Object>` | `getConversionClass()` The class that this Choice works on.
    `String` | `getFullPath()` The full path of the option.
    `String` | `getHelpText()` Gets a brief description of what is going on
    `String` | `getKey()` The key of the option.
    `String` | `getString()` String value to associate with the name (key)
    `String` | `getType()` The type by which UIs can pick an appropriate editor
    `void` | `init(org.jdom2.Element option, ResourceBundle configResources)` String value to associate with the name (key)
    `boolean` | `isHidden()` Whether this should be visible in a Config Editor.
    `boolean` | `isIgnored()` Whether this should be ignored altogether in a Config Editor.
    `boolean` | `isSaveable()` Is this Choice OK to write out to a file, or should we use settings in this run of the program, but forget them for next time.
    `boolean` | `requiresRestart()` Do we need to restart the program in order for this change to have effect?
    `void` | `setFullPath(String fullPath)` Sets the full path of the option.
    `void` | `setHelpText(String helptext)` Sets a brief description of what is going on
    `void` | `setString(String value)` String value to associate with this Field.

- - ### Method Detail

    - #### init

          void init(org.jdom2.Element option,
                  ResourceBundle configResources)
                    throws StartupException

      String value to associate with the name (key)
      Parameters:
        `option` - the option
        `configResources` - the resource bundle to load
      Throws:
        `StartupException` - if startup is not possible

    - #### getKey

          String getKey()

      The key of the option.
      Returns:
        String The key string as supplied in config.xml

    - #### getFullPath

          String getFullPath()

      The full path of the option.
      Returns:
        String The path string as supplied in config.properties

    - #### setFullPath

          void setFullPath(String fullPath)

      Sets the full path of the option.
      Parameters:
        `fullPath` - The path string as supplied in config.properties

    - #### getType

          String getType()

      The type by which UIs can pick an appropriate editor
      Returns:
        String The type string as supplied in config.xml

    - #### getConversionClass

          Class<? extends Object> getConversionClass()

      The class that this Choice works on. Used to decide how to display the choice to the user.
      Returns:
        The Class that this Choice works using.

    - #### getString

          String getString()

      String value to associate with the name (key)
      Returns:
        value of this Choice

    - #### setString

          void setString(String value)
                         throws ConfigException

      String value to associate with this Field. This method can throw any Exception since almost anything could go wrong at this point. The Config dialog ought to cope with any errors.
      Parameters:
        `value` - The new value for this Choice
      Throws:
        `ConfigException` - if there is a problem with the configuration

    - #### getHelpText

          String getHelpText()

      Gets a brief description of what is going on
      Returns:
        Some help text

    - #### setHelpText

          void setHelpText(String helptext)

      Sets a brief description of what is going on
      Parameters:
        `helptext` - Some help text

    - #### isSaveable

          boolean isSaveable()

      Is this Choice OK to write out to a file, or should we use settings in this run of the program, but forget them for next time. A typical use of this is for password configuration.
      Returns:
        True if it is safe to store the value in a config file.

    - #### isHidden

          boolean isHidden()

      Whether this should be visible in a Config Editor.
      Returns:
        hidden or visible

    - #### isIgnored

          boolean isIgnored()

      Whether this should be ignored altogether in a Config Editor.
      Returns:
        hidden or visible

    - #### requiresRestart

          boolean requiresRestart()

      Do we need to restart the program in order for this change to have effect?
      Returns:
        True if a restart is required