Difference between revisions of "Grub2 theme / reference"

From Rosalab Wiki
Jump to: navigation, search
m (→‎Image file: fix typo)
 
(16 intermediate revisions by one other user not shown)
Line 2: Line 2:
 
<br>
 
<br>
 
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.<br>
 
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.<br>
−
After reading source code related to graphical decoration I added new option and fixed a bug. (Both patches were sent to the upstream and accepted.)<br>
+
After reading source code related to graphical decoration I added new option and fixed a bug. (Both patches were sent to the upstream.)<br>
 
This document accumulates all information about syntax of the Grub2 (2.00) themes.<br>
 
This document accumulates all information about syntax of the Grub2 (2.00) themes.<br>
  
Line 37: Line 37:
 
There are three ways to specify a numeric value:
 
There are three ways to specify a numeric value:
 
* Absolute value - in pixels (e.g. 340)
 
* Absolute value - in pixels (e.g. 340)
−
* Relative value - in percentages of screen width/height (e.g. 40%)
+
* 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)
+
* Combined value - combination of two previous types (e.g. 50%-120). No whitespaces are allowed.
 
<br>
 
<br>
 +
 
== String ==
 
== String ==
  
Line 55: Line 56:
 
== Image file ==
 
== 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/bakcground.png")<br>
+
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")<br>
 
<br>
 
<br>
  
Line 107: Line 108:
 
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.<br>
 
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.<br>
 
The components and their properties are defined in a plain text configuration file ''theme.txt''.<br>
 
The components and their properties are defined in a plain text configuration file ''theme.txt''.<br>
−
The main theme file has two types of statements:
+
The main theme file has three types of statements:
 +
* OPTION : VALUE
 
* OPTION = VALUE
 
* OPTION = VALUE
−
* + CONTAINER { ... }
+
* + COMPONENT { ... }
−
The first construction is a property declaration. Each property may be defined only once.<br>
+
The first construction is a global property declaration. Each property may be defined only once.<br>
−
The second construction starts with the "+" symbol followed by the container's type and list of options and/or other containers in braces.<br>
+
The second construction is a property declaration for some child container. Each property may be defined only once inside one container.<br>
 +
The third construction starts with the "+" symbol followed by the component's type and list of options and/or other components in braces.<br>
 
Line starting with "#" is a comment.<br>
 
Line starting with "#" is a comment.<br>
 
Both single-line and multi-line forms are acceptable:
 
Both single-line and multi-line forms are acceptable:
−
  + CONTAINER {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 }
  
−
  + CONTAINER {
+
  + COMPONENT {
 
     OPTION_1 = VALUE_1
 
     OPTION_1 = VALUE_1
 
     OPTION_2 = VALUE_2
 
     OPTION_2 = VALUE_2
Line 126: Line 129:
  
 
  color="127,127,0"
 
  color="127,127,0"
−
 
  
 
==<span id="common_options">Common options</span>==
 
==<span id="common_options">Common options</span>==
Line 221: Line 223:
 
|-
 
|-
 
| scrollbar_thumb || Image used for the scrollbar's thumb || Styled Box ||
 
| scrollbar_thumb || Image used for the scrollbar's thumb || Styled Box ||
−
|-
 
−
| theme_dir || Full path to a directory with needed pixmaps. By default set to the directory where ''theme.txt'' is placed || String ||
 
 
|}
 
|}
 
:<sup>'''<span id="boot_menu_star1">*</span>'''</sup> Developed by Vladimir Testov, ROSA. Added by patch. Sent to upstream.
 
:<sup>'''<span id="boot_menu_star1">*</span>'''</sup> Developed by Vladimir Testov, ROSA. Added by patch. Sent to upstream.
Line 251: Line 251:
 
|-
 
|-
 
| highlight_style || Foreground 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 ||
−
|-
 
−
| theme_dir || Full path to a directory with needed pixmaps. By default set to the directory where ''theme.txt'' is placed || String ||
 
 
|}
 
|}
 
:'''*''' id must be set to "__timeout__" for displaying of elapsed time
 
:'''*''' id must be set to "__timeout__" for displaying of elapsed time
Line 267: Line 265:
 
| num_ticks || Number of ticks for a full circle || Numeric || 64
 
