Register to the configuration menu

Edit me

Plugins can register add their configuration to the configuration menu. This menu can be opened during gameplay to configure plugins.

Register configuration

To register a configuration to the plugin loader, the plugin need use the WUPS_GET_CONFIG macro.
This macro does only work in a C++ Context.
Usage:

#include <wups/config.h>

WUPS_GET_CONFIG() {
    WUPSConfig* config = new WUPSConfig("Example plugin");

    // setting up the the config

    return config;
}

The macro needs to return a heap pointer to a WUPSConfig object. The loader will take of deleting the object.

Structure of a `WUPSConfig`

A WUPSConfig is the top-level object which contains all information needed to created a configuration menu for a plugin. It contains categories which themself contain the actual items. The structure is illustrated in the following:

WUPSConfig ("HID to VPAD")
    |
    |--> WUPSConfigCategory ("Main")
    |            |
    |            |--> WUPSConfigItem ("Enable rumble")
    |            |--> WUPSConfigItem ("Enable network client")
    |
    |--> WUPSConfigCategory ("Controller Mapping")
                 |
                 |--> WUPSConfigItem ("Gamepad mapping")
                 |--> WUPSConfigItem ("Pro controller 1 mapping")
   [...]

A detailed documentation of all functions of a WUPSConfig can be found in the header.

Adding a category - WUPSConfigCategory

As said before, the WUPSConfig contains one or more categories. To create a category, you simply use the WUPSConfigCategory * addCategory(std::string categoryName) on a WUPSConfig object.

#include <wups/config.h>

WUPS_GET_CONFIG() {
    WUPSConfig* config = new WUPSConfig("Example plugin");
    //Create a new category
    WUPSConfigCategory* catOther = config->addCategory("Other");
    // setting up the the config

    return config;
}

It’s also possible to add an existing WUPSConfigCategory using WUPSConfigCategory * addCategory(WUPSConfigCategory * category). A detailed documentation of all functions can be found in the header.
You don’t have to take care of deleting the created WUPSConfigCategory, the plugin loader will do that for you.

Adding an item - WUPSConfigItem

Each category can hold multiple items. These items need be inherited from the abstract WUPSConfigItem class.
WUPS provide several implementations that can be used, but it’s also possible to use an own implementation. See the WUPSConfigItem class for details on the functions that need to be implemented. Example usage using a boolean item (WUPSConfigItemBoolean, provided by WUPS):

#include <wups/config.h>

// callback that will be called when the value changes.
void rumbleConfigChanged(WUPSConfigItemBoolean * configItem, bool newValue) {
    DEBUG_FUNCTION_LINE("New rumble value %d\n",newValue);
}

WUPS_GET_CONFIG() {
    WUPSConfig* config = new WUPSConfig("Example plugin");
    //Create a new category
    WUPSConfigCategory* catOther = config->addCategory("Other");
    
    // Add a boolean item to the category
    //                item Type                | config id | displayed name | default value | onChangeCallback.
    catOther->addItem(new WUPSConfigItemBoolean("rumble", "Enable rumble", true,              rumbleConfigChanged));
    
    return config;
}

You don’t have to take care of deleting the created WUPSConfigItem, the plugin loader will do that for you.

Automatic save/load of configurations

The Wii U Plugin System tries automatically persist the configurations to the SD Card. It created configuration files next to the plugins. When you have for example a sd:/wiiu/plugins/hidtovpad.wups, a sd:/wiiu/plugins/hidtovpad.cfg will be created.
Everytime you start or switch an application, this configuration will be read from the sd card. In case the loaded value is different from the default on, the “changed”-callback of an item will be called. If possible, make sure to always pass the current value as default value. Otherwise the callback will be called more than necessary (each time you switch an application or open the menu).

Everytime the configuration menu is opened, the configuration from the sd card will be read. Everytime you close it, the changes will be written to the sd card.
To persist a configuration, each item has an “configID”. Using this, the values can be saved as key/value pairs, where the key is the configID. The value is provided by the WUPSConfigItem implementation, which need to implement a std::string persist() and void loadValue(std::string persistedValue) function. See the WUPSConfigItem class for more information.

The idea is to have the following workflow.

Choose a default value for a configuration item in case no configuration was saved before.
Save it in a variable which lays in the .data section. This allows the variable to keep the value even when the running application switches.
Update this variable inside the valueChanged callback.
Use this variable as the default value for the config item.

