9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Grub2themetutorial
FromRosalabWiki

Grub22.00

Surfingthegreatworldwideweb,Ididn'tmanagetofindaguideforcreatingGRUB2themes,which
willhelpmeunderstandeveryvalueofeveryoptiononconcreteexamples.Nevertheless,whileyou're
creatingatheme,you'dliketheresulttobeexactlythesameasyouwanted.Soeverypixelisplaced
whereyouwantedittobe.So,readingthroughthesourcecode,I'vedecidedtowritesuchguide.The
goalofthisdocumentistorepresenteverypossibilityofgraphicaldecoration,showrestraintsand
featuresofGRUB2theming,giveaplantocreateanewtheme,withprecisionuptoapixel.

Contents
1Howtobegin
1.1createdirectory
1.2createtextfile
1.3parameterGRUB_THEMEin/etc/default/grub
1.4bootloaderconfigurationfile/boot/grub2/grub.cfg
2Commonconceptions
2.1Typesofelements
2.2Images
2.3Graphicaldecoration
2.4Fonts
3Testschemedescription
3.1decorationelements
3.1.1graphicaldecorationelement
3.1.2graphicaldecorationelement
3.1.3bootmenudecoration
3.1.4scrollbarbackground
3.1.5scrollbarthumb
3.1.6progressbardecoration
3.2images
3.2.1centralimageofcircularprogress
3.2.2tickimageofcircularprogress
4Propertiesofelements
4.1Commonproperties
4.2Rootelement
4.2.1desktopcolor,desktopimagebackground
4.2.2titletext,titlecolor,titlefonttitlesettings
4.2.3terminalboxconsoledecoration
4.2.4terminalfontconsolefont
4.2.5messagefont,messagecolor,messagebgcolornotused
4.3boot_menubootmenu
4.3.1left,top,width,heightcoordinatesoftherectangle
4.3.2item_color,item_font,selected_item_color,selected_item_fontfontand
colorofbootmenuitems
4.3.3seleted_item_pixmap_style,item_pixmap_styleitemsdecoration
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

1/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

4.3.4menu_pixmap_stylebootmenudecoration
4.3.5item_paddingpadding
4.3.6height,item_height,item_spacingitemscomposition
4.3.7iconwidth,iconheight,item_icon_spaceiconsandiconspace
4.3.8Usingoficons
4.3.9scrollbar_frame,scrollbar_thumb,scrollbar_width,scrollbarscrollbar
settings
4.3.10visibledon'tshowbootmenu
4.4progress_barHorizontalindicatorofelapsedtime
4.4.1left,top,width,heightcoordinatesoftherectangle
4.4.2ididentificator
4.4.3texttext,displayedontheprogressbar
4.4.4textcolor,fontcolorandfontofthetext
4.4.5Monocolorandgraphicalmodesofdecoration
4.4.6bg_color,fg_color,border_colorformonocolormode
4.4.7bar_style,highlight_styleforgraphicalmode
4.4.8Removedecoration
4.4.9visibledonotshowprogressbar
4.5circular_progressCircularindicatorofelapsedtime
4.5.1left,top,width,heightcoordinatesoftherectangle
4.5.2ididentificator
4.5.3center_bitmap,tick_bitmapimagesforthecircularprogressindicator
4.5.4num_ticks,start_angle,ticks_disappearcircularprogresssettings
4.5.5Example
4.6labelastringoftext
4.6.1left,top,width,heightcoordinatesoftherectangle
4.6.2font,colorcolorandfontofthetext
4.6.3alignaligning
4.6.4Showelapsedtimetobootingthedefaultitem
4.6.5textshowntext
4.6.6Examplewithcommonvalueoftext
4.6.7Examplewithspecialvalueoftext
4.7imageImage
4.7.1left,top,width,heightcoordinatesoftherectangle
4.7.2filefullpathtotheimagefile
4.8vboxverticalcontainer
4.8.1left,top,width,heightcoordinatesoftherectangle
4.8.2Compositionofcontainedelements
4.8.3Example
4.9hboxhorizontalcontainer
4.9.1left,top,width,heightcoordinatesoftherectangle
4.9.2compositionofcontainedelements
4.9.3Example
4.10canvasCanvas
4.10.1left,top,width,heightcoordinatesoftherectangle
5Commonfeautures
5.1Elements'drawingorder
5.2Element'sdrawingzone
5.3Element'sminimalsize
5.4Whatifnumbervaluesareincorrect
5.5Choosingofsymbol
6Fontcreationguide
6.1Createfontusinggrub2mkfont
6.2Parametersofgrub2mkfont
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

2/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

6.2.1output,o
6.2.2verbose,v
6.2.3name,n
6.2.4size,s
6.2.5bold,b
6.2.6ascent,descentofthefont
6.2.7Selectrangeofsymbolstoencode
7Parameterswhicharesetoutsideoftheme.txt
7.1/etc/default/grubFile
7.1.1GRUB_THEME
7.1.2GRUB_BACKGROUND
7.1.3LANGLANGUAGE

Howtobegin
So,wewanttocreateourowntheme.Let'sgostepbystep.

