dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Search | Go
Wiki > Main > CustomIcons

Custom Icons


Rockbox comes with a built-in set of monochrome icons that are enabled by default. These can be changed by the use of an Iconset. This is basically a series of bitmap images that replace those used in the default set.

Files Needed

These files must be place in /.rockbox/icons/:

  • A single BMP file of the icons used by the lists. This BMP size is <icon width> wide and <icon height> x <icon count> high. The icons are put in the BMP in the order they appear in apps/gui/icon.h (the enum themable_icons section). The current <icon count> is 32, not including the file types/viewers set. Each individual icon can be any size up to 24x24 pixels and in full 16-bit colour. For the colour targets RGB code <255,0,255> is transparent as is white on the mono targets.

  • For targets with remote displays you can provide a second set of icons in the same format as above. The main icons and remote icons can be of different sizes.

  • A separate BMP to hold the icons you wish to use for file types/viewers. There cannot be more icons in this file than in the main set, but you can have as few as you want, and the icons must be of the same dimensions as the main set.

  • Remote display capable targets can have another version of the above for the file type icons on the remote.

  • An .icons file (explained below).

Editing the Config File

There is no menu item in the user interface to load an icon set, so you have to use the .cfg file. The following codes load the various icon files:
  • iconset: - filename of the main icon set (for the list icons)
  • remote iconset: - filename of the main icon set for the remote display (for the list icons)
  • viewers iconset: - filename of the file type/viewers icon set
  • remote viewers iconset: filename of the file type/viewers icon set for the remote display

The ".icons" File

When a file type/viewers icon set is loaded, it checks the /.rockbox/icons/ folder for a file with the same name as the main icon set but with the extension .icons instead of .bmp. This file is a text file which lets you choose which icon to load for which file extension. The file is in the format "<ext>: <icon>" where <ext> is the extension of the file you want to use (e.g. "bmp") and <icon> is one of the following:

  • 0-31: The index of the icon in the file types/viewers icon set (0 is the first, 1 the second, and so on, from top to bottom).
  • *0-32: The index of the icon in the main icon set (*0 is the first, *1 the second, and so on, from top to bottom).
  • - : No icon.

How Does Rockbox Decide Which Icon to Display For a File Type?

  1. On startup the built-in file types are loaded (mp3, cfg, etc... the table in tree.c).
  2. Next the viewers.config file is read. The main purpose of this file is to make sure the build script copies plugins into the correct folder and to add "support" for file types which are not in tree.c. So, this means that icons for already known file types are ignored in this file. Users should never edit this file as part of an icon set.
  3. Once those files have been loaded, the .icons file for your viewers bmp is read. Any icons given to extensions in this file overwrite the icon from the previous two files. (If your theme changes the icons from tree.c and viewers.config are restored before loading the new .icons file.)

NOTE: Due to the way the icons are asked for in the code, you cannot change the icon for file types which all have the same FILE_ATTR_* value set (e.g. all audio files will have the same icon that has been defined for mp3). You can change the icon for all of these files by setting the icon for the first type which uses the ATTR.

The Gallery

Icon sets can be found on the IconSets Wiki page. Existing icon sets can be very effective learning tools, why not look at some examples?

r14 - 02 Apr 2021 - 20:46:06 - UnknownUser

Copyright © by the contributing authors.