Example using the WUPSConfigItemBoolean:

#include <wups/config.h>
#include <wups/config/WUPSConfigItemBoolean.h>

// Save a variable into the data section so it'll survive changing the apps.
// And give it the default value "false"
bool gRumbleActive __attribute__((section(".data"))) = false;

// callback that will be called when the value changes.
void rumbleConfigChanged(WUPSConfigItemBoolean * item, bool newValue) {
    DEBUG_FUNCTION_LINE("New rumble value %d\n",newValue);
    
    // Update the "gRumbleActive" with the new value. Use it as a default value the next time we build the config item
    gRumbleActive = newValue;
}

WUPS_GET_CONFIG() {
    WUPSConfig* config = new WUPSConfig("Example plugin");
    //Create a new category
    WUPSConfigCategory* catOther = config->addCategory("Other");
    
    // Add a boolean item to the category. As default value we choose the current value which is saved in the "gRumbleActive" variable.
    //                item Type                | config id | displayed name | default value | onChangeCallback.
    catOther->addItem(new WUPSConfigItemBoolean("rumble", "Enable rumble",    gRumbleActive, rumbleConfigChanged));
    
    return config;
}

Provided `WUPSConfigItem` implementations

The plugin system provides some item implementations which can be used.

WUPSConfigItemBoolean - simple boolean values

This item can be used for simple boolean values (e.g. on/off switches).

Can be found in: #include <wups/config/WUPSConfigItemBoolean.h>

Constructor:

typedef void (*BooleanValueChangedCallback)(WUPSConfigItemBoolean*, bool);

WUPSConfigItemBoolean(std::string configID, std::string displayName, bool defaultValue, BooleanValueChangedCallback callback);

configID:
ID which is used to save the state of the item. Needs to be unique across the whole plugin config
displayName:
Text that will displayed to the describe this item on the configuration menu.
defaultValue:
The default value of the item.
callback:
Callback that will be called (with the new value) whenever the configuration menu has been closed and value changed. It will also be called when the value read from the sd card is different than the default value.

Notes:
On default the text for a “true”-vale is “on”, and for a “false”-value if “off”. You can change it by using void setTrueValueName(std::string trueValName) or void setFalseValueName(std::string falseValName) on a WUPSConfigItemBoolean object.

Usage example:


#include <wups.h>
#include <wups/config.h>
#include <wups/config/WUPSConfigItemBoolean.h>

// callback that will be called when the value changes.
void rumbleConfigChanged(bool newValue) {
    DEBUG_FUNCTION_LINE("New rumble value %d\n",newValue);
}

WUPS_GET_CONFIG() {
    WUPSConfig* config = new WUPSConfig("Example plugin");
    WUPSConfigCategory* catOther = config->addCategory("Other");
    
    // Add a boolean item to the category
    //                item Type                | config id | displayed name | default value | onChangeCallback.
    catOther->addItem(new WUPSConfigItemBoolean("rumble", "Enable rumble", true,              rumbleConfigChanged));
    
    return config;
}

See the class definition for more information:
https://github.com/Maschell/WiiUPluginSystem/blob/master/wups_include/wups/config/WUPSConfigItemBoolean.h

WUPSConfigItemMultipleValues - Multiple choice out of multiple labeled values

This item can be used to create a item which multiple, pre-defined values. Each value has it’s own label (provided as value/label pairs).

Can be found in: #include <wups/config/WUPSConfigItemMultipleValues.h>

Constructor:

typedef void (*MultipleValuesChangedCallback)(WUPSConfigItemMultipleValues*, int32_t);

WUPSConfigItemMultipleValues(std::string configID, std::string displayName, int32_t defaultValue, std::map<int32_t,std::string> values_, MultipleValuesChangedCallback callback);

configID:
ID which is used to save the state of the item. Needs to be unique across the whole plugin config.
displayName:
Text that will displayed to the describe this item on the configuration menu.
defaultValue:
The default value of the item.
values:
Map which provides a list of possible values and their label.
callback:
Callback that will be called (with the new value) whenever the configuration menu has been closed and value has been changed. It will also be called when the value read from the sd card is different than the default value.

Notes:
If the default value is not a part of the provided value list, the first element will be used as default value.