createdirectory
Atfirst,createemptydirectoryforfilesofthenewtheme.
Itisrecommendedtocreatesubdirectoryin/boot/grub2/themes/
(hereinafter,wesuggestthatbootloaderisinstalledtothedirectory/boot/grub2/)
Letitbedirectory/boot/grub2/themes/test/

createtextfile
Weshouldcreatemainthemefileinthedirectorywejusthavecreated.
Itisrecommendedtocallthefiletheme.txt.
So,wehavecreatedfile/boot/grub2/themes/test/theme.txt
(hereinafter,theme.txtormainthemefile)

parameterGRUB_THEMEin/etc/default/grub
Tomakethebootloaderswitchtoourtheme,weshouldset
parameterGRUB_THEMEinfile/etc/default/grub.
Inotherwords,weshouldwriteastringGRUB_THEME=/boot/grub2/themes/test/theme.txt.
Afterthesign"="weshouldwritetheabsolutepathtothemainthemefile.
IfthestringGRUB_THEME=...alreadyexistsin/etc/default/grub,
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

3/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

weshouldrewriteit,soitwillbeGRUB_THEME=/boot/grub2/themes/test/theme.txt.
Thereshouldn'tbetwostringsforthesameparameter.

bootloaderconfigurationfile/boot/grub2/grub.cfg
Changesinthisfilewon'tbeapplieduntilweregeneratebootloaderconfigurationfile.
Usually,thereisscriptupdate-grub2inthesystem.Itshouldberunwithrootrights.
Incasethereisnosuchscriptinthesystemweshouldruncommandgrub2-mkconfig -o
/boot/grub2/grub.cfgwithrootrights.
update-grub2doesexactlythesamecommand.
update-grub2shouldbecalledeachtimewemakechangesto/etc/default/grub.

MostofGrub2themeoptionsaredescribedintheme.txt.Grub2parsesthisfileeachtimeduringboot
process.Soweshouldreboottoseeresultofchangesmadetotheme.txtortoourthemedirectory.
update-grub2writesmainthemefile'spathtothebootloader'sconfigurationfile.

Commonconceptions
StartwithreadingMainfilesyntax.
Eachparameterhaveapredefinedtype.
YoucanreadaboutdatatypesHere.
Note,thatglobaloptionsandcomponents'namesarechecked.Ifthereisanerror,errormessagewillbe
shownduringbootprocess.Itisdifferentforcomponent'soptions.Ifthereisanerrorthenparameter
won'tbeappliedanderrormessagewon'tbeshown.

Typesofelements
Therearesomepredefinedtypes:
rootelement
Topleveloftheme.txt.Herewesetglobaloptions.
Bootmenu(boot_menu)
Themainelement.Herebootmenu'soptionsareset.
Horizontaltimeoutindicator(progress_bar)
Indicationofelapsedtimetoexecutionthedefaultentryofthebootmenu.Useshorizontaltaband
text.
Circulartimeoutindicator(circular_progress)
Indicationofelapsedtimetoexecutionthedefaultentryofthebootmenu.Usescircular
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

4/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

animation.
Textstring(label)
Outputatextstring.
Image(image)
Outputanimage.
Verticalcontainer(vbox)
Container.Elementwhichcontainsotherelements.Outputselementsverticallyonebyonefrom
toptobottom.
Horizontalcontainer(hbox)
Container.Elementwhichcontainsotherelements.Outputselementshorizontallyonebeonefrom
lefttoright.
Canvas(canvas)
Container.Elementwhichcontainsotherelements.Coordinatesshouldbesetforeachchild
element.
Rootelementisaninstancecanvaswithsomeadditionaloptions.Itisstretchedtothescreendimensions.

Images
Imageisstretchedtothedefinedsized,ifthesesizesaregreaterthanrealimage'ssizes.Minimalvalues
arerealimagesizes.
Youshouldtakethisfeatureintoaccountwhileselectingbackgroundimage.Thereareseveraltypesof
displays.Thesameimagecanlookdifferentondisplayswithaspectratio4:3and16:9.
Ifimageisanlogotypeyoushoulduseabsolutevaluesforparameterswidthandheightsotherewon'tbe
anydistortions.
Usingstretchingitiseasytododifferentkindsofgradients.Forexample,youcouldusegradientimage
1pxwidth.

Graphicaldecoration
Graphicaldecorationofanelementconsistsof9zonescentral,south,southwest,westetc.
4diagonalzones(northwestetc)arenotstretched.
Eastandwestzonesarestretchedbyvertical.
Northandsouthzonesarestretchedbyhorizontal.
Centralzoneisstretchedbyverticalandbyhorizontal.
Ifthereisadiagonalzoneinthedecorationsothereshouldbebothsidezonesinthedecoration,
connectedwiththediagonalzone.E.g.ifthereisnorthwestzone,sothereshouldbebothnorthand
westzones.Moreover,constantvaluesofthediagonalzoneshouldbeequaltocorrespondingvaluesof
sidezones.Inourexample,heightofnorthwestzoneshouldbeequaltotheheightofnorthzoneand
widthofthenorthwestzoneshouldbeequaltothewidthofthewestzone.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

