MenuHelperHelper

A resource for PAYDAY 2 that simplifies menu creation as much as possible.

Example of use

Items

Menu items usually represent respective values in a settings table of a mod. MenuHelperHelper builds a settings menu based on the settings table you provide.

The type of an item is defined by the type of the value in the table. Number values are represented by sliders, booleans by toggle items, strings by text input fields and so on.

What you need to do first is create a table of settings and format it as explained below.

Example of a settings table

#!lua
settings_table = {

    slider = 5,

    toggle = true,

    input = 'text',

    button = function(item) return end,

    multiple_choice = { 'choice1', 'choice2', 'choice3', value = 1 },

    sub_menu = { slider2 = 10, toggle2 = false },

    divider = '_ 20'
}

Field slider contains a number, so a slider will be created for it. The value in the table (5) will be used as default value.

Field toggle contains a boolean value, so a toggle item will be created to represent it. It will be set to 'true' by default.

Input field will add an editable text item to the menu.

For button a button will be created. When user clicks on it, the function will be executed. The 'item' argument is the button menu item the user just clicked.

Since multiple_choice table contains an item with index 1 ('choice1'), it will be treated as a multiple choice item. 'value' field defines the index of the default value.

Sub_menu is a table without index 1, so it will be made into a submenu instead. Inside that menu there will be 'slider2' and 'toggle2'.

Divider is a string with underscore followed by a space followed by a number. This will be turned into a divider (empty space), the size is defined by the number.

CreateMenu()

CreateMenu() is the main function of MenuHelperHelper. It takes your settings table and sets up the menu for it.

CreateMenu() Example

#!lua
my_table = {
    set1 = 5,
    set2 = true
}

MenuHelperHelper:CreateMenu(my_table, 'my_menu_id', 'My menu file.txt', function(settings, menu_id) 
    my_table = settings
end)

Second argument is the ID of your menu. Must be unique.

Third argument is the name of the save file your menu will save its data to. The file will be saved in mods/saves automatically. If you don't want saving, pass nil.

Fourth argument is the callback function. When user exits the menu, this function will be executed. The first argument to that function will be the new (changed) settings table. In the example above 'my_table' is simply replaced with the new table. The second argument will be the menu ID (allows you to use one callback function for many menus).

When you run CreateMenu(), the save file is accessed (if present) and the settings are loaded from it. Those settings are instantly updated in 'my_table'.

Localization

All of the menu items are given names according to the 'path' to them in the table.

#!lua
my_table = {
    set1 = 5,
    set2 = true,
    more = { set3 = 4 }
}

(it is supposed that any ID here also has a comment ID for when you mouse over the item, it's the same ID plus '_desc' in the end)

For other fields:

#!lua
my_table_set1
my_table_set2
my_table_more - ID for the name of the submenu
my_table_more_set3

For that simply add another (fifth) argument when calling CreateMenu():

#!lua
MenuHelperHelper:CreateMenu(my_table, 'my_menu_id', 'My menu file.txt', function(settings, menu_id) 
    my_table = settings
end, 'localization.json')

The file will be a json-formatted localization file with string IDs matching empty texts that you'll need to fill.

Make sure to remove that argument before releasing your mod.

Tweaks

By default, the limits of a slider are from 0 to 50. You may want to change that, as well as some other things. That's what MenuHelperHelper._tweaks table is for.

#!lua
MenuHelperHelper._tweaks = {
    default = { slider_max = 100, slider_min = 10 }
}

Here are all of the parameters available at the moment:

#!lua
priority  -- The higher this is, the higher the item is in the menu
localized  -- If localized string should be used (if not you'll see IDs like 'set2')
slider_min -- Minimum value for sliders
slider_max -- Maximum value for sliders
show_value  -- If slider should display the number value set on it
float  -- If true, allows the slider to save values with floating point (otherwise they are rounded down)
divider -- If false, divider formatted string ('_ 20') will be treated as a normal string
callback  -- Sets the function to call when the value is changed (a function value)
ignore  -- If true, a menu item won't be created for the table field, but its data will be saved to the save file

Only for 'default':
instant_callback  -- If true, callback is called after every change, otherwise after user exits the menu
save_only_changed  -- If true, settings set as default won't be saved to the save file

You can give parameters to certain items by their names like this:

#!lua
my_table = {
    set1 = 5,
    set2 = true,
    more = { set3 = 4 },
    more2 = { set3 = 6 }
}

MenuHelperHelper._tweaks = {
    set1 = { slider_max = 100, slider_min = 10 },
    set3 = { show_value = false }
}

Tweaks for certain items are not merged with 'default' tweaks.

MenuHelperHelper._tweaks is reset after every CreateMenu() call.

SetValue()

Sometimes you may need to change a setting in your scripts. If you change it, the menu item that represents it will not change. To change a value in the menu, use SetValue() function:

#!lua
my_table = {
    set1 = 5,
    set2 = true,
    more = { set3 = 4 }
}

MenuHelperHelper:SetValue('my_menu_id:more:set3', 10, ':')

Second argument is the new value.

Third argument is the separator for 'path'. It defaults to colon and can be omitted.

Other things

• The menu saves the settings automatially, but not after SetValue(). If you want to force the menu to save the settings, call MenuCallbackHandler:MHH_save_my_menu_id(). Replace 'my_menu_id' with your menu ID.

• Use MenuHelperHelper:HasMenu(menu_id) to check if MenuHelperHelper has created a menu with certain ID.