Adding a RetroArch menu option¶
The RetroArch menu system is a bit complex as no UI framework is used for implementing it, due to extreme portability reasons. This guide outlines adding one setting to RetroArch global configuration and the corresponding menu entry, but you may encounter special menus or more complex settings. Try to add the new bits to places where they can be logically found.
Files you need to change¶
msg_hash_us.h
msg_hash_lbl.h
msg_hash.h
menu_cbs_sublabel.c
menu_setting.c
menu_displaylist.c
configuration.c
configuration.h
config.def.h
ui/drivers/qt/qt_options.cpp
Creating the config variable¶
For this example the variable will be a boolean option for showing messages about failed autoconfig. You can also view the pull request here.
- Open
config.def.h
- Add
#define DEFAULT_NOTIFICATION_SHOW_AUTOCONFIG_FAILS true
to provide a generic default for the option. If needed, use compiler switches for different defaults on different platforms. - Open
configuration.h
- There are sections for each variable type(string, float, int, uint and bool) go to
bools
and addbool notification_show_autoconfig_fails;
- Open
configuration.c
- Add
SETTING_BOOL("notification_show_autoconfig_fails", &settings->bools.notification_show_autoconfig_fails, true, DEFAULT_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, false);
topopulate_settings_bool
.
The variable is now part of global RetroArch settings, will be saved/loaded from configuration file and can be used from RetroArch code, but the menu still doesn't know it exists.
Defining menu labels and messages¶
Time to define the labels for identifying and displaying the new setting.
- Open
msg_hash.h
- Add
MENU_LABEL(NOTIFICATION_SHOW_AUTOCONFIG_FAILS)
toenum msg_hash_enums
- Open
intl/msg_hash_lbl.h
- Add
MSG_HASH( MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, "notification_show_autoconfig_fails")
in theMENU_ENUM_LABEL_
section. This identifier may appear in logs, but not in the menu. - Open
intl/msg_hash_us.h
- Add
MSG_HASH( MENU_ENUM_LABEL_VALUE_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, "Input (Autoconfig) Failure Notifications")
in theMENU_ENUM_LABEL_VALUE_
section. This is what the user and the translators actually see. - Add
MSG_HASH( MENU_ENUM_SUBLABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, "Display an on-screen message when input devices could not be configured.")
section. Sublabels are a bit more detailed explanations that appear underneath the menu item.
The option is now defined but the menu has still not been told to display it.
Displaying your option¶
Now the menu has to be told how to display the option.
- Open
menu/cbs/menu_cbs_sublabel.c
- Add
DEFAULT_SUBLABEL_MACRO( action_bind_sublabel_notification_show_autoconfig_fails, MENU_ENUM_SUBLABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS)
to the block ofDEFAULT_SUBLABEL_MACRO
functions. - Add
case MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS: BIND_ACTION_SUBLABEL(cbs, action_bind_sublabel_notification_show_autoconfig_fails); break;
to themenu_cbs_init_bind_sublabel
function. - Open
menu/menu_setting.c
- Find your variables section(saving, netplay, video, ...) and add
CONFIG_BOOL
macro. The options are too numerous to list here, look for a similar example to what you plan to add. This entry controls the related setting, the menu labels, and possible actions. Simple config types already have implemented actions for changing (like toggling the boolean value with left/right), but if something more complex is needed, like a list of predefined values, it will need to be implemented in other menu files. - Open
menu/menu_displaylist.c
- Find your variables section and add
{MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, PARSE_ONLY_BOOL, false },
the position of this command in the list is what determines the order of the menu entries, the first run is at the top of the list. - Open
ui/drivers/qt/qt_options.cpp
- Find the corresponding menu and add the option, in this case
notificationsGroup->add(MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG);
. This represents the menu item in the desktop menu.
Finishing¶
This guide only introduces the English menu labels. Translations are handled via Crowdin, after the pull request is accepted, new strings will appear for translators. New items wil be shown to users in English until translation is done.
There are several possibilities that can be done with the menu system, but most require additional functions. Help text may also be defined (a slightly longer description that can be displayed with Select button). Some of the menu code is dynamic depending on e.g. number of users, those items usually require extra care. Icon assignments are handled in the menu drivers (ozone, xmb, glui).