5/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Fonts
Fontsshouldbecreatedusingspecialutilitygrub2-mkfont.Moredetailedinformationin"Fontcreating
guide"

Testschemedescription
decorationelements
Increasedin5timesforbetterunderstanding.Alphachannel75%.(transparency)
Darkredbackgroundforclarity.

graphicaldecorationelement
inbox_*.png

graphicaldecorationelement
button_*.png

bootmenudecoration
menu_*.png

scrollbarbackground

http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

6/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

scrollbar_frame_*.png

scrollbarthumb
scrollbar_thumb_*.png

progressbardecoration
progress_*.png

images
centralimageofcircularprogress
center.png

tickimageofcircularprogress
tick.png

Propertiesofelements
Completedescriptionofoptionvalueswithscreenshotsandschemes.

Commonproperties
briefdescription
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

7/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

left, top, width, heightcoordinatesoftherectangle,containinganelement.

thanspecialwon'taffectanything.

Rootelement
briefdescription
Rootelementistheelementcontainingeveryelementofthetheme.Alsoitcontainsseveralglobal
options.Rootelementisanextendedcanvaselement.
Note,thatglobaloptionnamecontainsminuscharacter("-",e.g."terminal-box"),butelements'
optionscontainunderlinecharacter("_",e.g."item_height").Alsonotethatglobaloptionsusecolon
characterasthedivider(":",e.g."title_text: "GNU Grub""),butelementsoptionsuseequalsign
characterasthedivider("=",e.g."item_height = 20").
desktop-color, desktop-imagebackground

Firstisbackgroundcolor.
Secondisbackgroundimage.
Ifdesktop-imageissetthendesktop-colorisnotused.
Imageshouldbeplacedintothetheme'sdirectory.
Imageisscaledtothescreenresolution.
title-text, title-color, title-fonttitlesettings

Titledecor.Ifthetitleshouldn'tbeshown,settitle-text="".
Titletextisalwayscenteralignedandtext'sbaselineisplacedat40 + ascentfromthetopsideofthe
screen.(seeFontcreatingguide)
title-text: "Title Text"
title-color: "#FFFFFF"
desktop-image: "background.png"

terminal-boxconsoledecoration

Graphicaldecorationoftheconsole.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

8/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

DecorationisdrawnOUTSIDEoftheconsolerectangle.Coordinatesoftheconsoleareconstantand
hardcoded.Theycanbechangedusingapatch.Seebelow.
Note,thatconsoleisdrawnoncenterslicewith3pxpaddingfromeachside.
Consolebackgroundissetin/etc/default/grub.Seebelow.
Animagefortheconsolebackgroundshouldnotbetransparent.
Bydefaulttherewillbeblackscreen.
terminal-fontconsolefont

Thenameofthefont,usedintheconsole.
Afteranewfonthasbeenaddedtothetheme'sdirectory,update-grub2shouldbeexecuted.
Seemoreaboutfont'screatinginfontcreating
title-text: ""
desktop-image: "background.png"
terminal-font: "Droid Sans Mono Regular 11"
terminal-box: "inbox_*.png"

Hereinafter,globaloptionsareexactlythesame.

message-font, message-color, message-bg-colornotused

Theseparameterscanbeset,buttheyaren'tusedcurrently.

boot_menubootmenu
briefdescription
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

9/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Themainelement.Showsthelistofinstalledoperatingsystems.Wecanselectthesystemwe'dliketo
bootin.
left, top, width, heightcoordinatesoftherectangle

Standardparameters.Don'tforgettosetthem.
item_color, item_font, selected_item_color, selected_item_fontfontand

colorofbootmenuitems
Wemustunderstandwhichitemisselected,soitshouldbehighlightedsomehow.Wecanusefont,color
orgraphicaldecoration.item_color, item_fontcolorandfontofnonactivemenuitems
selected_item_color, selected_item_fontcolorandfontoftheselecteditem
+ boot_menu {
left = 50%-300
top = 50%-100
width = 600
height = 300
selected_item_color = "#0000FF"
}

Seemoreaboutfont'screatinginfontcreating
seleted_item_pixmap_style, item_pixmap_styleitemsdecoration

ThedecorationisdrawnOUTSIDEofmenuitem.
Bydefaultwecansetgraphicaldecorationonlyfortheselectedmenuitem.
InROSAyoucouldsetgraphicaldecorationfornonactivemenuitems.
Letsdefinesizesofselecteditem'sframeaspad_left,pad_top,pad_rightandpad_bottom.Fullitem's
heightwillbeitem_height + pad_top + pad_bottom - 1.
Youshouldtakedecreasingby1intoaccounttoachievethedesiredsizeoftheselecteditem.

http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

10/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

+ boot_menu {
left = 50%-300
top = 50%-100
width = 600
height = 300
selected_item_color = "#0000FF"
selected_item_pixmap_style = "button_*.png"
}

menu_pixmap_stylebootmenudecoration

