Grub2 theme / reference

What links here (1) →

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.

Data types

Console colors

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.

• color_normal - text color in console
  
• menu_color_normal - color of inactive entries and border of menu (in cases when graphical theme can not load, e.g. corrupt theme.txt file).
  
• menu_color_highlight - color of selected entry

Theme colors

There are three ways to specify a color value in theme.txt:

• HTML-style - "#RRGGBB" or "#RGB", where R, G, B are hexadecimal values (e.g. "#D4E0EC")
• Comma separated decimal RGB values. e.g. "(127,127,255)"
• SVG 1.0 color names. e.g. cornflowerblue. Written in lowercase.

Font name

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")

Numeric

Coordinates and lengths are specified using numeric format.
There are three ways to specify a numeric value:

• Absolute value - in pixels (e.g. 340)
• Relative value - in percentages of parent container's width/height (or screen if parent is root element) (e.g. 40%)
• Combined value - combination of two previous types (e.g. 50%-120). No whitespaces are allowed.

String

A string is a sequence of characters enclosed in double-quotes, e.g.:

"Edit entry"

Boolean

A boolean value can be:

• true
• false.

Image file

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")

Styled box

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

• NAME - the name of graphical element, the same for all parts of one element ("example")
• PART - slice's name ("sw")
• EXT - extension ("png")

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)

Key files for theming

1. /etc/default/grub
2. /boot/grub2/custom.cfg
3. /boot/grub2/themes/rosa/theme.txt

Using themes

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.

Main file syntax

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:

• OPTION : VALUE
• OPTION = VALUE
• + COMPONENT { ... }

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"

Common options

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:

__timeout__ Currently, this id has special meaning in progress_bar, circular_progress, label elements.

Global options

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

Boot menu (boot_menu)

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

^* Developed by Vladimir Testov, ROSA. Added by patch. Sent to upstream.

Horizontal indicator of elapsed time (progress_bar)

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

* id must be set to "__timeout__" for displaying of elapsed time

**@TIMEOUT_NOTIFICATION_SHORT@ for "Ns"
@TIMEOUT_NOTIFICATION_MIDDLE@ for "Ns remaining."
@TIMEOUT_NOTIFICATION_LONG@ for "The highlighted entry will be executed automatically in Ns."
where N is elapsed time in seconds.

Circular indicator of elapsed time (circular_progress)

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

* id must be set to "__timeout__" for displaying of elapsed time

** measured in "parrots". 1 "parrot" = 1 / 256 of full circle. So -64 "parrots" is equal to -90 degrees.

Text string (label)

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

* id must be set to "__timeout__" and text should be empty for displaying of elapsed time

Amount of elapsed time in seconds will be shown.

** @KEYMAP_SHORT@ for "enter: boot, `e': options, `c': cmd-line"
@KEYMAP_MIDDLE@ for "Press enter to boot the selected OS, `e' to edit the commands before booting or `c' for a command-line."
@KEYMAP_LONG@ for "Press enter to boot the selected OS, `e' to edit the commands before booting or `c' for a command-line. ESC to return previous menu."

Image file (image)

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

Vertical box (vbox)

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.

Horizontal box (hbox)

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.

Canvas (canvas)

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.

Options from /etc/default/grub affecting theme

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.

GRUB_GFXMODE

Sets screen resolution of Grub2 and plymoth.
Syntax: GRUB_GFXMODE=WIDTHxHEIGHT, where

• WIDTH - screen width
• HEIGHT - screen height

E.g.

GRUB_GFXMODE=1024x768

GRUB_THEME

Full path to main theme file should be set in this option.
Syntax: GRUB_THEME="FULL_PATH", where

• FULL_PATH - is a full path to file theme.txt of the selected theme.

E.g.

GRUB_THEME="/boot/grub2/themes/rosa/theme.txt"

LANG and LANGUAGE

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

• xx_XX - selected language, e.g. en_US
  

E.g.

LANG=en_US
LANGUAGE=en_US

GRUB_BACKGROUND

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

• FULL_PATH - full path to the image file

E.g.

GRUB_BACKGROUND="/boot/grub2/themes/rosa/terminal_background.png"

Appendix A. Console colors table.

Console colors

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.