ModOptionsAPI

Author: Jonathan Brazell (WyrdOne)
Version: 1.6.2
Compatible: Minecraft 1.6.2
Description: An API for allowing simple mod options menus in Minecraft Options menu.

For non-developers, please go to "Installation"
For developers, please go to Developers

-----------------
Installation
-----------------

1) Install ModLoader
   FML/Forge will also work.
2) Copy moapi zip file to your mods folder
3) Start up minecraft and play.

-------------------
Server Installation
-------------------

1) Copy contents of moapi zip file to your minecraft_server.jar
2) Start up minecraft and play.

------------------
Compatibility
------------------

MOAPI should be compatible with pretty much any mod.

------------------
Developers
------------------

The sourcecode for mcp is located on GitHub at https://github.com/WyrdOne/ModOptionsAPI

Make sure to initialize your options before the user accesses them.  The load method of your mod is a good place for this.

(MOAPI uses ModLoader to create the option button on the options screen, but it could technically run without it)

Example mods are provided in /examples/.

API Features:
- Boolean/ Toggle Options
- List/ Multi-value options
- Text input options
- Key binding options
- Slider options
- Saves conveniently to disk in consistent save file
- Well designed and consistent API with both a simple and more advanced interface available.
- Includes all source and no files are obfuscated. 
- Fully JavaDoc commented where appropriate.
- Simple GUI API interface; no complex widgets or unexpected behaviour.
- Individual Server and World values
- Scrolling menus are always available
- Callbacks so you have more control over value changes

------------------
Version History
------------------

1.6.2 - Updated to Minecraft 1.6.2 compatibility.

1.5.1 - Updated to Minecraft 1.5.1 compatibility.

1.5 - Updated to Minecraft 1.5 compatibility, added server support as well.

1.0.2 - Madified MOAPI to no longer edit base classes, does require a mod loader of some sort.

1.0.1 - Minecraft 1.4.6 Compatible
- Made compatible with Minecraft 1.4.6
- Made options wider on screen
- Fixed issue with done button overlapping option buttons

1.0.0 - Minecraft 1.4.4 Compatible
- Made compatible with Minecraft 1.4.4
- Moved api from package moapi to moapi.api
- Moved moapi.gui to moapi.clientgui
- Moved formatting options and narrow/wide options internal to ModOption class
- Made class to handle modifying Minecraft menus to allow minimal intrusion into base classes
- Made GuiAPI inteface code 100% reflection to allow it to compile without GuiAPI
- Eliminated "super simple" method that was not really so simple

9.3 - Minecraft 1.4.2 Compatible
- Made compatible with Minecraft 1.4.2
- Changed IntegerSliderFormat to include the option name as well as the integer value.

9.2 - Minecraft 1.3.2 Compatible
- Made compatible with Minecraft 1.3.2

9.1 - Minecraft 1.3.1 Compatible
- Made compatible with Minecraft 1.3.1
- Forked from original version since original author no longer maintains the code.

9 - Minecraft 1.2.5 Compatible
(Overview)
- WyrdOne made MOAPI compatible with 1.2.5
- Removed ModMappedMultiOption
(API changes)
- ModMappedMultiOption has been removed
-- Was a deprecated feature

8 - Minecraft 1.1 Compatible
- Made compatible with Minecraft 1.1

7 - Minecraft 1.0 Compatible
- Made compatible with Minecraft 1.0 and version number bumped to 7 to prevent the mod being removed from the MC forums (rounded down to 7)
- New folder format which is automatically generated from a custom packing script

0.7.1 - Minecraft Beta 1.8 compatible version
Sorry if this changelog isn't descriptive, due to the long time of not working, I have lost the majority of the changelog
(Overview)
- Removed all deprecated elements in ModSliderOption
- Added ModMappedOption
- Set ModMappedMultiOption to deprecated
- Internal ID concept added such that all options can have a separate internal storage ID to their display ID
- Added new constructors to all options and sub-menus/options to allow a custom internal ID
- Added return values in ModOptions to many more methods in order to make it a builder class
- Added new ModOptions.setOptionStringFormat(ModOption, DisplayStringFormatter)
- Added new ModOptions.addOptionFormatter(ModOption, DisplayStringFormatter)

