API Functions/InterfaceOptions

These can be found in "Red 5 Studios\Firefall\system\gui\lib\lib_InterfaceOptions.lua".
== Usage ==
<nowiki>
Base Functions:
	InterfaceOptions.AddMovableFrame(table)
		frame = [GUI or name] the var for the frame or the name of the frame
		scalable = [boolean] defines if the frame should be scalable
		label or label_key = [string] the frame's label or the SDB key string for the label
	InterfaceOptions.SaveVersion(number) --optional function
		if not used then the assumed version is 1
		Use to ignore saved values if the saved version number is different then the current one
	InterfaceOptions.SetCallbackFunc(func [, title]) --required function
		this may only be called once and it must be done during ON_COMPONENT_LOAD
		func must be a function if you have options or false/nil if you just have movable frames without options
			the func will recieve (id, val) as args
		title is an optional override for the options header/root label, by default it uses the title assigned in the xml
	InterfaceOptions.NotifyOnDefaults(boolean) --optional function
		this will fire the func supplied by SetCallbackFunc with the id of "__DEFAULT", incase you want to know when the user default all the options
	InterfaceOptions.NotifyOnLoaded(boolean) --optional function
		this will fire the func supplied by SetCallbackFunc with the id of "__LOADED", incase you want to know when all the options are finished loading
	InterfaceOptions.NotifyOnDisplay(boolean) --optional function
		this will fire the func supplied by SetCallbackFunc with the id of "__DISPLAY" and a boolean value for if the interface options are visible
		Useful for conditionally displayed UI to display a dummy version for interface configuring
Option Creation Functions:
	Note Temp WIP Feature:
		all the following options support a table field of subtab which should be an array of strings, except AddChoiceEntry which isn't really an option
		this will place the option into a sub-tab based on those fields
		ie: InterfaceOptions.AddCheckBox({id="wip", label="wip", default=true, subtab={"Sub1","Sub2"}})
			Interface>ComponentName>Sub1>Sub2 is the tab tree in which you will find this option
		to place multiple option in the same sub-tab, they will all need to have the same subtab array
		there is currently no limit to the depth of nested sub-tabs outside of the indenting the tabs get
		This sub-tab system might get a facelift in the future when R5 components start using it more
	InterfaceOptions.AddMultiArt(table)
		id = [string] unique identifier
		url = [string] url of a WebImage						--use 1 out of the 3; url, icon, or texture
		icon = [number] id of an Icon
		texture = [string] texture name of a Texture			--will accept textures defined in the components xml as well as the human_skin
		region = [string][optional] region name for a Texture
		width = [number] width for the image					--use 2 out of the 3; height, width, or aspect
		height = [number] height for the image
		aspect = [number] height for the image
		padding = [number][optional] padding + height determines how much height the entry takes up
		y_offset = [string][optional] +number or -number; center-y:50%"..y_offset; offsets the image from the center of the entry
		x_offset = [string][optional] +number or -number; center-x:50%"..x_offset; offsets the image from the center of the entry
		tint = [string][optional] tint to apply to the image
		OnClickUrl = [string][optional] OnClick of the image will open an external browser to the supplied url
	InterfaceOptions.AddButton(table)
		id = [string] unique identifier
		label or label_key = [string] the option's label or the SDB key string for the label
		tooltip or tooltip_key = [string][optional] like label except displays on mouseover in a popup if present
		Note: a button will trigger the SetCallbackFunc witht he id and no value whenever it is clicked
	InterfaceOptions.StartGroup(table)
		label or label_key = [string] the option's label or the SDB key string for the label
		checkbox = [boolean][optional] this adds a checkbox to the group which will have a working value as well as collapse the group when it is unchecked, useful if a group of options has a disable option
			the following are only needed if checkbox is true
			id = [string] unique identifier
			tooltip or tooltip_key = [string][optional] like label except displays on mouseover in a popup if present
			default = [boolean] the default value for the option
		Note: nested groups are not supported, each StartGroup needs to have a StopGroup before a new start can be triggered.
	InterfaceOptions.StopGroup()
		Note: nested groups are not supported, each StartGroup needs to have a StopGroup before a new start can be triggered.
		no params needed
	InterfaceOptions.AddCheckBox(table)
		id = [string] unique identifier
		label or label_key = [string] the option's label or the SDB key string for the label
		tooltip or tooltip_key = [string][optional] like label except displays on mouseover in a popup if present
		default = [boolean] the default value for the option
	InterfaceOptions.AddSlider(table)
		id = [string] unique identifier
		label or label_key = [string] the option's label or the SDB key string for the label
		tooltip or tooltip_key = [string][optional] like label except displays on mouseover in a popup if present
		default = [number] the default value for the option
		min = [number] the minimum range
		max = [number] the maximum range
		inc = [number] the increment amounts
		multi = [number][optional] muliples the value with the multi for displaying, used with percents that are 0-1 to display as 0-100 with a multi of 100
		format = [string][optional] the format to use in string.format(format, value) for the displayed value, does not affect value's value, use '%0.0f' instead of '%d' for integers
		prefix = [string][optional] prefix for the displayed number
		suffix = [string][optional] suffix for the displayed number, useful for adding '%' or 's' for percents and seconds
	InterfaceOptions.AddTextInput(table)
		id = [string] unique identifier
		label or label_key = [string] the option's label or the SDB key string for the label
		tooltip or tooltip_key = [string][optional] like label except displays on mouseover in a popup if present
		default = [string] the default value for the option
		numeric = [boolean][optional][default: false] enforces only numeric chars [0123456789-.]
		masked = [boolean][optional][default: false] masks the text with ********, this is a visual only mask, the saved value will not be masked
		whitespace = [boolean][optional][default: true] whether to allow spaces or not
		maxlen = [number][optional][default: 256] max char length of the text input box
	InterfaceOptions.AddColorPicker(table)
		id = [string] unique identifier
		label or label_key = [string] the option's label or the SDB key string for the label
		tooltip or tooltip_key = [string][optional] like label except displays on mouseover in a popup if present
		default = [table] the default value for the option
			tint = [string] the RRGGBB hex color code
			alpha = [number range: 0 -- 1][optional] alpha value if the alpha is to be adjustable
			exposure = [number range: -1 -- 1][optional] exposure value if the exposure is to be adjustable
	InterfaceOptions.AddChoiceMenu(table)
		id = [string] unique identifier
		label or label_key = [string] the option's label or the SDB key string for the label
		tooltip or tooltip_key = [string][optional] like label except displays on mouseover in a popup if present
		default = [string] the default value for the option, must link up with a choice's val
		NOTE: all values from a ListMenu come back as strings, even if the entries value was defined as a number
	InterfaceOptions.AddChoiceEntry(table)
		menuId = [string] the AddListMenu id that this choice is attacted to
		label or label_key = [string] the choice's label or the SDB key string for the label
		val = [string] the value for the choice entry
