MCM Option Types

Version 1.0

Introduction

This guide introduces all available option types and explains how to use them.

It's assumed that you read MCM Quickstart and understood the basic concepts behind creating a custom config menu. If not, you should do that before continuing here.

These are all available option types:

• Empty Option
• Header Option
• Text Option
• Toggle Option
• Slider Option
• Menu Option
• Color Option
• Keymap Option

Adding options works pretty much the same for all types in OnPageReset, same goes for OnOptionHighlight and OnOptionDefault. Where they differ is how option selection is handled.

Empty Option

Empty options are used to add empty space between other options. They cannot be interacted with, hence you don't have to save their OID.

Functions:

int function AddEmptyOption()

Example:

event OnPageReset(string a_page)
	AddEmptyOption()
endEvent

Header Option

A header option shows a decorated title text. It can be used to group several options together under a common category. Header options cannot be interacted with, so you normally don't have to save the OID.

Functions:

; Add
int function AddHeaderOption(string text, int flags = 0)

; Change
function SetOptionFlags(int option, int flags, bool noUpdate = false)

Example:

event OnPageReset(string page)
	AddHeaderOption("Gameplay")
endEvent

Text Option

Functions:

; Add
int function AddTextOption(string text, string value, int flags = 0)

; Change
function SetTextOptionValue(int option, string value, bool noUpdate = false)
function SetOptionFlags(int option, int flags, bool noUpdate = false)

Events:

; Select
event OnOptionSelect(int option)

; Highlight
event OnOptionHighlight(int option)

; Default
event OnOptionDefault(int option)

Example:

; OID
int counterOID_T ; _T for text

; State
int counter = 0


event OnPageReset(string page)
	counterOID_T = AddTextOption("Select Counter", counter)
endEvent


event OnOptionSelect(int option)
	if (option == counterOID_T)
		counter += 1
		SetTextOptionValue(counterOID_T, counter)
	endIf
endEvent

Toggle Option

Functions:

; Add
int function AddToggleOption(string text, bool checked, int flags = 0)

; Change
function SetToggleOptionValue(int option, bool checked, bool noUpdate = false)
function SetOptionFlags(int option, int flags, bool noUpdate = false)

Events:

; Select
event OnOptionSelect(int option)

; Highlight
event OnOptionHighlight(int option)

; Default
event OnOptionDefault(int option)

Example:

; OID
int toggleOID_B ; _B for toggle

; State
bool toggleState = false


event OnPageReset(string page)
	toggleOID_B = AddToggleOption("My Checkbox", toggleState)
endEvent


event OnOptionSelect(int option)
	if (option == toggleOID_B)
		toggleState = !toggleState
		SetTextOptionValue(toggleOID_B, toggleState)
	endIf
endEvent

Slider Option

Functions:

; Add
int function AddSliderOption(string text, float value, string formatString = "", int flags = 0)

; Change
function SetSliderOptionValue(int option, float value, string formatString = "", bool noUpdate = false)
function SetOptionFlags(int option, int flags, bool noUpdate = false)

; Dialog setup
function SetSliderDialogStartValue(float value)
function SetSliderDialogDefaultValue(float value)
function SetSliderDialogRange(float minValue, float maxValue)
function SetSliderDialogInterval(float value)

Events:

; Dialog open
event OnOptionSliderOpen(int option)

; Dialog accept
event OnOptionSliderAccept(int option, float value)

; Highlight
event OnOptionHighlight(int option)

; Default
event OnOptionDefault(int option)

Example:

; OID
int frequencyOID_S ; _S for slider
int durationOID_S ; _S for slider

; State
float frequency = 2
float duration = 30


event OnPageReset(string page)
	frequencyOID_S = AddSliderOption("How often?", frequency, "Every {0} days")
	durationOID_S = AddSliderOption("How long?", duration, "For {0} minutes")
endEvent


event OnOptionSliderOpen(int option)
	if (option == frequencyOID_S)
		SetSliderDialogStartValue(frequency)
		SetSliderDialogDefaultValue(2.0)
		SetSliderDialogRange(1.0,  14.0)
		SetSliderDialogInterval(1.0)

	elseIf (option == durationOID_S)
		SetSliderDialogStartValue(duration)
		SetSliderDialogDefaultValue(30)
		SetSliderDialogRange(0, 120)
		SetSliderDialogInterval(5.0)

	endIf
