520 lines
25 KiB
Text
520 lines
25 KiB
Text
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 (*note loadfont::). To see
|
|
the list of loaded fonts, execute the "lsfonts" command (*note
|
|
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".
|
|
|