Skip to content

MCM Option Types

Jump to bottom
Mardoxx edited this page Oct 21, 2012 · 26 revisions

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:

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)

; Change
function SetOptionFlags(int option, int flags)

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)
function SetOptionFlags(int option, int flags)

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)
function SetOptionFlags(int option, int flags)

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

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.

Functions:

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

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

; 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)
function SetOptionFlags(int option, int flags)

; 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)
function SetOptionFlags(int option, int flags)

; 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)
function SetOptionFlags(int option, int flags)

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
Clone this wiki locally