Grub2 2.00
I was given the task to implement a theme for Grub2 according to the designer's draft. First, I found documents and manuals about Grub2 graphical decoration. It happened that everything I've found was incomplete, obsolete and partly wrong.
After reading source code related to graphical decoration I added new option and fixed a bug. (Both patches were sent to the upstream.)
This document accumulates all information about syntax of the Grub2 (2.00) themes.
Console colors can be set in /boot/grub2/custom.cfg
File syntax:
color_normal=text-color/bg-color menu_color_normal=text-color/bg-color menu_color_highlight=text-color/bg-color
where "text-color" and "bg-color" - text color and background color from set of colors.
Please, note that "black" background color is treated as transparent. Also, if global option for terminal background (GRUB_BACKGROUND) is not set the background will be black.
There are three ways to specify a color value in theme.txt:
Grub2 uses PFF2 font format. grub-mkfont utility should be used to convert BDF, PCF or TTF fonts to PFF2 format. Output file should have pf2 extension and should be placed to the theme directory. (/boot/grub2/themes/rosa/)
In the theme.txt file full font name and size should be used. (e.g. "Droid Sans Mono Regular 11")
Coordinates and lengths are specified using numeric format.
There are three ways to specify a numeric value:
A string is a sequence of characters enclosed in double-quotes, e.g.:
A boolean value can be:
An absolute path to a valid image file. Allowed formats are: PNG, TGA, JPG; transparency is supported. (e.g., "/boot/grub2/themes/rosa/background.png")
A styled box contains 9 rectangular regions (or slices) that are used for drawing an image on the screen:
Northwest Slice (nw) |
North Slice (n) |
Northeast Slice (ne) |
West Slice (w) |
Center Slice (c) |
East Slice (e) |
Southwest Slice (sw) |
South Slice (s) |
Southeast Slice (se) |
The slice's name is shown in brackets. The slices must be named according to format NAME_PART.EXT, where
So, the filename for our example (South-west region of the "example" element) will be "example_sw.png".
The center slice is scaled to fit the element's height and width. Other slices form the border around the center slice.
The following table shows how the slices are scaled:
not scaled | ↔ | not scaled |
↕ | horizontally and vertically | ↕ |
not scaled | ↔ | not scaled |
Any missing slice is left empty.
Files with slices should be placed in the theme directory.
Naming of graphical elements in theme.txt should look like "example_*.png" (or "NAME_*.EXT" in general case)
GRUB's graphical menu can be customized by using themes.
Create an empty directory in /boot/grub2/themes/ (e.g. "example/"), in this directory then create a new file named theme.txt and specify the full path to it in /etc/default/grub:
GRUB_THEME="/boot/grub2/themes/example/theme.txt"
After saving changes in /etc/default/grub you should run update-grub2.
A Grub2 theme can include various components such as images, labels, various styled boxes and progress indicators. There is one special type of component referred to as container. This special component is used as a container for other components. The root element is an instance of a canvas container component. A container component can also hold other containers.
The components and their properties are defined in a plain text configuration file theme.txt.
The main theme file has three types of statements:
The first construction is a global property declaration. Each property may be defined only once.
The second construction is a property declaration for some child container. Each property may be defined only once inside one container.
The third construction starts with the "+" symbol followed by the component's type and list of options and/or other components in braces.
Line starting with "#" is a comment.
Both single-line and multi-line forms are acceptable:
+ COMPONENT {OPTION_1 = VALUE_1 OPTION_2 = VALUE_2 ... OPTION_N = VALUE_N }
+ COMPONENT { OPTION_1 = VALUE_1 OPTION_2 = VALUE_2 ... OPTION_N = VALUE_N }
Spaces are ignored. So the following entries mean the same:
color = "127, 127, 0"
color="127,127,0"
These options are applicable to any element. (if not declared otherwise)
Coordinates origin is a left corner of the display, as always.
property | description | Data type | default |
left | The left position of the element | Numeric | |
top | The top position of the element | Numeric | |
width | The element's width | Numeric | |
height | The element's height | Numeric | |
id | Identifier for the element | String |
id The identifier for the component. This can be any arbitrary string. The ID can be used by scripts to refer to various components in the GUI component tree. Currently, there is one special ID value that GRUB recognizes:
Global properties are described in root entry of theme.txt
This entry is an instance of canvas with additional options:
property | description | Data type | default |
title-text | A title for the menu | String | GRUB Boot Menu |
title-font | Font used for the title text | Font name | Unknown Regular 16 |
title-color | Color of the title text | Color value | black |
message-font | Font used for GRUB messages | Font name | Unknown Regular 16 |
message-color | Color used for GRUB messages | Color value | white |
message-bg-color | Background color for GRUB messages | Color value | black |
desktop-image | Background image for the menu | Image file | |
desktop-color | Color of the background if a background image is not specified |
Color value | white |
terminal-box | Image used for the terminal box | Styled Box | Plain black box |
terminal-font | Font used for the terminal box | Font name | Fixed 10 |
The boot_menu component sets the visual style of the boot menu. This component must be included in the theme definition file.
The boot_menu have all common options and additionally:
property | description | Data type | default |
visible | Show or hide the boot menu | Boolean | true |
menu_pixmap_style | Styled box for the menu background | Styled Box | |
item_font | Font used for the menu items | Font name | Unknown Regular 16 |
item_color | Color of the menu items | Color value | black |
item_pixmap_style * | Image used to display the inactive items | Styled Box | |
selected_item_font | Font used for the selected menu item. Valid values are any font name or inherit. When set to inherit, it uses the same font set by the item_font property | Font name | inherit |
selected_item_color | Color of the selected menu item. Valid values are any color value or inherit. When set to inherit, it uses the same color set by the item_color property | Color value | inherit |
selected_item_pixmap_style | Image used to highlight the selected item | Styled Box | |
item_height | Height of each menu item | Numeric | 42 |
item_padding | Amount of space to leave on either side of the menu items | Numeric | 14 |
item_spacing | Amount of space between menu items | Numeric | 16 |
icon_width | Width of the menu item icons | Numeric | 32 |
icon_height | Height of the menu item icons | Numeric | 32 |
item_icon_space | Space to leave between a menu item's icon and it's text | Numeric | 4 |
scrollbar | Show or hide the scrollbar | Boolean | true |
scrollbar_width | Width of the scrollbar | Numeric | 16 |
scrollbar_frame | Image used for the scrollbar's frame | Styled Box | |
scrollbar_thumb | Image used for the scrollbar's thumb | Styled Box |
Displays a solid color or styled horizontal progress indicator that gives a graphical indication of the time remaining until the highlighted menu item is booted.
progress_bar have all common options and additionally:
property | description | Data type | default |
visible | Show or hide the progress bar | Boolean | true |
bg_color | Background color for a solid color progress bar | Color value | "128, 128, 128" |
fg_color | Foreground color for a solid color progress bar | Color value | "200, 200, 200" |
border_color | Border color for a solid color progress bar | Color value | black |
text | Text to show on the progress bar. Possible values are: @TIMEOUT_NOTIFICATION_SHORT@ @TIMEOUT_NOTIFICATION_MIDDLE@ @TIMEOUT_NOTIFICATION_LONG@, or any valid string ** |
String | |
text_color | Color of the text | Color value | black |
font | Font used for the text | Font name | Unknown Regular 16 |
bar_style | Background image for the styled progress bar. If this is not specified, a solid color progress bar is displayed | Styled box | |
highlight_style | Foreground image for the styled progress bar. If this is not specified, a solid color progress bar is displayed | Styled box |
Displays a circular progress indicator that gives a graphical indication of the time remaining until the highlighted menu item is booted.
circular_progress have all common options and additionally:
property | description | Data type | default |
num_ticks | Number of ticks for a full circle | Numeric | 64 |
start_angle | Position of first tick mark to disappear or appear ** | Numeric | -64 |
ticks_disappear | Sets whether ticks should appear or disappear. Set to false for ticks to appear or true for ticks to disappear | Boolean | False |
center_bitmap | Image to show at the center of the progress bar | Image file | |
tick_bitmap | Image to use for the tick marks | Image file |
The label component displays a single line of text on the screen.
label have all common options and additionally:
property | description | Data type | default |
text | Text to display. Possible values are: @KEYMAP_SHORT@ @KEYMAP_MIDDLE@ @KEYMAP_LONG@, or any valid string ** |
String | |
font | Font used for the text | Font name | Unknown Regular 16 |
color | Color of the text | Color value | black |
align | Horizontal alignment of the text. Possible values are left, center or right | String | left |
The image component displays an image on the screen. The image is scaled to fit the size specified by
the width and height properties.
image have all common options and additionally:
property | description | Data type | default |
file | The image's filename | Image file |
The vbox component is a container component which lays out other components within it vertically
starting at the top. It sets the width of each component to the width of the widest component. The
components retain their respective height.
vbox have all common options except width and height which are ignored.
The hbox component is a container component which lays out other components within it horizontally
starting from the left. It sets the height of each component to the height of the tallest component. The
components retain their respective width.
hbox have all common options except width and height which are ignored.
The canvas component is a container component which allows for the placement of other components
within it according to their individual positions and sizes. Unlike the vbox and hbox components, it
does not change the components sizes.
canvas have all common options.
There are some options in /etc/default/grub which interconnected with Grub2 theme. Options are set like OPTION=value, from the beginning, without spaces. Stings started with # are comments.
Sets screen resolution of Grub2 and plymoth.
Syntax: GRUB_GFXMODE=WIDTHxHEIGHT, where
E.g.
GRUB_GFXMODE=1024x768
Full path to main theme file should be set in this option.
Syntax: GRUB_THEME="FULL_PATH", where
E.g.
GRUB_THEME="/boot/grub2/themes/rosa/theme.txt"
If you'd like to select Grub2 locale not equal to the system's locale, you should use these options.
It is strongly recommended to use both of them at the same time with the same value.
Syntax: LANG="xx_XX" and LANGUAGE="xx_XX", where
E.g.
LANG=en_US LANGUAGE=en_US
To set Grub2 console's background (not transparent, in PNG, JPG or TGA format), you should set the full path to the image file in this option.
Syntax: GRUB_BACKGROUND="FULL_PATH", where
E.g.
GRUB_BACKGROUND="/boot/grub2/themes/rosa/terminal_background.png"
symbole | color's name | value |
0 | black | #000000 |
1 | blue | #0000a8 |
2 | green | #00a800 |
3 | cyan | #00a8a8 |
4 | red | #a80000 |
5 | magenta | #a800a8 |
6 | brown | #a85400 |
7 | light-gray | #a8a8a8 |
8 | dark-gray | #545454 |
9 | light-blue | #5454fe |
A | light-green | #54fe54 |
B | light-cyan | #54fefe |
C | light-red | #fe5454 |
D | light-magenta | #fe54fe |
E | yellow | #fefe54 |
F | white | #fefefe |
Vladimir Testov, ROSA, 2013.