Next: , Previous: , Up: GNU GRUB manual   [Contents][Index]


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-textSpecifies the text to display at the top center of the screen as a title.
title-fontDefines the font used for the title message at the top of the screen.
title-colorDefines the color of the title message.
message-fontCurrently unused. Left for backward compatibility.
message-colorCurrently unused. Left for backward compatibility.
message-bg-colorCurrently unused. Left for backward compatibility.
desktop-imageSpecifies 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-alignSpecifies 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-alignSpecifies 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-colorSpecifies the color for the background if *desktop-image* is not specified.
terminal-boxSpecifies 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-borderSpecifies the border width of the terminal window.
terminal-leftSpecifies the left coordinate of the terminal window.
terminal-topSpecifies the top coordinate of the terminal window.
terminal-widthSpecifies the width of the terminal window.
terminal-heightSpecifies 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:

    idSet to “__timeout__“ to display the time elapsed to an automatical boot of the default entry.
    textThe 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.
    fontThe font to use for text display.
    colorThe color of the text.
    alignThe horizontal alignment of the text within the component. Options are “left“, “center“ and “right“.
    visibleSet to “false“ to hide the label.
  • image A component that displays an image. The image is scaled to fit the component.

    Properties:

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

    idSet to “__timeout__“ to display the time elapsed to an automatical boot of the default entry.
    fg_colorThe foreground color for plain solid color rendering.
    bg_colorThe background color for plain solid color rendering.
    border_colorThe border color for plain solid color rendering.
    text_colorThe text color.
    bar_styleThe 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“.
    fontThe font to use for progress bar.
    textThe 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:

    idSet to “__timeout__“ to display the time elapsed to an automatical boot of the default entry.
    center_bitmapThe file name of the image to draw in the center of the component.
    tick_bitmapThe file name of the image to draw for the tick marks.
    num_ticksThe number of ticks that make up a full circle.
    ticks_disappearBoolean value indicating whether tick marks should progressively appear, or progressively disappear as *value* approaches *end*. Specify “true“ or “false“. Default is “false“.
    start_angleThe 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_fontThe font to use for the menu item titles.
    selected_item_fontThe font to use for the selected menu item, or “inherit“ (the default) to use “item_font“ for the selected menu item as well.
    item_colorThe color to use for the menu item titles.
    selected_item_colorThe color to use for the selected menu item, or “inherit“ (the default) to use “item_color“ for the selected menu item as well.
    icon_widthThe width of menu item icons. Icons are scaled to the specified size.
    icon_heightThe height of menu item icons.
    item_heightThe height of each menu item in pixels.
    item_paddingThe amount of space in pixels to leave on each side of the menu item contents.
    item_icon_spaceThe space between an item’s icon and the title text, in pixels.
    item_spacingThe amount of space to leave between menu items, in pixels.
    menu_pixmap_styleThe 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_styleThe image file pattern for the item styled box.
    selected_item_pixmap_styleThe image file pattern for the selected item highlight styled box.
    scrollbarBoolean value indicating whether the scroll bar should be drawn if the frame and thumb styled boxes are configured.
    scrollbar_frameThe image file pattern for the entire scroll bar. Example: “scrollbar_*.png“
    scrollbar_thumbThe 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_overlayIf 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_sliceThe 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_padThe left scrollbar padding in pixels. Unused if “scrollbar_slice“ is “west“.
    scrollbar_right_padThe right scrollbar padding in pixels. Unused if “scrollbar_slice“ is “east“.
    scrollbar_top_padThe top scrollbar padding in pixels.
    scrollbar_bottom_padThe bottom scrollbar padding in pixels.
    visibleSet 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:

xValue in pixels
p%Percentage
p%+xmixture 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“.

Next: Booting GRUB from the network, Previous: Writing your own configuration file, Up: GNU GRUB manual   [Contents][Index]