MenudecorationisdrawnINSIDEthedesiredrectangleoftheelement(bootmenu).Sizedofthis
decorationarecountedformenuitems(menuitemsaredrawninthecenterslice).Itismorecomplicated
forascrollbar(seebelow).
item_paddingpadding

Setsprintingareaofbootmenuitemsrectangleinsidecentralsliceofmenu'sgraphicaldecoration(or
entiremenurectangleifnographicaldecorationisset)withpaddingitem-paddingfromeachsideof
centralsliceedges(orfromedgesofbootmenu'srectangleifnographicaldecorationisset).
Note,thatitem_paddingdoesnotaffectscrollbar'soutfit.Modifygraphicaldecorationsofmenuand
scrollbarifchangesinscrollbarpaddingareneeded(e.g.youcanaddtransparentpixelsto
correspondingareas)
height, item_height, item_spacingitemscomposition

Distancebetweenbottomsidesofmenuitems(seepicture)isalwaysitem_height + item_spacing.
Note,thatformulaofshownitemsnumberincludesmenu'sframeanditem_padding,butexcludes
pad_topandpad_bottom.(seepicture)
heightshouldbecountusingunobviousformula.Nisthenumberofitemswewouldliketosee.Total
heightshouldbeequalto
2*item_padding + menu_pad_top + menu_pad_bottom + (N - 1)*(item_height +
item_spacing) + pad_top + pad_bottom + item_height - 1

Alsonote,thatminimalnumberofshownitems(N)is3.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

11/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Ifheightislessthenthevalue,countedwiththisformula,numberofmenuitemsisbigenoughandthe
bottomitemisselected,thengraphicaldecorationoftheselecteditemwon'tbedrawncompletely.if
heightisgreaterthenthevalue,countedwiththisformula,numberofmenuitemisbigenoughandthe
bottomitemisselected,thenthescrollbar'sbottomedgewillnotbealignedwithbottomedgeofthe
selecteditem'sgraphicaldecoration.
+ boot_menu {
left = 50%-300
top = 50%-100
width = 600
height = 289
selected_item_color = "#0000FF"
selected_item_pixmap_style = "button_*.png"
menu_pixmap_style = "inbox_*.png"
item_padding = 20
item_spacing = 20
item_height = 30
}

Heightiscountedusingthegivenformula.

icon-width, icon-height, item_icon_spaceiconsandiconspace

Bydefault,
icon_width = 32
icon_height = 32
item_icon_space = 4

Textisindentedadditionallyforicon_width + item_icon_spacefromtheleftedgeoftheitem's
drawingarea.Inotherwords,freespaceforaniconisalwaysleftindependentlyofisthereanicontobe
drawnornot.
Ifthisbehaviorisunwantedyoushouldnullicon_widthandsetdesiredvalueforitem_icon_space.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

12/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Alsonote,thatwidthofmenuitemsisdecreasedby2pixels.Thatway,wewillseeadditional2pixels
offreespacefromtherightedgeofeastsliceofthemenu.
Note,thatfont'ssymbolscanincludeemptypixelsfromeitherside.E.g.inouttestscheme,distance
fromtheleftedgeis36bydefault(icond_width + item_icon_space),butdistancetothefirstpixelof
thefirstsymbolis37.

Usingoficons
Ifyou'dliketouseiconsyoushouldmakedirectoryimageinthethemedirectory.
Thenyoushouldplaceiconsinpngformattothedirectoryimage.Icon'snameshouldcorrespondto
somepredefinedclass.
Defaultclasses:
windows>os
gnulinux>gnu>os
osx>darwin>os
hurd>gnu>os
Moreimportantclassistotheleft.Ificonwindows.pngisfoundthenitwillbeshown.Theiconos.png
willnot.
Mainsystem'sclass(equaltoit'sname)willbeavailablealso.(mainsysteminthiscaseisthesystem
whereupdate-grub2scriptwascalled).Thisclassismoreimportantthangnu-linux.
E.g.forROSAsystemthisclasswillbe"rosa"etc.Youcanfindclassesinthefile
/boot/grub2/grub.cfg.
WithpatchappliedtoROSA,suchclasswillbeshownforeveryotherinstalledOSontheparticular
computer.
scrollbar_frame, scrollbar_thumb, scrollbar_width, scrollbarscrollbar

settings
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

13/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Let'sseedetailedinformationaboutscrollbars.
Donotuseslicesdifferentfromnorth,southandcenterforscrollbar_thumb.
Youcoulduseall9slicesforscrollbar_frame.
Youcanincreasepaddingfromanysideofthescrollbarbyaddingtransparentpixelstothe
correspondingslice.
Scrollbarisdrawntotherightofthecenterslice.So,ifwedon'thavemenu'sgraphicaldecoration
orthereisn'teastsliceinthemenu'sgraphicaldecorationwewon'tseescrollbarevenifit's
needed.
Scrollbarisdrawnonlyifneeded.
Notethatwidthofthebootmenuisdecreasesby2pixels(frommaximumwidth).Becauseofthat
distancebetweenmenuitemsandthescrollbarisalwaysatleast2pixels.
Youhavetosetbothscrollbar_frameandscrollbar_thumb.Ifoneoftheseparametersisn'tset
youwon'tseethescrollbar.
Widthofscrollbar_frameandwidthofscrollbar_thumbcanbedifferent.
scrollbar_frameisdrawnintheeastsliceofmenu'sgraphicaldecoration.scrollbar_thumbis
drawnentirelyinthecentersliceofscrollbar_frame.
scrollbar_widthwidthofthescrollbar.Itmeanswidthofthecentralpartofscrollbar_frame.
Ifsumofscrollbar_widthandwidthsofeastandwestslicesofscrollbar_framearelessthan

