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