Downloads

releases

current build

extras

Documentation

FAQ

manual

wiki

docs index

Support

mailing lists

IRC

forums

Tracker

bugs

patches

TWiki > Main > ThemeGuidelines

Guidelines for Submitting Themes

(We like to think of them more as rules)

Theme Name

Please don't include the platform name in the theme title. On the Wiki, and in this site all themes are stored according to the devices they are combatible with, and having "Nano" or "SansaE200" on every theme name on your Nano or E200 is just silly.

File Structure

The currently preferred method of packaging a theme file is .ZIP. This zip file should be names to match your theme. If you are dealing with a theme that is for multiple platforms, or are converting an existing theme to a new platform, then including the platform name in the zip filename is fine. Once submitted to this site, that portion of the filename will almost always be removed before uploading.

Inside your zip file should be a folder called .rockbox, and inside this folder 'backdrops', 'fonts', 'themes', 'icons' & wps folders as appropriate- all lowercase. pCase is important... If you don't exactly match filenames etc on unix based platforms - when running a sim for example - the theme will fail to load.

If you created the zip file in a Windows based PC, check inside the backdrops and wps folders for 'thumbs.db' files - these can be deleted as they serve no use to anyone else, and just take up disk space on the device (sometimes several hunderds of kilobytes!)

File Naming

Remember, not everyone will want to load the whole of your theme, they must like to 'mix and match' with a wps from one theme, a backdrop from another etc., so please try to name your backgrounds, wps's and themes consistently.

A bad example

       #My sample theme - mymates.cfg 
       wps: /.rockbox/wps/myfirstwps.wps
       font: /.rockbox/fonts/snap.fnt
       backdrop: /.rockbox/backdrops/johnandstuart.bmp
       iconset: /.rockbox/icons/silk.18x17x16.bmp
       viewers iconset: /.rockbox/icons/tango_viewers.20x16x16.bmp
       foreground color: 000000

This would make it difficult for someone to easily know which backdrop is being used by this theme, and makes removing the theme from your device just that little more difficult etc. and could have problems reading the text if the previous theme had set 000000 as the backgound color

       #Theme Name: Killers 
       #By: Rockboxuser@somedomain.net (MrCoolNick on IRC)
       #Platform: iPod Video (320x240x16) - Standard build
       #Version: 0.1 beta
       #Licenced CC-BY-SA 3.0
       #Graphics taken from mymates.com
       #Last updated: Wed, 16th May 2007 17:22 CEST
       wps: /.rockbox/wps/mymates.wps
       font: /.rockbox/fonts/snap.fnt
       backdrop: /.rockbox/backdrops/mymates.bmp
       iconset: /.rockbox/icons/silk.18x17x16.bmp
       viewers iconset: /.rockbox/icons/tango_viewers.20x16x16.bmp
       foreground color: 000000
       background color: FFFFFF

This is now easy to see which backdrop and wps is being used by this theme, and the text would always be readable regardless of what colours had been set previously... in addition the header gives more information about the thems, and who to contact in the event of problems with it...

Colours and Backdrops

If you load a coloured background on your wps and a coloured backdrop in the menu, you will obviously need to change the forground colour selected in your theme - it would be unreadable otherwise - but you should also set the background colour to a contrasting shade, else when another theme is loaded that assumes the default dark on light colour scheme, the text can become unreadable. Put simply - ALWAYS set both a foreground and background color, and ensure that they have sufficient contrast to be readable without your background images being loaded

Patches and Builds

Many themes will not work with the official build, and it is expected that the theme author suggests a suitable build that can run the theme correctly to make life easy for novice users, it would also be a great benefit to experienced users if the specific patches required are specified.

Versioning

Please consider building a version number into your theme - either in a comment or as a separate text file inside the zip, along with a date.

Licensing

Please consider publishing your theme with an appropriate license. No one can modify material from your theme if it is not published with a suitable license. Please make sure that any 3rd party images have an appropriate license (granting re-use and/or modification). For some sources of images published with a clear license see FreeImages.