Option Manipulation Functions:
	InterfaceOptions.DisableOption(ID, bool)
		ID = [string] the option id that you want to disable
		bool = [boolean] true = disabled, false = enabled
	InterfaceOptions.EnableOption(ID, bool)
		ID = [string] the option id that you want to disable
		bool = [boolean] true = enabled, false = disabled
	InterfaceOptions.UpdateLabel(ID, label[, key])
		ID = [string] the option id that you want to disable
		label = [string] the new label for the option, or keystring if key is true
		key = [boolean][optional] whether the label is a key_string that needs to be lookedup first
Frame Manipulation Functions:
	InterfaceOptions.ChangeFrameHeight(frame, val)
		frame = [GUI or name] the var for the frame or the name of the frame
		val = [string or number] new frame height
	InterfaceOptions.ChangeFrameWidth(frame, val)
		frame = [GUI or name] the var for the frame or the name of the frame
		val = [string or number] new frame width
	InterfaceOptions.UpdateMovableFrame(frame)
		frame = [GUI or name] the var for the frame or the name of the frame
		used if the frame had to be tinkered with and you want to get it realigned and the position saved
	InterfaceOptions.DisableFrameMobility(frame, bool)
		frame = [GUI or name] the var for the frame or the name of the frame
		bool = [boolean] true = removes the frames mobility outline, false = displays it
</nowiki>
 InterfaceOptions.AddDivider({id= "DISABLE?", label="OVERRIDE"})
This just adds a divider with some text in it. I suppose you could use more than one for a small readme, but that would take up some space. Remember that now everyone is using the same resolution screen as you.
;Examples:
<nowiki>
require "lib/lib_InterfaceOptions"
local enabled = true;
InterfaceOptions.AddCheckBox({id="ENABLED", label="Disable addon", default=false}) --Disable the entire addon?
function OnMessage(args)
	-- log("Received Message ["..args.type.."] with data ["..tostring(args.data)..']')
	if args.type == "ENABLED" then 
		enabled = not args.data -- Since we call the option "Disable Addon"
	end
end
</nowiki>
;xml file
<nowiki>
<Frames>
 <HUDFrame name="ExampleMainHUD">
 <OnMessage bind="OnMessage"/>
 </HUDFrame>
</Frames>
</nowiki>
Category:Addon_API