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".