| num_ticks || Number of ticks for a full circle || Numeric || 64
 
|-
 
|-
−
| start_angle || Position of first tick mark to disappear or appear || Numeric ||-64
+
| start_angle || Position of first tick mark to disappear or appear [[#start_angle_notify | '''**''']] || Numeric ||-64
 
|-
 
|-
−
| ticks_disappear <sup>'''[[#circular_progress_strange | ?]]'''</sup> || Sets whether ticks should appear or disappear. Set to ''false'' for ticks to appear or ''true'' for ticks to disappear || Boolean || NOT SPECIFIED!!!
+
| 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 ||
 
| 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 ||
 
| tick_bitmap || Image to use for the tick marks || Image file ||
−
|-
 
−
| theme_dir || Full path to a directory with needed pixmaps. By default set to the directory where ''theme.txt'' is placed || String ||
 
 
|}
 
|}
 
:'''*''' id must be set to "__timeout__" for displaying of elapsed time
 
:'''*''' id must be set to "__timeout__" for displaying of elapsed time
−
:<span id="circular_progress_strange"><sup>'''?'''</sup></span> Will be fixed?
+
:'''<span id="start_angle_notify">**</span>''' measured in "parrots". 1 "parrot" = 1 / 256 of full circle. So -64 "parrots" is equal to -90 degrees.
 
<br>
 
<br>
  
Line 296: Line 292:
 
| align || Horizontal alignment of the text. Possible values are ''left'', ''center'' or ''right'' || String || left
 
| align || Horizontal alignment of the text. Possible values are ''left'', ''center'' or ''right'' || String || left
 
|}
 
|}
−
:'''*''' id must be set to "__timeout__" for displaying of elapsed time
+
:'''*''' id must be set to "__timeout__" and text should be empty for displaying of elapsed time
−
:''N''s will be shown, where ''N'' is amount of elapsed time in seconds.
+
:Amount of elapsed time in seconds will be shown.
 
:'''<span id="label_modes">**</span>''' @KEYMAP_SHORT@ for "enter: boot, `e': options, `c': cmd-line"<br> @KEYMAP_MIDDLE@ for "Press enter to boot the selected OS, `e' to edit the commands before booting or `c' for a command-line."<br> @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."
 
:'''<span id="label_modes">**</span>''' @KEYMAP_SHORT@ for "enter: boot, `e': options, `c': cmd-line"<br> @KEYMAP_MIDDLE@ for "Press enter to boot the selected OS, `e' to edit the commands before booting or `c' for a command-line."<br> @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."
 
<br>
 
<br>
Line 309: Line 305:
 
| property || description || Data type || default
 
| property || description || Data type || default
 
|-
 
|-
−
| file || The image's filename || String ||
+
| file || The image's filename || Image file ||
−
|-
+
−
| theme_dir || Full path to a directory with the file. By default set to the directory where ''theme.txt'' is placed || String ||
+
 
|}
 
|}
 
<br>
 
<br>
Line 358: Line 352:
 
==LANG and LANGUAGE==
 
==LANG and LANGUAGE==
 
If you'd like to select Grub2 locale not equal to the system's locale, you should use these options.<br>
 
If you'd like to select Grub2 locale not equal to the system's locale, you should use these options.<br>
−
It is strongly recommended to use both of them at the same time with the same parameter.<br>
+
It is strongly recommended to use both of them at the same time with the same value.<br>
 
Syntax: LANG="xx_XX" and LANGUAGE="xx_XX", where
 
Syntax: LANG="xx_XX" and LANGUAGE="xx_XX", where
 
*xx_XX - selected language, e.g. en_US<br>
 
*xx_XX - selected language, e.g. en_US<br>
Line 413: Line 407:
 
|}
 
|}
 
<br><br>
 
<br><br>
−
Vladimir Testov, ROSA, 2012.
+
Vladimir Testov, ROSA, 2013.
 
[[en:Grub2 theme / reference]]
 
[[en:Grub2 theme / reference]]
 
[[ru:Тема Grub2 / синтаксис]]
 
[[ru:Тема Grub2 / синтаксис]]

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:

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.

Retrieved from "http://wiki.rosalab.com/en/index.php?title=Grub2_theme_/_reference&oldid=8805"