0.7 - Additions. Threatening changes with conflicts.
(Overview)
- Threatening changes: Restructuring of GUI classes, unlikely to break anything, but some methods throw different *runtime* exceptions now, so please check the "Potentially Threatening Method Signature Changes for API" section
- Restructured some of the gui classes, more to come in 0.8 which WILL be breaking changes.
- Added key binding options
- Added text input fields
- Added more API points for simplicity (primarily overloading int with Integer methods to allow more flexibility)
- Added getValue(global) and setValue(value, global) to remove need for xGlobalValue() methods and reduce unecessary code branching
(Class Additions to API)
- Added modoptionsapi.ModKeyOption for adding key bindings
- Added modoptionsapi.ModTextOption for adding pure text fields
- Added modoptionsapi.MOFormatters.NoFormat to allow just the value in a button
(Exception Additions)
- Added modoptionsapi.KeyAlreadyBoundException for when a keybinding already exists and something is attempting to re-use that binding
(Class Changes and Additions to GUI)
- Added package modoptionsapi.gui
- Moved modoptionsapi.MOGuiSider to modoptionsapi.gui.Slider
- Moved modoptionsapi.MOGuiScrollOptions to modoptionsapi.gui.ModMenu
- Added modoptionsapi.gui.TextInputField
- Added modoptionsapi.gui.TextField
- Added modoptionsapi.gui.KeyBindingField
(Method Additions for API (GUI specific ignored))
- Added ModOption.setValue(value, global) to allow setting value in scope without setGlobalValue/setLocalVValue
- Added ModOption.getValue(global) to allow getting from a scope without calling getGlobalValue and getLocalValue
- Added ModOptions.addKeyOption for adding new key binding
- Added ModOptions.addKeyBinding for adding new key binding
- Added ModOptions.addTextOption for adding a text option
- Many other Binding/ Text option methods added to ModOptions, check Javadoc or diff records on github
- Many other convenience methods added, check Javadoc or diff records on GitHub
(Non-breaking Method Signature Changes for API (Gui specific ignored))
- Changed all ModOptions.addXOption to return the option created
(Potentially Breaking Method Signature Changes for API)
- Changed all ModOptions.setOptionValue methods to throw NoSuchOptionException instead of IncompatibleOptionTypeException when the case applies
- Changed all ModOptions.get<X>Value methods to throw IncompatibleOptionTypeException where the case applies
(Bug Fixes)
- Fixed obscure unreported bug in ModOption.setValue(value) where local/ global value were set backwards. 

0.6.5 - Additions. No breaking changes
- Added new constructors for ModMappedMultiOption
- Added new methods to ModMappedMultiOption to allow for "int" calls.
- Added ModOptions.addMappedMultiOption(String, int[], String[]) for simplicity
- Added ModOptions.setWideOption(ModOption) for simplicity
- Added ModOptionGuiController.setWide(ModOption) for simplicity

0.6.4 - Updated for Minecraft Beta 1.7.2

0.6.2 - Compatibility Update
- Compatible with Minecraft 1.6.5

0.6.1 - No breaking changes
(Overview)
- Overhauled the MOGuiSlider class
- Depreciated plenty of MOGuiSlider functionality
- Depreciated many ModOptions methods
- Improved formatters to be able to be chained
- Changed file format for slider values to a float
- Fixed several slider bugs, including right click not setting global mode
(API Additions)
- Added ModOptions.getToggleValue for getting a toggle value
- Added ModOptions.getSliderValue for getting a slider's float value
- Added ModOptions.getMappedValue for getting a mapped multi's value
- Added ModOptions.addOptionFormatter for adding an extra formatter to an option
- Added NOSuchOptionException for when a option is missing upon a call (only applied to new methods so far)
- Added ModOptionsGuiController.addFormatter to add a new formatter to a specific option's output formatting
- Added ModSliderOption.setLocalValue(int) to allow for easy setting of integer values
- Added ModSliderOption.setGlobalValue(int) to allow for easy setting of integer values
- Added ModSliderOption.transformValue for transforming a value from the current bounds to a new set of bounds
- Added ModSliderOption.untransformValue as the inverse of transformValue
- Added MOFormatters.integerSlider field for polling the new formatter type
- Added MOFormatters.IntegerSliderFormat for easy setting of an integer slider
(Depreciations) - To be removed in 1.0
- ModSliderOption.getIntValue(float). Use getValue/getLocalValue/getGlobalValue
- ModSliderOption.getIntValue(). Use getValue/getLocalValue/getGlobalValue
- ModSliderOption.setIntValue(). Use setValue/setLocalValue/setGlobalValue and Integer.floatValue/ (float)
- ModSliderOption.getFloatValue(int). Use getValue/getLocalValue/getGlobalValue
- ModsliderOption.getFloatValue(). Use getValue/getLocalValue/getGlobalValue
(Improvements/ Bug Fixes)
- Fixed slider bug preventing setting value to GLOBAL
(API Changes)
- Changed ModOptions.setOptionStringFormat to remove all other formatters added to preserve expected behaviour, use addOptionFormatter for new behaviour
- Changed ModOptionsGuiController.setFormatter to remove all other formatters to preserve expected behaviour, use addFormatter for new behaviour
- Changed ModOptions.getDisplayString to now chain all added formatters for multiple formatted output
- Changed SuffixFormat.manipulate to not add the name label automatically in line with multiple formatters
(File Format)
- The slider option is now stored as a float value