endEvent


event OnOptionSliderAccept(int option, float value)
	if (option == frequencyOID_S)
		frequency = value
		SetSliderOptionValue(frequencyOID_S, frequency, "Every {0} days")

	elseIf (option == durationOID_S)
		duration = value
		SetSliderOptionValue(durationOID_S, duration, "For {0} minutes")

	endIf
endEvent

Menu Option

Functions:

; Add
int function AddMenuOption(string text, string value, int flags = 0)

; Change
function SetMenuOptionValue(int option, string value, bool noUpdate = false)
function SetOptionFlags(int option, int flags, bool noUpdate = false)

; Dialog setup
function SetMenuDialogStartIndex(int value)
function SetMenuDialogDefaultIndex(int value)
function SetMenuDialogOptions(string[] options)

Events:

; Dialog open
event OnOptionMenuOpen(int option)

; Dialog accept
event OnOptionMenuAccept(int option, int index)

; Highlight
event OnOptionHighlight(int option)

; Default
event OnOptionDefault(int option)

Example:

; List
string[] difficultyList

; OID
int difficultyOID_M ; _M for menu

; State
int difficultyIndex = 1


event OnInit()
	super.OnInit()

	difficultyList = new string[3]
	difficultyList[0] = "Easy"
	difficultyList[1] = "Normal"
	difficultyList[2] = "Hard"
endEvent

event OnPageReset(string page)
	difficultyOID_M = AddMenuOption("Difficulty", difficultyList[difficultyIndex])
endEvent


event OnOptionMenuOpen(int option)
	if (option == difficultyOID_M)
		SetMenuDialogOptions(difficultyList)
		SetMenuDialogStartIndex(difficultyIndex)
		SetMenuDialogDefaultIndex(1)
	endIf
endEvent


event OnOptionMenuAccept(int option, int index)
	if (option == difficultyOID_M)
		difficultyIndex = index
		SetMenuOptionValue(difficultyOID_M, difficultyList[difficultyIndex])
	endIf
endEvent

Color Option

Functions:

; Add
int function AddColorOption(string text, int color, int flags = 0)

; Change
function SetColorOptionValue(int option, int color, bool noUpdate = false)
function SetOptionFlags(int option, int flags, bool noUpdate = false)

; Dialog setup
function SetColorDialogStartColor(int color)
function SetColorDialogDefaultColor(int color)

Events:

; Dialog open
event OnOptionColorOpen(int option)

; Dialog accept
event OnOptionColorAccept(int option, int color)

; Highlight
event OnOptionHighlight(int option)

; Default
event OnOptionDefault(int option)

Example:

; OID
int colorOID_C ; _C for color

int favColor = 0xFF0000


event OnPageReset(string page)
	colorOID_C = AddColorOption("Favorite color", favColor)
endEvent


event OnOptionColorOpen(int option)
	if (option == colorOID_C)
		SetColorDialogStartColor(color)
		SetColorDialogDefaultColor(0xFF0000)
	endIf
endEvent


event OnOptionColorAccept(int option, int color)
	if (option == colorOID_C)
		favColor = color
		SetColorOptionValue(colorOID_C, favColor)
	endIf
endEvent

Keymap Option

Functions:

; Add
int function AddKeyMapOption(string text, int keyCode, int flags = 0)

; Change
function SetKeyMapOptionValue(int option, int keyCode, bool noUpdate = false)
function SetOptionFlags(int option, int flags, bool noUpdate = false)

Events:

; Select
event OnOptionKeyMapChange(int option, int keyCode, string conflictControl = "", string conflictName = "")

; Highlight
event OnOptionHighlight(int option)

; Default
event OnOptionDefault(int option)

Example:

; OID
int keyOID_K ; _K for Keymap

int myKey = 37 ; K


event OnPageReset(string page)
	keyOID_K = AddKeyMapOption("My Hotkey", myKey)
endEvent


event OnOptionKeyMapChange(int option, int keyCode, string conflictControl = "", string conflictName = "")
	if (option == keyOID_K)
		myKey = keyCode
		SetKeyMapOptionValue(keyOID_K, myKey)
	endIf
endEvent