Homebrew Menu

The Homebrew Menu (hbmenu) is the menu for launching homebrew applications. Applications are launched using the Homebrew ABI, hence normally nx-hbloader will do the actual launching.

Usage

See Homebrew Applications for SD layout etc.

Controls

Use the D-Pad/joystick to select the app/directory, up/down can be used for faster scrolling. Press A to launch the app. Navigating directories is supported, press A to enter a directory and press B to leave the current directory. Press Y to activate netloader and press B to deactivate netloader.

Press the - button to enter Theme Menu. Press X to (un)star the current menu entry.

Touch controls

To navigate through the list of folders and applications you can swipe left and right on the bottom list. To open an item you can tap on it in the list or with it highlighted tap the Open or Launch button prompt in the bottom right. To go back (a folder) you can swipe up or tap the Back button prompt in the bottom right (the latter is only available when no message-box is shown / netloader isn't active). To activate the netloader you can swipe down on the screen. To enter Theme Menu you can swipe left on the screen.

To (un)star the current menu entry you can touch the (un)star button prompt.

Status

The battery/charge/temperature status can be displayed, however this is only displayed when the required services are available/accessible.

The local-time and network status are also displayed.

Netloader

With netloader activated as described above you can load apps over the network with nxlink. With the toolchain setup run nxlink <nrofile> if your network can handle UDP broadcast messages. If nxlink fails with "No response from Switch!" you can use -a <ip address> before <nrofile> for the address to send the app to. See nxlink help for more options.

Themes

Themes can be optionally loaded from SD "/config/nx-hbmenu/themes/". The theme (or the default) can be selected using the Theme Menu via the - button. This uses libconfig. Default settings will be used for any settings not specified in the theme (including themeInfo).

The file extension is .cfg. .romfs is also supported, this is RomFs. With the toolchain setup you can run the following to build a .romfs: build_romfs {input directory} {out name}.romfs. The .romfs (and therefore the input directory) contains: '/theme.cfg', optionally '/icon.jpg' for the menu-entry in Theme Menu, and any assets.

Directories or .zip can also be used for themes, which have the same content described above for RomFs. .zip must directly contain the theme data, no directories.

See Homebrew Themes for a list of themes.

The string used for displaying the buttons/stars can be set with buttonAText, buttonBText, buttonXText, buttonYText, buttonMText, labelStarOnText, and labelStarOffText, but normally these can be left at the defaults. Change the value of the enableWaveBlending field to 1 to enable wave blending.

There's also borderColor, borderTextColor, and progressBarColor fields which can be set like the other color fields. logoColor can be used to set the RGB color of the logo, the alpha component is loaded from the logo image. highlightGradientEdgeColor is also available.

The color fields are RGBA.

Sample theme file:

themeInfo={
    name="Theme Name";
    author="Theme Author Name";
    version="1.0.0";
};

lightTheme={
    textColor=(0,0,0,255);
    frontWaveColor=(255,102,204,255);
    middleWaveColor=(255,51,153,255);
    backWaveColor=(204,0,153,255);
    backgroundColor=(233,236,241,255);
    highlightColor=(255,77,166,255);
    separatorColor=(128,0,128,255);
    enableWaveBlending=0;
};

darkTheme={
    textColor=(255,255,255,255);
    frontWaveColor=(255,51,153,255);
    middleWaveColor=(255,102,204,255);
    backWaveColor=(204,0,153,255);
    backgroundColor=(0,0,0,255);
    highlightColor=(255,77,166,255);
    separatorColor=(255,255,255,255);
    enableWaveBlending=0;
};

layout={
    <object name>={
        visible=true;
        posType=true;
        posStart = (100,400);
        posEnd = (170,0);
        size = (0,680);
    };
    
    // Any other objects here.
    
};

assets={
    <object name>={
        path = "relative_path_in_romfs";
        imageSize = (256,256);
    };

    // Any other objects here.
};

The 'layout' group is optional. Each group within this is for a layout object, these and the settings contained within the objects are all optional (defaults are used when not specified). How each setting in the layout objects' are handled are specific to each object. The 'visible' field controls whether the object is displayed, however this is ignored from config for some objects / unused for certain other objects. posType controls the handling for pos* fields: generally this does nothing, however with some objects this controls whether the pos is absolute (false) / relative to {base-pos} or special-handling (true). When posType is absolute the pos* fields must not be negative. The content of 'size' must not be negative.

Note that increasing *Wave height compared to the defaults can result in slowdown since sw-rendering is used.

Layout objects:

Layout object name	Description	'visible' from config ignored / field used	Used fields (besides 'visible')
logo	Hbmenu logo image.	Yes, yes	posStart
hbmenuVersion	Hbmenu version text.	Yes, yes	posStart
loaderInfo	Loader info text (displayed next to hbmenuVersion with the defaults). When the loader-info string doesn't contain a space, posStart is used directly for the text position, otherwise the right-justified position from posEnd is used.	Yes, yes	posStart, posEnd
attentionText	Attention text (Applet Mode text). When posType is relative (the default), the base position is the final position used by 'status'.	Yes, yes	posType, posStart
logInfo	Logging info for debug enabled via a build define.	Yes, yes	posStart
infoMsg	Text for NoAppsFound_Msg.	Yes, yes	posStart
menuPath	Menu path text.	No, yes	posStart, size[0]
menuTypeMsg	Text for the current type of menu (such as "Theme Menu"). Position is right-justified from posStart.	No, yes	posStart
msgBoxSeparator	Message-box separator. Position is relative to the bottom of the box.	No, no	posStart[1]
msgBoxBottomText	Message-box text displayed at the bottom below the separator. Position is relative to the bottom of the box.	No, no	posStart[1]
backgroundImage	Background image, not set with the defaults. Requires assets.background_image to be setup. This is drawn after backgroundColor, the maximum drawn y-pos is the same as backgroundColor (drawing where the waves are located is skipped). Note that this can result in slowdown since sw-rendering is used, especially with an image which covers the entire screen (besides where the waves are displayed).	No, yes	posStart
backWave	Back wave. The height is controlled by size[1], relative to the bottom of the screen.	No, yes	size[1]
middleWave	Middle wave. The height is controlled by size[1], relative to the bottom of the screen.	No, yes	size[1]
frontWave	Front wave. The height is controlled by size[1], relative to the bottom of the screen.	No, yes	size[1]
buttonA	Button A, displayed with the string from theme*.buttonAText. With posType=relative (default is absolute) the position is relative to buttonAText.	No, yes	posType, posStart
buttonAText	Button A text. posType=true is the same as absolute since the base-pos is 0.	No, yes	posType, posStart
buttonB	Button B, displayed with the string from theme*.buttonBText. With posType=relative the base position is buttonBText.	No, yes	posType, posStart
buttonBText	Button B text. With posType=relative the base position is buttonA. When buttonA is displayed with non-empty-directory, posStart is used, otherwise posEnd is used (buttonA not displayed).	No, yes	posType, posStart
buttonY	Button Y, displayed with the string from theme*.buttonYText. With posType=relative the base position is buttonYText.	No, yes	posType, posStart
buttonYText	Button Y text. With posType=relative the base position is buttonB, or if that's not displayed (menu path is in the root directory) the base is buttonA instead.	No, yes	posType, posStart
buttonM	Button '-', displayed with the string from theme*.buttonMText. With posType=relative the base position is buttonMText.	No, yes	posType, posStart
buttonMText	Button '-' text. With posType=relative the base position is buttonY.	No, yes	posType, posStart
buttonX	Button X, displayed with the string from theme*.buttonXText. With posType=relative the base position is buttonXText.	No, yes	posType, posStart
buttonXText	Button X text. With posType=relative the base position is buttonM.	No, yes	posType, posStart
networkIcon	Network status icon. With posType=relative the final position from 'status' is used for the base X-coordinate, however posStart[1] is used directly as the Y-coordinate regardless.	No, yes	posType, posStart
batteryCharge	Battery charge text. The position from posStart is right-justified.	No, yes	posStart
batteryIcon	Battery icon.	No, yes	posStart
chargingIcon	Battery charging icon.	No, yes	posStart
status	Text displayed for the time. The position from posStart is right-justified.	No, yes	posStart
temperature	Temperature text.	No, yes	posStart
menuList	Menu list. posStart is the absolute position for the first tile. posEnd is the relative position for the next tile, relative to the current tile (outline not included). The size doesn't include the outline.	No, no	posStart, posEnd, size
menuListTiles	posEnd[0] is the the maximum number of tile entries to adjust the currently selected entry index by, for example with HID input for DPad Up/Down.	No, no	posEnd[0]
menuListIcon	Menu entry icon. posStart is relative to the current tile entry (see menuList), regardless of posType. size must be >0 and <=256x256, otherwise 256x256 is used.	No, no	posStart, size
menuListName	Menu entry name text. posStart is relative to the current tile entry (see menuList), regardless of posType.	No, no	posStart, size
menuActiveEntryIcon	Icon for the currently active menu entry. size must be >0 and <=256x256, otherwise 256x256 is used.	No, yes	posStart, size
menuActiveEntryName	Name text for the currently active menu entry.	No, yes	posStart, size
menuActiveEntryAuthor	Author text for the currently active menu entry.	No, yes	posStart
menuActiveEntryVersion	Version text for the currently active menu entry.	No, yes	posStart

The 'assets' group is optional, it is only used with .romfs themes. The 'path' and 'imageSize' settings are required. imageSize[0-1] must be >0, and <= 1280x720. For some objects, the imageSize must match the internal imageSize for certain layout objects. The 'path' is the file-path to load the asset from, this is relative to "{mount-name}:/". imageSize is the size of the image, for non-.bin this must match the image size for the loaded file.

When an asset object is not specified, the settings are invalid, or loading the file fails, the default asset is used (if any).

The 'path' must have one of the below extensions:

• ".bin": Raw image without a header (the default images also use this). imageSize directly controls the size to load from here, the filesize must match width*height*{pixel-byte-size}.
• ".jpg"/".jpeg": JPEG, if you need transparency use PNG instead.
• ".png": PNG, background-color is black(all-zero) when the input PNG uses alpha and the target format is RGB24.

The pixel formats listed below are the formats used internally, the image-loading libraries handle converting the image to the required format where needed (except for .bin which uses the listed format directly).

Asset objects:

Layout object name	Description	Pixel format	Only alpha component is used, with RGB from textColor used instead	Size which the imageSize must match, from the internal layout object field
battery_icon	Battery icon.	RGBA32	Yes	None
charging_icon	Battery charging icon.	RGBA32	Yes	None
folder_icon	Folder/directory icon.	RGB24	No	256x256
invalid_icon	Icon displayed when loading the app's icon failed.	RGB24	No	256x256
theme_icon_dark	Default icon displayed in the Theme Menu for darkTheme.	RGB24	No	256x256
theme_icon_light	Default icon displayed in the Theme Menu for lightTheme.	RGB24	No	256x256
airplane_icon	Icon displayed when nifmGetInternetConnectionStatus fails.	RGBA32	Yes	None
wifi_none_icon	Icon displayed for wifi with signal strength 0.	RGBA32	Yes	None
wifi1_icon	Icon displayed for wifi with signal strength 1.	RGBA32	Yes	None
wifi2_icon	Icon displayed for wifi with signal strength 2.	RGBA32	Yes	None
wifi3_icon	Icon displayed for wifi with signal strength 3.	RGBA32	Yes	None
eth_icon	Icon displayed when connected to the Internet via Ethernet.	RGBA32	Yes	None
eth_none_icon	Icon displayed when using Ethernet, with no Internet connection.	RGBA32	Yes	None
background_image	Background image. Optional, not set with the defaults. See layout.backgroundImage.	RGB24	No	None

File Associations

File-association cfg files can optionally be loaded from SD "/config/nx-hbmenu/fileassoc/" during startup. There's 1 .cfg file for each app. During normal menu scanning, hbmenu will check for file_extensions/filenames from fileassoc cfg with the dir-list filename, when the file is not recognized otherwise (likewise for directories). This is processed in the same order that the cfg was loaded from SD / same order specified in the cfg file.

When processing directories where no NRO was detected, hbmenu will go through the dir-listing and use the first entry where the filename matches a fileassoc entry where filename is specified (file_extension entries are skipped).

The generated menu entry launches the specified app_path where the first passed argument (argv[1] in the launched app) is the absolute filepath for the associated file. See below regarding the icon used for the menu entry. The author and version fields for the menu entry are loaded from app_path, while the name is the filename (unless a directory is being processed, in this case the directory name is used). When {$FILEPATH with extension changed to .nacp} exists, the aforementioned strings will be loaded from there instead.

The only optional setting is icon_path and app_args. All paths are absolute. Icon will attempted to be loaded from the following: {$FILEPATH with extension changed to .jpg} -> icon_path setting if it exists (target setting -> main file_assoc setting) -> icon from app_path.

If you have targets where file_extension and filename both have the same extension, the filename target should be located before that file_extension target in the cfg. Targets which have both file_extension and filename settings are ignored. Each target must have either a file_extension or filename setting.

app_args specifies the args to pass following argv[0](app-path). This is an array of strings for each argv[N+1]. If a "%f" token is found (only one per array index is handled), it's replaced with the path for the fileassoc. If no "%f" token is specified or app_args is not specified, the fileassoc path is passed to argv[1].

Sample fileassoc file:

fileassoc={
  app_path="/switch/myapp/app.nro";
  icon_path="/switch/myapp/myicon.jpg";
  app_args = ["arg1", "arg2", "%f"];

  targets=(
    {
      file_extension=".ext3";
      icon_path="/switch/myapp/myicon2.jpg";
      app_args = ["arg1", "arg2", "--path=%f"]; // Optional, overrides fileassoc.app_args.
    },
    {
      file_extension=".ext4";
      icon_path="/switch/myapp/myicon3.jpg";
    },
    {
      filename="main.py";
      icon_path="/switch/myapp/myicon4.jpg";
    }
  );
};