widthoftheeastsliceofmenu'sgraphicaldecoration,thenthescrollbarwon'tbedrawn
completely.
YoucouldsetvalueFalseforscrollbar.Inthatcasethescrollbarwon'tbeshown.Alternative:
justdon'tsetparametersscrollbar_thumbandscrollbar_frame.
Asitwassaidbefore,item_paddingdon'taffectsthescrollbar.
Inthisexampletherearenoadditionalpixelsforthescrollbarintheeastsliceofmenu'sgraphical
decoration.
+ boot_menu {
left = 50%-300
top = 50%-100
width = 600
height = 289
selected_item_color = "#0000FF"
selected_item_pixmap_style = "button_*.png"
menu_pixmap_style = "inbox_*.png"
item_padding = 20
item_height = 30
item_spacing = 20
scrollbar_thumb = "scrollbar_thumb_*.png"
scrollbar_frame = "scrollbar_frame_*.png"
scrollbar_width = 10
}

http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

14/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Aswecansee,scrollbarisn'tcompletelydrawn.

Inthisexamplewehavechangedmenu'sgraphicaldecoration.We'llusethisconfigurationoftheboot
menuhereinafter.boot_menu.
+ boot_menu {
left = 50%-300
top = 50%-100
width = 600
height = 289
selected_item_color = "#0000FF"
selected_item_pixmap_style = "button_*.png"
menu_pixmap_style = "menu_*.png"
item_padding = 20
item_height = 30
item_spacing = 20
scrollbar_thumb = "scrollbar_thumb_*.png"
scrollbar_frame = "scrollbar_frame_*.png"
scrollbar_width = 10
}

Nowthescrollbariscorrectlydisplayed.Alsowecanseethatitem_paddingdoesnotaffectthe
scrollbar.

http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

15/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

visibledon'tshowbootmenu

WecansetvalueFalseforthevisibleproperty.Thatwaythebootmenuwon'tbeshown.Alternative:
donotdescribeboot_menucomponentinthemainthemefile.

progress_barHorizontalindicatorofelapsedtime
Briefdescription
Thiselementdisplayselapsedtimetoexecutionofthedefaultentry.
Progressstartsfromnonzerolength.
left, top, width, heightcoordinatesoftherectangle

Standardparameters.Don'tforgettosetthem.
Notethatifwidthorheightislessthanneededtodisplaythegiventextthenwidthorheightwillbe
autoincreased.
ididentificator

Todisplaycountdown(visuallyortextually)youshouldsetpredefinedvaluetoid.
id = "__timeout__"

texttext,displayedontheprogressbar

Texttooutputonthecountdownindicator.Thereareseveralpredefinedspecialvalues.Theyhave
specialmeaningandaretranslatedtodifferentlanguages.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

16/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

@TIMEOUT_NOTIFICATION_SHORT@for"Ns"
@TIMEOUT_NOTIFICATION_MIDDLE@for"Nsremaining."
@TIMEOUT_NOTIFICATION_LONG@for"Thehighlightedentrywillbeexecuted
automaticallyinNs."
Nisanamountofsecondstoexecutionofthedefaultentry.Thestringisupdatedeverysecond.Alsoyou

cansetanyconstanttextvalue.
text-color, fontcolorandfontofthetext

Fontandfontcolorofthetextstring,printedontheindicator.
Seemoreaboutfont'screatinginfontcreating

Monocolorandgraphicalmodesofdecoration
Thereare2optionsofdecoration:
monocolormode,withareasfilledwithfixedcolorsand1pxborder
graphicalmode,withgraphicaldecorations
Ifoneoftheoptionsforgraphicaldecorationisusedthenwillbeturnedonthesecondoption.Otherwise
thefirstoptionwillbeused.
Seedetailedinformationbelow.
bg_color, fg_color, border_colorformonocolormode
+ progress_bar {
left = 50%-300
top = 50%+200
width = 600
height = 50
id = "__timeout__"
text = "@TIMEOUT_NOTIFICATION_LONG@"
border_color = "white"
}

Defaultvalueareusedinthisexample:
bg_color = "128, 128, 128"
fg_color = "200, 200, 200"

bar_style, highlight_styleforgraphicalmode

Note,itisrecommendedtouseonlycentralsliceforthehighlight_styleparameter.Otherwisethe
countdownindicatorwillbeshownincorrectly.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

