Skip to content

MCM Option Types

Jump to bottom
Sebastian edited this page Aug 19, 2015 · 26 revisions

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:

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)

Example:

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

Text Option

A text option displays a generic text/value pair. What you do with it, is up to you. Examples could be a text-based "On/Off" toggle or an uni-directional option stepper. You could also set up a text option for an "Uninstall" button.

Functions:

; Add
int function AddTextOption(string text, string value)

; Change
function SetTextOptionValue(int option, string value)

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

A toggle option displays a text label and a check box. There's not much more to say about this one.

Functions:

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

; Change
function SetToggleOptionValue(int option, bool checked)

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
		SetToggleOptionValue(toggleOID_B, toggleState)
	endIf
endEvent

Slider Option

Unlike the previous option types, slider options are dialog-based. This means selecting the option won't immediately result in a selection event, but instead a dialog is opened and a OnOptionSliderOpen event is generated.

In OnOptionSliderOpen you have to set up the parameters for the dialog.

Once the user has accepted a new value, OnOptionSliderAccept is executed. The dialog may also be canceled, in which case no further event is generated.

With the format string parameter you can embed the slider value in a string, e.g. "Every {0} hours", where {0} is replaced by the current value. The number inside the brackets sets the decimal places: A value of 1 with format string {2} is displayed as 1.00.

Functions:

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

; Change
function SetSliderOptionValue(int option, float value, string formatString = "{0}")

; 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 = 1.5


event OnPageReset(string page)
	frequencyOID_S = AddSliderOption("How often?", frequency, "Every {0} days")
	durationOID_S = AddSliderOption("How long?", duration, "For {1} hours")
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(1.5)
		SetSliderDialogRange(1.0, 24.0)
		SetSliderDialogInterval(0.5)

	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

A menu option is a dialog-based type as well. Selecting it will show a sub-menu with up to 128 entries. The entries are passed as a string array in OnOptionMenuOpen.

After the sub-menu dialog is closed, the selected menu index is passed to OnOptionMenuAccept.

When adding a OnInit to your script, don't forget to call parent.OnInit() first, so the initialization routine of SKI_ConfigBase is still executed.

Functions:

; Add
int function AddMenuOption(string text, string value)

; Change
function SetMenuOptionValue(int option, string value)

; 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()
	parent.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

A color option shows a color swatch dialog when selected. We handpicked the best colors in the world for you to choose from. Colors are passed as 0xRRGGBB hexadecimal numbers. So 0xFF0000 is red, 0xFFFFFF is white, 0x000000 is black etc.

You have to set up the dialog parameters in OnOptionColorOpen, the selected color is received in OnOptionColorAccept.

Functions:

; Add
int function AddColorOption(string text, int color)

; Change
function SetColorOptionValue(int option, int color)

; 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

A keymap option prompts the user to press a key have the option has been selected. It is not dialog-based, but the result generates a special event OnOptionKeyMapChange which is passed the pressed key.

It's up to you to accept or discard the pressed key. This includes reacting to potential conflicts by checking conflictControl and conflictName. See the Advanced Features guide for more details on this topic.

Functions:

; Add
int function AddKeyMapOption(string text, int keyCode)

; Change
function SetKeyMapOptionValue(int option, int keyCode)

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

Input Option

An input option shows a text input dialog when selected, which allows the user to enter a text string with the keyboard.

By default, the dialog starts with an empty input box. This can be changed by setting a start parameter in OnOptionInputOpen. The input can be processed in OnOptionInputAccept.

Functions:

; Add
int function AddInputOption(string text, string initialValue)

; Change
function SetColorOptionValue(int option, string newValue)

; Dialog setup
function SetInputDialogStartText(string value)

Events:

; Dialog open
event OnOptionInputOpen(int option)

; Dialog accept
event OnOptionInputAccept(int option, string input)

; Highlight
event OnOptionHighlight(int option)

; Default
event OnOptionDefault(int option)

Example:

; OID
int inputOID_I ; _I for input

string myName = "Drago Nborn"


event OnPageReset(string page)
	inputOID_I = AddInputOption("Character Name", myName)
endEvent


event OnOptionInputOpen(int option)
	if (option == inputOID_I)
		; Fill input box with current value
		SetInputDialogStartText(myName)
	endIf
endEvent


event OnOptionInputAccept(int option, string input)
	if (option == inputOID_I)
		myName= input
		SetInputOptionValue(inputOID_I, myName)
	endIf
endEvent
Clone this wiki locally