Difference between revisions of "Grub2 theme / reference"
(Created page with "<span style="font-size: 300%">'''Grub2 2.00'''</span> <br> I was given the task to implement a theme for Grub2 according to the designer's draft. First, I found documents and ...") |
|||
| Line 414: | Line 414: | ||
<br><br> | <br><br> | ||
Vladimir Testov, ROSA, 2012. | Vladimir Testov, ROSA, 2012. | ||
| + | [[en:Grub2 theme / reference]] | ||
| + | [[ru:Тема Grub2 / синтаксис]] | ||
Revision as of 08:57, 23 January 2013
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 and accepted.)
This document accumulates all information about syntax of the Grub2 (2.00) themes.
Contents
- 1 Data types
- 2 Key files for theming
- 3 Using themes
- 3.1 Main file syntax
- 3.2 Common options
- 3.3 Global options
- 3.4 Boot menu (boot_menu)
- 3.5 Horizontal indicator of elapsed time (progress_bar)
- 3.6 Circular indicator of elapsed time (circular_progress)
- 3.7 Text string (label)
- 3.8 Image file (image)
- 3.9 Vertical box (vbox)
- 3.10 Horizontal box (hbox)
- 3.11 Canvas (canvas)
- 4 Options from /etc/default/grub affecting theme
- 5 Appendix A. Console colors table.
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 screen width/height (e.g. 40%)
- Combined value - combination of two previous types (e.g. 50%-120)
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/bakcground.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
- /etc/default/grub
- /boot/grub2/custom.cfg
- /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 two types of statements:
- OPTION = VALUE
- + CONTAINER { ... }
The first construction is a property declaration. Each property may be defined only once.
The second construction starts with the "+" symbol followed by the container's type and list of options and/or other containers in braces.
Line starting with "#" is a comment.
Both single-line and multi-line forms are acceptable:
+ CONTAINER {OPTION_1 = VALUE_1 OPTION_2 = VALUE_2 ... OPTION_N = VALUE_N }
+ CONTAINER {
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 |
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 | |
| theme_dir | Full path to a directory with needed pixmaps. By default set to the directory where theme.txt is placed | String |
- 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 | |
| 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
- **@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 | NOT SPECIFIED!!! |
| 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 | |
| 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
- ? Will be fixed?
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__" for displaying of elapsed time
- Ns will be shown, where N is amount of elapsed time in seconds.
- ** @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 | String | |
| theme_dir | Full path to a directory with the file. By default set to the directory where theme.txt is placed | String |
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 parameter.
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.
| 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, 2012.