0.6
(Overview)
- Added callbacks
- Updated for MCP212/Minecraft Beta 1.5_01
- Added scrolling in menus
(API Additions)
- MOCallback abstract class
(Improvements)
- Some bug fixes, details forgotten due to 1.5 release (>.>)
(File Changes)
- GuiModOptions.java -> GuiModScrollOptions.java (not a part of the public API, part of implementation)

0.5.0.2
- Fixed bug in sliders preventing local mode from activating 

0.5.0.1
- Fixed a bug in sliders preventing them from working and saving values

0.5
(Overview)
- Added a new file format called a .modoptions to easily write your own options for this API with only 5 lines of actual Java, which before would have used 50+
- Made 1.4_01 compatible 
(Files)
- Added new example file called Test.modoptions
- Added new exception type
(Additions)
- New exception type: MOMissingModException
- Added ModOptionsAPI.addMod(String) to load your mod options from a new .modoptions file format
(Improvements)
- Improved IncompatibleOptionTypeException

0.4
(Overview)
- Added world specific and server specific values
- Moved user files to a separate ZIP file
- Moved dev files to a separate ZIP file
(Files)
- Added 3 new files to files and compatiblity patch for world/server options
(Additions)
- Added ModOptions.getMultiplayerSubOptions() for getting submenus that can use server specific options
- Added ModOptions.getSingleplayerSubOptions() for getting submenus that can use world specific options
- Added ModOptions.setMultiplayerMode(boolean) for setting if the menu can use server specific options
- Added ModOptions.setSingleplayerMode(boolean) for setting if the menu can use world specific options
- Added ModOptions.isMultiplayerMod() for checking if the menu can use server specific options
- Added ModOptions.isSingleplayerMod() for checking if the menu can use world specific options
- Added ModOptions.loadValues(String, boolean) for compatibility with new save options
- Added ModOptions.save(String, boolean) for compatibility with new save options
- Added ModOption.localValue for representing the current local value
- Added ModOption.global to flag whether to use global value or not
- Added ModOption.setLocalValue(E)
- Added ModOption.getLocalValue()
- Added ModOption.getGlobalValue()
- Added ModOption.setLocalValue(E)
- Added ModOption.useGlobalValue() for checking if getValue() is to use the global value or not
- Added ModOption.setGlobal(boolean) for settng whether getValue() is to use the global value
- Added ModSliderOption.setGlobalValue(Float) override
- Added ModSliderOption.setLocalValue(Float) override
- Added ModSliderOption.getFloatValue(float) for checking a given value
- Added ModSliderOption.getIntValue(float) for checking a given value 
- Added ModOptionsAPI.getMultiplayerMods() for getting mods that have server specific options enabled
- Added ModOptionsAPI.getSingleplayerMos() for getting mods that have world specific options enabled
- Added ModOptionsGuiController.getDisplayString(ModOption, boolean) to denote whether to use local value or not
(Non Breaking Changes)
- Changed ModOptions.loadValues() to load only global values
- Changed ModOptions.save() to save only global values
- Changed ModOption.setValue(E) to set the current scope value
- Changed ModOption.getValue() to use the global value only when ModOptions.global is true
- Changed ModSliderOption.getFloatValue() to use current scope value
- Changed ModSliderOption.getIntValue() to use current scope value
- Changed ModSliderOption.setIntValue(int) to only current scope value to 1st param
- Changed ModOptionsGuiController.getDisplayString(ModOption) to use global value only

0.3.3.2
- Removed bug causing options to not be saved when "esc" is pressed.

0.3.3.1
- Improved ordering of elements in API. Ordered in opposite direction to the way they are added. This will be flipped later. Previous order was Chaotic due to use of Hashtable. Using more ordered LinkedHashMap.
- Removed output to terminal by ModOptionsAPI (hi and hid were being output)

0.3.3
- Compatible with beta 1.4
- Compatibility with GUIAPI probably temporarily lost.

0.3.2
- Fixed a menu display bug
- Set a constructor for ModMappedMultiOption to private. It was not meant to be public in the first place.

0.3.1
- Fixed a menu display bug

0.3
- Added ModMappedMultiOption for mapping strings to integer keys for more advanced case/ arithmetic comparisons
- Re-implemented backend to ensure ordering of options is personalised and not alphabetical.
- Added GUI controller API to allow for more control over display of your options
- Added a SuffixFormat in the new MOFormatter class for those wishing to append suffixes to their values.
- Improved general backend
- Fixed slider bugs
- Improved entire slider class

0.2
- Changed getOptionValue return type from Object to String for easier parsing
- Added new constructor for ModBooleanOption of: (String name, String OnVal, String OffVal)
- Bug fixes
-- Improved saving - no null values stored when constructing a new ModSliderOption with a high/low value
-- Fixed subMenus not actually displaying due to an incorrect id check.

0.1
- Initial Version