grub: Theme file format
7 Theme file format
*******************
7.1 Introduction
================
The GRUB graphical menu supports themes that can customize the layout
and appearance of the GRUB boot menu. The theme is configured through a
plain text file that specifies the layout of the various GUI components
(including the boot menu, timeout progress bar, and text messages) as
well as the appearance using colors, fonts, and images. Example is
available in docs/example_theme.txt
7.2 Theme Elements
==================
7.2.1 Colors
------------
Colors can be specified in several ways:
* HTML-style "#RRGGBB" or "#RGB" format, where *R*, *G*, and *B* are
hexadecimal digits (e.g., "#8899FF")
* as comma-separated decimal RGB values (e.g., "128, 128, 255")
* with "SVG 1.0 color names" (e.g., "cornflowerblue") which must be
specified in lowercase.
7.2.2 Fonts
-----------
The fonts GRUB uses "PFF2 font format" bitmap fonts. Fonts are
specified with full font names. Currently there is no provision for a
preference list of fonts, or deriving one font from another. Fonts are
loaded with the "loadfont" command in GRUB (⇒loadfont). To see
the list of loaded fonts, execute the "lsfonts" command (⇒
lsfonts). If there are too many fonts to fit on screen, do "set
pager=1" before executing "lsfonts".
7.2.3 Progress Bar
------------------
Figure 7.1
Figure 7.2
Progress bars are used to display the remaining time before GRUB boots
the default menu entry. To create a progress bar that will display the
remaining time before automatic boot, simply create a "progress_bar"
component with the id "__timeout__". This indicates to GRUB that the
progress bar should be updated as time passes, and it should be made
invisible if the countdown to automatic boot is interrupted by the user.
Progress bars may optionally have text displayed on them. This text
is controlled by variable "text" which contains a printf template with
the only argument %d is the number of seconds remaining. Additionally
special values "@TIMEOUT_NOTIFICATION_SHORT@",
"@TIMEOUT_NOTIFICATION_MIDDLE@", "@TIMEOUT_NOTIFICATION_LONG@" are
replaced with standard and translated templates.
7.2.4 Circular Progress Indicator
---------------------------------
The circular progress indicator functions similarly to the progress bar.
When given an id of "__timeout__", GRUB updates the circular progress
indicator's value to indicate the time remaining. For the circular
progress indicator, there are two images used to render it: the *center*
image, and the *tick* image. The center image is rendered in the center
of the component, while the tick image is used to render each mark along
the circumference of the indicator.
7.2.5 Labels
------------
Text labels can be placed on the boot screen. The font, color, and
horizontal alignment can be specified for labels. If a label is given
the id "__timeout__", then the "text" property for that label is also
updated with a message informing the user of the number of seconds
remaining until automatic boot. This is useful in case you want the
text displayed somewhere else instead of directly on the progress bar.
7.2.6 Boot Menu
---------------
The boot menu where GRUB displays the menu entries from the "grub.cfg"
file. It is a list of items, where each item has a title and an
optional icon. The icon is selected based on the *classes* specified
for the menu entry. If there is a PNG file named "myclass.png" in the
"grub/themes/icons" directory, it will be displayed for items which have
the class *myclass*. The boot menu can be customized in several ways,
such as the font and color used for the menu entry title, and by
specifying styled boxes for the menu itself and for the selected item
highlight.
7.2.7 Styled Boxes
------------------
One of the most important features for customizing the layout is the use
of *styled boxes*. A styled box is composed of 9 rectangular (and
potentially empty) regions, which are used to seamlessly draw the styled
box on screen:
Northwest (nw) North (n) Northeast (ne)
West (w) Center (c) East (e)
Southwest (sw) South (s) Southeast (se)
To support any size of box on screen, the center slice and the slices
for the top, bottom, and sides are all scaled to the correct size for
the component on screen, using the following rules:
1. The edge slices (north, south, east, and west) are scaled in the
direction of the edge they are adjacent to. For instance, the west
slice is scaled vertically.
2. The corner slices (northwest, northeast, southeast, and southwest)
are not scaled.
3. The center slice is scaled to fill the remaining space in the
middle.
As an example of how an image might be sliced up, consider the styled
box used for a terminal view.
Figure 7.3
7.2.8 Creating Styled Box Images
--------------------------------
The Inkscape_ scalable vector graphics editor is a very useful tool for
creating styled box images. One process that works well for slicing a
drawing into the necessary image slices is:
1. Create or open the drawing you'd like use.
2. Create a new layer on the top of the layer stack. Make it visible.
Select this layer as the current layer.
3. Draw 9 rectangles on your drawing where you'd like the slices to
be. Clear the fill option, and set the stroke to 1 pixel wide
solid stroke. The corners of the slices must meet precisely; if it
is off by a single pixel, it will probably be evident when the
styled box is rendered in the GRUB menu. You should probably go to
File | Document Properties | Grids and enable a grid or create a
guide (click on one of the rulers next to the drawing and drag over
the drawing; release the mouse button to place the guide) to help
place the rectangles precisely.
4. Right click on the center slice rectangle and choose Object
Properties. Change the "Id" to "slice_c" and click Set. Repeat
this for the remaining 8 rectangles, giving them Id values of
"slice_n", "slice_ne", "slice_e", and so on according to the
location.
5. Save the drawing.
6. Select all the slice rectangles. With the slice layer selected,
you can simply press Ctrl+A to select all rectangles. The status
bar should indicate that 9 rectangles are selected.
7. Click the layer hide icon for the slice layer in the layer palette.
The rectangles will remain selected, even though they are hidden.
8. Choose File | Export Bitmap and check the *Batch export 9 selected
objects* box. Make sure that *Hide all except selected* is
unchecked. click *Export*. This will create PNG files in the same
directory as the drawing, named after the slices. These can now be
used for a styled box in a GRUB theme.
7.3 Theme File Manual
=====================
The theme file is a plain text file. Lines that begin with "#" are
ignored and considered comments. (Note: This may not be the case if the
previous line ended where a value was expected.)
The theme file contains two types of statements:
1. Global properties.
2. Component construction.
7.3.1 Global Properties
-----------------------
7.3.2 Format
------------
Global properties are specified with the simple format:
* name1: value1
* name2: "value which may contain spaces"
* name3: #88F
In this example, name3 is assigned a color value.
7.3.3 Global Property List
--------------------------
title-text Specifies the text to display at the top
center of the screen as a title.
title-font Defines the font used for the title
message at the top of the screen.
title-color Defines the color of the title message.
message-font Currently unused. Left for backward
compatibility.
message-color Currently unused. Left for backward
compatibility.
message-bg-color Currently unused. Left for backward
compatibility.
desktop-image Specifies the image to use as the
background. It will be scaled to fit the
screen size or proportionally scaled
depending on the scale method.
desktop-image-scale-methodSpecifies the scaling method for the
*desktop-image*. Options are "stretch",
"crop", "padding", "fitwidth",
"fitheight". "stretch" for fitting the
screen size. Otherwise it is
proportional scaling of a part of
*desktop-image* to the part of the
screen. "crop" part of the
*desktop-image* will be proportionally
scaled to fit the screen sizes.
"padding" the entire *desktop-image* will
be contained on the screen. "fitwidth"
for fitting the *desktop-image*'s width
with screen width. "fitheight" for
fitting the *desktop-image*'s height with
the screen height. Default is "stretch".
desktop-image-h-align Specifies the horizontal alignment of the
*desktop-image* if
*desktop-image-scale-method* isn't equeal
to "stretch". Options are "left",
"center", "right". Default is "center".
desktop-image-v-align Specifies the vertical alignment of the
*desktop-image* if
*desktop-image-scale-method* isn't equeal
to "stretch". Options are "top",
"center", "bottom". Default is "center".
desktop-color Specifies the color for the background if
*desktop-image* is not specified.
terminal-box Specifies the file name pattern for the
styled box slices used for the command
line terminal window. For example,
"terminal-box: terminal_*.png" will use
the images "terminal_c.png" as the center
area, "terminal_n.png" as the north (top)
edge, "terminal_nw.png" as the northwest
(upper left) corner, and so on. If the
image for any slice is not found, it will
simply be left empty.
terminal-border Specifies the border width of the
terminal window.
terminal-left Specifies the left coordinate of the
terminal window.
terminal-top Specifies the top coordinate of the
terminal window.
terminal-width Specifies the width of the terminal
window.
terminal-height Specifies the height of the terminal
window.
7.3.4 Component Construction
----------------------------
Greater customizability comes is provided by components. A tree of
components forms the user interface. *Containers* are components that
can contain other components, and there is always a single root
component which is an instance of a *canvas* container.
Components are created in the theme file by prefixing the type of
component with a '+' sign:
' + label { text="GRUB" font="aqui 11" color="#8FF" } '
properties of a component are specified as "name = value" (whitespace
surrounding tokens is optional and is ignored) where *value* may be:
* a single word (e.g., "align = center", "color = #FF8080"),
* a quoted string (e.g., "text = "Hello, World!""), or
* a tuple (e.g., "preferred_size = (120, 80)").
7.3.5 Component List
--------------------
The following is a list of the components and the properties they
support.
* label A label displays a line of text.
Properties:
id Set to "__timeout__" to display the time elapsed
to an automatical boot of the default entry.
text The text to display. If "id" is set to
"__timeout__" and no "text" property is set then
the amount of seconds will be shown. If set to
"@KEYMAP_SHORT@", "@KEYMAP_MIDDLE@" or
"@KEYMAP_LONG@" then predefined hotkey
information will be shown.
font The font to use for text display.
color The color of the text.
align The horizontal alignment of the text within the
component. Options are "left", "center" and
"right".
visible Set to "false" to hide the label.
* image A component that displays an image. The image is scaled to
fit the component.
Properties:
file The full path to the image file to load.
* progress_bar Displays a horizontally oriented progress bar. It can
be rendered using simple solid filled rectangles, or using a pair
of pixmap styled boxes.
Properties:
id Set to "__timeout__" to display the time elapsed
to an automatical boot of the default entry.
fg_color The foreground color for plain solid color
rendering.
bg_color The background color for plain solid color
rendering.
border_color The border color for plain solid color
rendering.
text_color The text color.
bar_style The styled box specification for the frame of
the progress bar. Example:
"progress_frame_*.png" If the value is equal to
"highlight_style" then no styled boxes will be
shown.
highlight_styleThe styled box specification for the highlighted
region of the progress bar. This box will be
used to paint just the highlighted region of the
bar, and will be increased in size as the bar
nears completion. Example: "progress_hl_*.png".
If the value is equal to "bar_style" then no
styled boxes will be shown.
highlight_overlayIf this option is set to "true" then the
highlight box side slices (every slice except
the center slice) will overlay the frame box
side slices. And the center slice of the
highlight box can move all the way (from top to
bottom), being drawn on the center slice of the
frame box. That way we can make a progress bar
with round-shaped edges so there won't be a free
space from the highlight to the frame in top and
bottom scrollbar positions. Default is "false".
font The font to use for progress bar.
text The text to display on the progress bar. If the
progress bar's ID is set to "__timeout__" and
the value of this property is set to
"@TIMEOUT_NOTIFICATION_SHORT@",
"@TIMEOUT_NOTIFICATION_MIDDLE@" or
"@TIMEOUT_NOTIFICATION_LONG@", then GRUB will
update this property with an informative message
as the timeout approaches.
* circular_progress Displays a circular progress indicator. The
appearance of this component is determined by two images: the
*center* image and the *tick* image. The center image is generally
larger and will be drawn in the center of the component. Around
the circumference of a circle within the component, the tick image
will be drawn a certain number of times, depending on the
properties of the component.
Properties:
id Set to "__timeout__" to display the time
elapsed to an automatical boot of the
default entry.
center_bitmap The file name of the image to draw in the
center of the component.
tick_bitmap The file name of the image to draw for
the tick marks.
num_ticks The number of ticks that make up a full
circle.
ticks_disappear Boolean value indicating whether tick
marks should progressively appear, or
progressively disappear as *value*
approaches *end*. Specify "true" or
"false". Default is "false".
start_angle The position of the first tick mark to
appear or disappear. Measured in
"parrots", 1 "parrot" = 1 / 256 of the
full circle. Use values "xxx deg" or
"xxx \xc2\xb0" to set the angle in
degrees.
* boot_menu Displays the GRUB boot menu. It allows selecting items
and executing them.
Properties:
item_font The font to use for the menu item
titles.
selected_item_font The font to use for the selected
menu item, or "inherit" (the
default) to use "item_font" for
the selected menu item as well.
item_color The color to use for the menu item
titles.
selected_item_color The color to use for the selected
menu item, or "inherit" (the
default) to use "item_color" for
the selected menu item as well.
icon_width The width of menu item icons.
Icons are scaled to the specified
size.
icon_height The height of menu item icons.
item_height The height of each menu item in
pixels.
item_padding The amount of space in pixels to
leave on each side of the menu
item contents.
item_icon_space The space between an item's icon
and the title text, in pixels.
item_spacing The amount of space to leave
between menu items, in pixels.
menu_pixmap_style The image file pattern for the
menu frame styled box. Example:
"menu_*.png" (this will use images
such as "menu_c.png",
"menu_w.png", 'menu_nw.png", etc.)
item_pixmap_style The image file pattern for the
item styled box.
selected_item_pixmap_style The image file pattern for the
selected item highlight styled
box.
scrollbar Boolean value indicating whether
the scroll bar should be drawn if
the frame and thumb styled boxes
are configured.
scrollbar_frame The image file pattern for the
entire scroll bar. Example:
"scrollbar_*.png"
scrollbar_thumb The image file pattern for the
scroll bar thumb (the part of the
scroll bar that moves as scrolling
occurs). Example:
"scrollbar_thumb_*.png"
scrollbar_thumb_overlay If this option is set to "true"
then the scrollbar thumb side
slices (every slice except the
center slice) will overlay the
scrollbar frame side slices. And
the center slice of the
scrollbar_thumb can move all the
way (from top to bottom), being
drawn on the center slice of the
scrollbar frame. That way we can
make a scrollbar with round-shaped
edges so there won't be a free
space from the thumb to the frame
in top and bottom scrollbar
positions. Default is "false".
scrollbar_slice The menu frame styled box's slice
in which the scrollbar will be
drawn. Possible values are
"west", "center", "east"
(default). "west" - the scrollbar
will be drawn in the west slice
(right-aligned). "east" - the
scrollbar will be drawn in the
east slice (left-aligned).
"center" - the scrollbar will be
drawn in the center slice. Note:
in case of "center" slice: a) If
the scrollbar should be drawn then
boot menu entry's width is
decreased by the scrollbar's width
and the scrollbar is drawn at the
right side of the center slice.
b) If the scrollbar won't be drawn
then the boot menu entry's width
is the width of the center slice.
c) We don't necessary need the
menu pixmap box to display the
scrollbar.
scrollbar_left_pad The left scrollbar padding in
pixels. Unused if
"scrollbar_slice" is "west".
scrollbar_right_pad The right scrollbar padding in
pixels. Unused if
"scrollbar_slice" is "east".
scrollbar_top_pad The top scrollbar padding in
pixels.
scrollbar_bottom_pad The bottom scrollbar padding in
pixels.
visible Set to "false" to hide the boot
menu.
* canvas Canvas is a container that allows manual placement of
components within it. It does not alter the positions of its child
components. It assigns all child components their preferred sizes.
* hbox The *hbox* container lays out its children from left to right,
giving each one its preferred width. The height of each child is
set to the maximum of the preferred heights of all children.
* vbox The *vbox* container lays out its children from top to bottom,
giving each one its preferred height. The width of each child is
set to the maximum of the preferred widths of all children.
7.3.6 Common properties
-----------------------
The following properties are supported by all components:
'left'
The distance from the left border of container to left border of
the object in either of three formats:
x Value in pixels
p% Percentage
p%+x mixture of both
'top'
The distance from the left border of container to left border of
the object in same format.
'width'
The width of object in same format.
'height'
The height of object in same format.
'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__" Component with this ID will be updated by GRUB
and will indicate time elapsed to an automatical
boot of the default entry. Affected components:
"label", "circular_progress", "progress_bar".
Info Catalog
grub: Configuration
grub: Top
grub: Network