17/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Note,usingofanyoftheseparametersturnsonthegraphicalmode.
+ progress_bar {
left = 50%-300
top = 50%+200
width = 600
height = 50
id = "__timeout__"
text = "@TIMEOUT_NOTIFICATION_LONG@"
bar_style = "inbox_*.png"
highlight_style = "progress_*.png"
}

Removedecoration
Ifyou'dliketoremovedecorationssoonlythetextstringwillbeshownyoushouldsetequalvaluesto
bar_stylyandhighlight_style.
Thevaluecanbeanytextvalue.Thisisnotnecessaryforthevaluetobethenameofsomereal
graphicaldecoration.
Thevaluemustincludethesymbol"*".
Inthefollowingexampletextcoloris"white".
+ progress_bar {
left = 50%-300
top = 50%+200
width = 600
height = 50
id = "__timeout__"
text = "@TIMEOUT_NOTIFICATION_LONG@"
text_color = "white"
bar_style = "*"
highlight_style = "*"
}

visibledonotshowprogressbar

YoucouldsetthevalueFalsetothisparameter.Thatwayprogressbarwon'tbeshown.Alternative:just
don'tuseprogress_barelementinthemainthemefile.

http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

18/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

circular_progressCircularindicatorofelapsedtime
Briefdescription
Circularindicatorofelapsedtimeshowsgraphicallytheelapsedtimetoexecutingthedefaultentry.
Elapsedtimeisdisplayedwithdrawingticks.
Ifticks_disappearisn'tsetthenticksareappearing(alongthecircumference,clockwise)untilthe
circleiscompleted.
Ifticks_disappearissetthenticksaredisappearing.
Numberofdrawnticksisalwaysdecreasedby1.Sometickscanbedrawnatthefirststate.(circular
indicatorstartsfillingfromnonzerovalue)
left, top, width, heightcoordinatesoftherectangle

Standardparameters.Don'tforgettosetthem.
Itisrecommendedtosetsimilarvaluetowidthandtoheight.Detailedinformationaboutrectangle
coordinatesfeaturesseebelow.
ididentificator

Todisplaycountdownyoushouldsetpredefinedvaluetoid.
id = "__timeout__"

center_bitmap, tick_bitmapimagesforthecircularprogressindicator

Centralimageneitherscaledorturned.It'sdrawninthecenterofthedesiredrectangleoftheelement.If
theimageislessthantherectanglethenpartoftheimagewon'tbedrawn.It'sthebackgroundofthe
indicator.
Tickimagealsodoesn'tscaledorturned.It'sdrawnmultipletimescircumferential.Thecircleis
inscribedintothedesiredrectangle.
It'srecommendedtousesquareimages(heightandwidtharethesame).
Calculationsuseelements'widthandtick'swidth.
Ifwidthoftheelementisgreaterthenit'sheightthensometickswon'tbedrawn.

http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

19/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Ittick'sheightisgreaterthenit'swidththentickswon'tbecompletelydrawn.

It'srecommendedtomaketick'swidththesameparityaselement'swidth.(onlyinthatcasewewillhave
correctsymmetricaldisplaying)
num_ticks, start_angle, ticks_disappearcircularprogresssettings
num_ticksThenumberoftickstomakeafullcircle.
start_angleThestartingangle.(startingfromxaxis).It'smeasuredin"parrots".One"parrot"1/256

ofthefullcircle.Thatway-90degree(or-/2)willbe-64"parrots".
tick_bitmapisdrawnwithoutanychanges(noturning,noscalingetc)andanglesaremeasured(inthe

algorithm)in"parrots"soit'srecommendedtosetnum_tickswithvaluesequaltonthpowerof2.That
waywewillhavesmoothandsymmetricalpicture.
ticks_disappearbydefaultticksareappearing.

YoucouldsetvalueTrueforticks_disappearparameter.Inthiscasetickswilldisappearuntilnoneof
themarepresent.
ticks_disappear = "True"

Note,thatnumberofdrawnticksisalwaydecreasedby1.

Example
+ circular_progress {
left = 50%-450
top = 50%+310
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

20/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

id = "__timeout__"
width = 51
height = 51
center_bitmap = "center.png"
tick_bitmap = "tick.png"
num_ticks = 8
}

labelastringoftext
Briefdescription
Wecandisplayalineoftextusinglabelelement.
Ifspecialvaluesforidandtextaresetthenelapsedtimetoexecutionofthedefaultentrywillbe
shown.
Notethatthereisnotlinebreakingmechanism.Ifprintinglengthofthetextlineisgreaterthen
rectangle'swidthwillbeincreased.
left, top, width, heightcoordinatesoftherectangle

Standardparameters.Don'tforgettosetthem.
Notethatwidthisusedonlyforaligningthetextifalignparameterhavevalueof"center"or
"right".
Notealsothatheightisn'tused.
font, colorcolorandfontofthetext

Fontandcolorofthetext.
Seemoreaboutfont'screatinginfontcreating
alignaligning

Threecorrectvaluesareavailable:
leftalignthetextbytheleftedgeoftheelement
centeralignthetextbycenteroftheelement
rightalignthetextbytherightedgeoftheelement

Showelapsedtimetobootingthedefaultitem
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

