Latest revision as of 10:35, 15 November 2015

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:

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:

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.

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:

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:

^* 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:

* 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:

* 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:

* 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:

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.

Vladimir Testov, ROSA, 2013.