Ventoy Theme Plugin

What do you feel when you first see Ventoy ? Not so pretty right? Now you can customize your own theme!
Ventoy is based on grub2, so all grub2 themes can be used on Ventoy.
This website collects many beautiful grub themes GRUB Themes - Gnome-look.org

  • Json Configuration

Recommend to use VentoyPlugson, a GUI ventoy.json configurator. Refer VentoyPlugson
A theme object is defined to describe the theme configuration in /ventoy/ventoy.json.
It should be noted that, you don't need to configure every option, you can also configure only some or one of them.

{
    "theme": {
        "file": "/ventoy/theme/blur/theme.txt",
        "gfxmode": "1920x1080",
        "display_mode": "GUI",
        "serial_param": "--unit=0 --speed=9600",
        "ventoy_left": "5%",
        "ventoy_top": "95%",
        "ventoy_color": "#0000ff",
        "fonts": [
            "/ventoy/theme/blur/Hack-12.pf2",
            "/ventoy/theme/blur/Hack-14.pf2",
            "/ventoy/theme/blur/Hack-16.pf2"
        ]
    }
}

Key Type Description
file STRING/STRING ARRAY The theme.txt file path. It can be a single string or a string array. For example:
"file": [
    "/ventoy/theme1/theme.txt",
    "/ventoy/theme2/theme.txt",
    "/ventoy/theme3/theme.txt",
    "/ventoy/theme4/theme.txt"
]
When you use a string array, you can use default_file option to select which one to use when boot.
Besides, with latest Ventoy release you can switch between these themes after boot. Refer: Switch between Themes
default_file INTEGER This option only take effect when file is a string array. It's an integer with default value 0. Meanings as follows:
0: randomly select a theme when boot. (This is the default value)
1: Select the 1st theme when boot.
2: Select the 2nd theme when boot.
3: Select the 3rd theme when boot.
......
resolution_fit INTEGER This option will only take effect when file contains more than one files and default_file is 0.
0: Not filter. (This is the default value)
1: Filter.
For more details about the option, please refer the following About resolution_fit
gfxmode STRING Optional, the gfxmode for grub2, default is "1024x768".
You can also use "max" to automatically choose the maximum resolution when boot.
display_mode STRING Optional, the menu display mode, GUI CLI serial serial_console default is GUI
"GUI" or "CLI" corresponding to the GUI mode and TEXT mode respectively. On very few machines Ventoy's menu can't be shown or the cursor moves extremely slow. In this case you can set the default mode to "CLI".
However, both "GUI" and "CLI" need a VGA device, if your machine only has serial, you can use serial
Also you can use serial_console if you have both serial and VGA device.
Attention: Unicode characters will NOT be displayed normally in CLI or serial mode.
serial_param STRING Optional, will be used only if display_mode is set to serial or serial_console
This parameter is used to set the serial(e.g. port speed), --unit=0 corresponding to COM1, --unit=1 corresponding to COM2 ...... https://www.gnu.org/software/grub/manual/grub/grub.html#serial
ventoy_left STRING Optional, left position of the ventoy version info, default is "5%"
ventoy_top STRING Optional, top position of the ventoy version info, default is "95%"
ventoy_color STRING Optional, the color of the ventoy version info, default is "#0000ff"
fonts STRING ARRAY Optional, each item is a full path of the font file to be loaded
  • TEXT mode <==> GUI mode

Ventoy will use GUI mode by default. But it may have some problems in some special machine with GUI mode. In this case you need to switch to TEXT mode.
Both text mode and GUI mode provide the same features, only that the GUI mode is more beautiful. You can use the following methods to switch display mode:

  1. F5 Tools-->Screen Display Mode-->Force Text Mode menu. This is one-time effective and needs to be set every time you boot into Ventoy.
  2. Press F7. This is the same as F5 menu above. Press F7 repeatedly to switch back and forth between text mode and GUI mode.
  3. With theme plugin in this article, you can set text mode as Ventoy's default display mode.

  • Switch between Themes (1.0.62+)

If you set more than one themes, you can swith between them with F5 Tools --> Theme Select menu as follows (effective immediately):
It should be noted that, the theme selected by this menu is temporary and will not be saved. So next boot Ventoy sill select a theme depend on default_file option.




  • About resolution_fit (1.0.86+)