21/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Toshowtheelapsedtimeweshouldsetspecialvalueofidandtheparametertextshouldnotbepresent
inthedescriptionoftheelementinthemainthemefile.
+ label {
left = 50%-350
top = 50%+260
height = 30
width = 30
id = "__timeout__"
color = "white"
}

textshowntext

Wecanoutputanytextmessage.Thereareseveralspecialvalues:
@KEYMAP_SHORT@for"enter:boot,`e':options,`c':cmdline"
@KEYMAP_MIDDLE@for"PressentertoboottheselectedOS,`e'toeditthecommandsbefore
bootingor`c'foracommandline."
@KEYMAP_LONG@for"PressentertoboottheselectedOS,`e'toeditthecommandsbefore
bootingor`c'foracommandline.ESCtoreturnpreviousmenu."
Specialvaluesaretranslatedtothelanguage,usedinGRUB.
Notethatthereisnolinebreakingmechanismandtextline'swidthisn'tlimited.

Examplewithcommonvalueoftext
+ label {
left = 50%-300
top = 50%+220
height = 30
width = 600
color = "white"
align = "right"
text = "Some text."
}

Examplewithspecialvalueoftext
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

22/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

+ label {
left = 50%-300
top = 50%+220
height = 30
width = 600
color = "cyan"
align = "center"
text = "@KEYMAP_SHORT@"
}

imageImage
Briefdescription
Animagecanbedisplayedonthescreen.
Ifimage'sheightislessthandefinedheight,thendefinedheightwillbesettotheimage'srealheight.
Thesameworksfortheimage'swidth.
Ifdefinedwidthorheightaregreaterthanimage'srealwidthorheight(correspondingly)thentheimage
willbestretchedtothedefinedsize.
left, top, width, heightcoordinatesoftherectangle

Standardparameters.Don'tforgettosetthem.
Ifyou'dliketodisplayunchangedimagejustdon'tsetwidthandheightparameterstheywillbeset
automatically.
filefullpathtotheimagefile

Fullpathtotheimagefile.

vboxverticalcontainer
Briefdescription
Container.Parentelementwhichcontainsotherelements.
left, top, width, heightcoordinatesoftherectangle
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

23/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Don'tforgettosetleftandtopparameters.heightandwidthareignoredandwillberedefinedsoyou
don'tneedtosetthem.

Compositionofcontainedelements
Elements,containedintheverticalboxareshownconsequentiallyfromtoptobottom.
Youdon'tneedtosetleftandtopparametersforchildelementsthesevalueswon'tbetakeninto
account.
Maximumofchildelements'widthsisbeingcounted,thenallwidths(widthsofeverychildelementand
thecontainer)verticalaresetwiththeresultingvalue.
Valuesofchildelements'heightsaren'tchange.

Example
+ vbox {
left = 50%+310
top = 50%-50
width = 20
height = 100
#D1
+ image { left = 50 top = 10 width = 60 height = 60 file = "center.png" }
#D2
+ image { left = 40 top = 20 width = 70 height = 70 file = "button_n.png" }
}

hboxhorizontalcontainer
Briefdescription
Container.Parentelementwhichcontainsotherelements.
left, top, width, heightcoordinatesoftherectangle

Don'tforgettosetleftandtopparameters.heightandwidthareignoredandwillberedefinedsoyou
don'tneedtosetthem.

compositionofcontainedelements
Elements,containedinthehorizontalboxareshownconsequentiallyfromlefttoright.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

24/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Youdon'tneedtosetleftandtopparametersforchildelementsthesevalueswon'tbetakeninto
account.
Maximumofchildelements'heightsisbeingcounted,thenallheights(heightsofeverychildelement
andthecontainer)aresetwiththeresultingvalue.
Valuesofchildelements'widthswon'tchange.

Example
+ hbox {
left = 300
top = 50%+310
width = 20
height = 100
#D1
+ image { left = 50 top = 10 width = 60 height = 60 file = "center.png" }
#D2
+ image { left = 40 top = 20 width = 70 height = 70 file = "button_n.png" }
}

canvasCanvas
Briefdescription
Container.Parentelementwhichcontainsotherelements.Childelements'coordinatesarerelative.That
way,(0,0)forachildelementiscoordinatesoftopleftcornerofthecontainer.
Rootelementisaninstanceofcanvas.
left, top, width, heightcoordinatesoftherectangle

Standardparameters.Don'tforgettosetthem.

Commonfeautures
Commonfeaturesnotrelatedtosomeconcretesubject.

Elements'drawingorder
Elementsaredrawnconsequentlyfromtoptobottominaverticalbox.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

25/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Elementsaredrawnconsequentlyfromlefttorightinahorizontalbox.
Childelementsforacanvasaredrawninreverseorder.IfelementAinplacedbeforeelementBinthe
mainthemefilethenAwillbedrawnafterB.

Element'sdrawingzone
Thereisdrawingareadefinedforeachelement.Itissetwithparametersleft,top,width,height.
Everythingthatcrossesthedefinedareawon'tbedrawn.

Element'sminimalsize
Eachelementhaveafunctionfordeterminationoftheminimalsizeoftherectangleenoughtodrawthis
element.Ifdefinedwidth(height)islessthenminimalwidth(height)thendefinedwidth(height)willbe
redefinedtotheminimalvalue.

Whatifnumbervaluesareincorrect
Descriptionofnumericvalues.
Note,thatabsoluteandrelativevaluesarecountedrelativetotheparentcontainer.
Letscallwidthandheightoftheparentcontainerparent_widthandparent_heightcorrespondingly.
Itleftortoparenegativeitwillberedefinedto0.
Ifleft+widthisgreaterthanparent_widththenwidthwillberedefinedtoparent_width - left.
Thatway,rightedgeoftheelementwillmatchrightedgeoftheparentcontainer.
Iftop+heightisgreaterthanparent_heightthenheightwillberedefinedtoparent_height - top.
Thatway,bottomedgeoftheelementwillmatchbottomedgeoftheparentcontainer.
Wecanusethisfeaturestoachievedifferentcompositionofelementsondifferentscreenresolutions.

Choosingofsymbol
Thefontofanelementisdescribedinthemainthemefile.Ifthedesiredfonthasn'tbeenfoundorthe
desiredsymbolisn'tcontainedinthedesiredfontthemostappropriatesymbolfromanotherfont
(presentinthetheme)willbeused.
Forexamplebordersymbolsaren'tpresentinsomefonts.Ifwe'veselectedsuchfonttobethefontofthe
consolethenbordersymbolswillbetakenfromanotherfont.Knowingthisfeaturehelptoavoid
confusionaboutunexpectedresults(e.g.dashedborderorquestionmarksymbolsinplaceoftheborder)

Fontcreationguide
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

26/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Briefdescription
GRUBusesit'sownfontformat.Neededfontcanbecreatedusingtheutilitygrub-mkfont
Afterthefonthasbeencreatedandplacedintothetheme'sdirectory,utilitygrub2-updateshouldbe
executedsothechangeswillbeapplied.

Createfontusinggrub2-mkfont
GRUBdon'tusekerning(changesofthedistancebetweenthesymbolsincaseofsomecharacter
combinations).
File,resultingfromexecutionoftheutilityshouldnecessarilyhavetheextension.pf2
Syntax:
grub2-mkfont INPUT_FONT [optional parameters] -o OUTPUT_FONT

Resultingfileshouldbeplacedintothethemedirectory.

Parametersofgrub2-mkfont
--output, -o

Necessaryparameter.Thenameoftheresultingfile.Shouldhaveextension.pf2sothefontcanbeused
byGRUB.
--verbose, -v

grub2mkfontDroidSansMono.ttfotmp.pf2v
Font name: Droid Sans Mono Regular 16
Max width: 13
Max height: 17
Font ascent: 17
Font descent: 5
Number of glyph: 591

Displayinformationaboutthecreatedfont.
Displaysname,maximumwidthandheight,ascentanddescentofthefont,quantityofsymbols.
--name, -n

Setthefont'sname.
Bydefault,font'snameisautocreatedwithtemplate:FONT_NAMETYPESIZE
--size, -s

Setthefont'ssizeinpixels.
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

27/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Thevalueis16bydefault.
--bold, -b

Outputboldfont.
Itisnormalbydefault.
ascent,descentofthefont

--asce, -c

ascentofthefont(seepicture)
--desc, -d

descentofthefont(seepicture)
Wecansettheseparameterstoachievelarger\lesserlinespacing,toalignthebaseline(seepicture).If
wearegoingtosettheseparametersweshouldwatchcarefullythateveryneededsymboliscorrectly
displayed.

Selectrangeofsymbolstoencode
Wecansetarangeofsymbolstoencode.
--ascii-bitmaps

toencodeonlyasciisymbols
--range, -r

toencodethegivenrangeofsymbols

Parameterswhicharesetoutsideoftheme.txt
http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

28/29

9/3/2015

Grub2 theme tutorial - Rosalab Wiki

Options,whicharesetoutsideofthemainthemefile.

/etc/default/grubFile
GRUB_THEME
Fullpathtothemainthemefile.

GRUB_BACKGROUND
Fullpathtothebackgroundimageoftheconsole.Thisfileshouldbenontransparent.It'sstretchedto
thesizesoftheconsole.(notethe3pxborder)

LANGLANGUAGE
Ifyou'dliketosetalanguageusedinGRUByoushouldsetboththisparameterstothesamevalue.
Differentsyntaxcanbeused:en,en_US,en_US.UTF-8.

VladimirTestov,ROSA,2013.
Retrievedfrom"http://wiki.rosalab.ru/en/index.php?title=Grub2_theme_tutorial&oldid=7882"
Thispagewaslastmodifiedon6September2013,at11:33.
Thispagehasbeenaccessed42,006times.
[0watchingusers]
ContentisavailableunderCreativeCommonsAttributionShareAlike3.0License(CCBYSA)
unlessotherwisenoted.

http://wiki.rosalab.ru/en/index.php/Grub2_theme_tutorial#How_to_begin

29/29