It's well known that the display effect of background pictures, icons, text, etc. in the theme has a lot to do with the resolution.
One theme may look beautiful in one resolution but look ugly in another resolution.
As shown in the above picture, Ventoy supports more than one themes, and you can switch between these themes with F5 Tools --> Theme Select menu after boot.
So we can set different themes for different resolutions. For example:

"file": [
    "/ventoy/themes/theme_800x600/theme.txt",
    "/ventoy/themes/theme_1024x768/theme.txt",
    "/ventoy/themes/theme_1600x900/theme.txt"
]

Furthermore, we can set more than one themes for each resolution. For example:

"file": [
    "/ventoy/themes/theme_800x600_1/theme.txt",
    "/ventoy/themes/theme_800x600_2/theme.txt",
    "/ventoy/themes/theme_800x600_3/theme.txt",
    "/ventoy/themes/theme_1024x768_1/theme.txt",
    "/ventoy/themes/theme_1024x768_2/theme.txt",
    "/ventoy/themes/theme_1024x768_3/theme.txt",
    "/ventoy/themes/theme_1600x900_1/theme.txt",
    "/ventoy/themes/theme_1600x900_2/theme.txt",
    "/ventoy/themes/theme_1600x900_3/theme.txt"
]

If we set the default resolution to 1600x900, then we can choose for example /ventoy/themes/theme_1600x900_1/theme.txt as the default theme (that is set default_file to 7).
So far everything looks perfect, isn't it ?
However, there is a prerequisite here that we may not realize. That is we think that the machine always supports the resolution we set.
But for some special machines they may not support the resolution we set. They will choose another resolution when boot. Alough we can choose the appropriate theme according to the current resolution after boot. But this is a manual operation after all, can we automatically select a theme according to the resolution when boot ? This is just the original intention of the resolution_fit option.

You must set more than one themes, and default_file must set to 0, or resolution_fit option will not take effect.
Then when boot, instead of randomly selecting among all theme files as before, Ventoy will filter out those theme files that match the current resolution and randomly select one of them. Of course, if there is only one theme after filter, then it will always be used. So you can set as follows:

{
    "theme": {
        "file": [
            "/ventoy/themes/theme_800x600/theme.txt",
            "/ventoy/themes/theme_1024x768/theme.txt",
            "/ventoy/themes/theme_1600x900/theme.txt"
        ],        
        "resolution_fit": 1
    }
}

Then Ventoy will choose the appropriate theme according to the resolution when boot.
How does Ventoy filter out themes according to the resolution ?
Ventoy will check that whether the full path of the theme file contains AAAxBBB string. (x must be lowercase)
For example, for resolution 1600x900, the full path of the theme file must contain string "1600x900"
The string can be included in some directory name, for example /ventoy/themes/theme_1600x900/theme.txt or
The string can also be included in the file name, for example /ventoy/themes/themeA/theme_1600x900.txt

Besides, if resolution_fit option takes effect, when you change current resolution with F5 Tools --> Resolution Configuration menu, Ventoy will immediately select a new theme which matches the new resolution.

  • Hotkey Tips

Add these following hbox definitions to your new theme.txt to show the hotkey tips. You can also change the position and color.

+ hbox{ 
    left = 30%
    top = 95%
    width = 10%
    height = 25
    + label {text = "@VTOY_HOTKEY_TIP@" color = "blue" align = "left"} 
}

+ hbox{ 
    left = 90%
    top = 5 
    width = 10%
    height = 25
    + label {text = "@VTOY_MEM_DISK@" color = "red" align = "left"} 
}

  • Ventoy version info

By default there will be a version info string at the lower left corner. For example 1.0.10 UEFI www.ventoy.net
This info is hard coded in the source. You can use ventoy_left/ventoy_top/ventoy_color to change its position and color.
If you want to remove it completely, I encourage you to read the source code, modify it and rebuild Ventoy. I think this is also the essence of open source.


  • Multi-Mode

Supported. You can set different themes for different BIOS mode. Please refer Multi-Mode Option for details.


  • Sample Theme

https://gbatemp.net/threads/medicat-usb-a-multiboot-linux-usb-for-pc-repair.361577/