Chameleon > Theme Park

Creating Themes Guide - Updated for v2.1 rev1994

(1/17) > >>


Creating themes for the Chameleon bootloader

First of all, I want to congratulate the Chameleon team for all their hard work creating this fantastic bootloader which features a customisable GUI. Thanks also to fassl for helping me get my head around some issues and thanks to Zef and meklort for believing in the rollover feature enough to implement it properly ;)

Guide update - 7th June 2012

Chameleon v2.1rev 1994 now includes icon support for Mountain Lion. This builds upon the previous GUI changes that were introduced in February with rev1738 where Chameleon's GUI gained the ability to distinguish between different versions of OS X and reflect that by using specific device images.

I'm updating this guide to give more information about the additional graphic files and as I did before, taking the opportunity to make any other changes to keep it current. And since rocksteady upped the max character limit for posts, I can now extend this guide to make it more detailed.

Previous guide update - 26th August 2010

I think this guide has served it's purpose well for the last 16 months from when I first made it, but there have been some changes to the GUI in the upcoming RC5 which warrant an update of the guide and it also gives me a chance to add, tweak and amend the existing guide to make it more complete. Thanks to everyone who commented on the guide and gave feedback to help improve it.

RC5 can now draw a different image for the device icon when the user highlights that device in the GUI. This gives it rollover functionality and can be used to great effect to give the interface more feel. I used the effect in Chameleon's new default theme to indicate the selected device with the changing of the LED colour. The device_selection graphic can still be used in combination with the rollover devices and is still drawn below the highlighted device, though I chose to use a blank device_selection for the new default Chameleon theme.

The rollover devices are identified by the bootloader by having a '_o' at the end of the filename, before the extension. So for example, the optical drive is normally shown with the graphic device_cdrom.png, where as to add a rollover image for the optical drive, a new image is needed and that shall be named device_cdrom_o.png.

The rollover devices don't have to be used and if they're not in the theme folder then the bootloader will just draw the non-rollover device image instead, as you would normally see with current themes.

An explanation of a theme

A theme is a folder of files which the bootloader can read and load to present a graphical user interface to the user and when all the available items are used to their full, a theme can create a dramatic screen not seen in any other bootloader.

I like to class themes in to two different categories, flexible and rigid. This is important to understand as flexible themes are easier to use on multiple systems where as rigid themes might need altering to fit a different resolution other than it was designed for. If I were to try to define each category, it would come to something like this:

Flexible theme: One that doesn't use a full-screen image such as a background, doesn't have any element too close to the edge of the screen and it's elements can be determined as floating (or don't need to be in any exact location on the screen).

Rigid theme: One that uses a background image and/or requires the device icons, menu etc. be to in a specific location on the screen to achieve an overall effect.

Theme elements

Themes are made from a set of .PNG files for the images and a theme.plist which contains properties describing the various details for each theme element. for example positioning, levels of transparency, screen size.

As Chameleon has evolved, so has the number of supported files used in it's GUI. You can use Chameleon's revision identifier to know what graphic files are supported in that version:

Chameleon v2.1 rev1994 added GUI support for 10.8 (aka Mountain Lion) by using four extra files, bringing the total number of files for a complete theme to 64 (63 .PNG files and 1 theme.plist).

Chameleon v2.1 rev1738 was updated to use a set of 60 files to describe a complete theme (59 .PNG files and 1 theme.plist). The additional files over previous versions are for displaying different OS installations which Chameleon can now distinguish. For example, Haiku, FreeBSD, OpenBSD and the different flavours of OS X from 10.4 to 10.7.

RC5 (which eventually evolved to be the official v2.0 release). This version used a set of 38 files (37 .PNG files and 1 theme.plist) because of the introduction of using a separate graphic per device to show it's selected state (aka the rollover effect). RC5 no longer used separate image files for device_fat16 and device_fat32 as it classed them both as device_fat and device graphics were added for the GUI to show RAID drives.

RC1-RC4 used a set of 31 files (30 .PNG files and 1 theme.plist).

To ease identification, individual files can be grouped in to 9 sections as shown in the following table which shows the theme files used for each major theme upgraded version of Chameleon.

Note: Please see the bottom of the post for details of an application 'Lizard' by sonotone which can make use of 1 x additional PNG file named thumb.png in the theme folder to serve as a preview image of the theme.

Screen resolution

Resolution of Chameleon's GUI
The bootloader will recognise a range of available resolutions from your system and these can be seen by selecting the ‘Video Info’ option from the options menu. Only these resolutions can be used to display the theme at boot. To find out more abut identifying the screen resolution that Chameleon is using on your system, see here. Ultimately though, Chameleon will draw the GUI at the best screen resolution it can for your monitor based around the resolution it finds defined in the GraphicsMode boot option in to

Resolution of a theme
The theme.plist holds values entered in the screen_width and screen_height fields to identify the resolution the theme is designed for, but the bootloader will always draw the theme in to the resolution it's selected for the GUI regardless of the screen size set in the theme.plist. This will normally go unnoticed when using a 'flexible' theme, but will be obvious when using a 'rigid' theme.

Lets see how a theme will look at it's intended resolution and when used at a different resolution, so for this example we will use Chameleon's new default theme, which we can say is a 'flexible' theme. It has screen_width & screen_height values set at 1024x768 in it's theme.plist and here's how it renders in the GUI when drawn at both 1024x768 and 1680x1050. 

To also enable a theme to better accommodate a different resolution, the developers have sensibly allowed themes to use relative positioning for their elements, so from one screen resolution to another, apart from the size of the graphics, everything should be positioned more or less the same regardless of screen size. Notice that when the theme is drawn on the 1680x1050 pixel grid the theme elements are still positioned correctly. This is due to the relative positioning described in the theme.plist. 

The same doesn't happen though for a 'rigid' theme, and next we look at a theme that uses a full screen image for the background. While background images can spice up a theme and greatly enhance the overall effect, they require the user to manually resize the image to fit the desired screen resolution as Chameleon isn't able to resize images. So if using a theme sized 1024x768 with a matching sized background image on a 1680x1050 screen then the background will still draw as 1024x768 with the remainder of the pixels filled with the colour specified in the screen_bgcolor field in the theme.plist.

You can see this happening in the next example which is showing OcciJano's lovely 'Like a Mac' theme. It was designed for a resolution of 1280x1024 and here's how it renders in the GUI when drawn at both 1280x1024 and 1680x1050.

In this case it’s up to me, the end user, to resize the graphics to fit my screen resolution.

The resizing process can be greatly aided by the theme designer if they think about other resolutions than just their own. After some trials I recommend supplying three different sized themes using the ratios of 16:10, 16:9 and 4:3 designed at a high resolution which will allow anyone to resize the theme to fit their required resolution whilst keeping the intended shape. So in the above example of OcciJano's theme where it's just the background that doesn't work at different screen sizes, he could have supplied a higher-res background image which I could then crop/scale to fit my display without loss of quality. Instead the only options I have is to either A) not use a background image, B) resize (make larger) the supplied one to fit my screen which will decrease the quality of the image or C) create a new background or use a different image.


The properties in this list describe positional, colour, size and transparency information for the individual elements that make up a theme.  Also note how the list is nicely broken down in to sections to make it easy to read and find particular items. Please try to keep this default order because changing it just makes it harder to quickly locate items.

(Note: items in red are because at the time of writing I can’t remember if that’s the exact edge used, for example, logo_pos_y could be positioned by the bottom edge not the top edge)

Theme elements, what they're used for and where

I have created a series of illustrations to show what each graphic is and where it is intended to be used. But when designing a theme, feel free to place different sections where you want as who's to say the logo has to be at the top middle of the screen? or that the menu has to be centred at the bottom?
Note: Items in blue can all be found in the theme.plist, items in BOLD are graphics. Fonts used are shown as red.

I have also included this positional guide to show how the values in the theme.plist relate to co-ordinates on the screen. (I found info for this in docs from the Chameleon SVN)

Image file format

The bootloader uses 24 bit PNG images with 8 bit transparency. Many applications allow saving files in this format. I use Photoshop’s 'Save for Web & Devices' file option which aims to keep the maximum image quality possible whilst using the smallest possible file size.  Here's a screen shot for reference:


Like the other graphic files, the fonts are also made as PNG files. Chameleon's GUI uses two fonts , font_small which is used to display the device names, and font_console which is used to display the menus and also the boot information generated by the bootloader and displayed in the top left of the screen.

They are created as a continuous string of characters in the following order.

Each character is then separated by a full red pixel (R:255 G:0 B:0) as you can see on the shipped themes. Here's a blown up section of the font_small graphic from the Chameleon default theme for reference.

Note: Be careful with fonts because in my many trials with different sizes etc, I have on occasion had a boot failure with a Memory Allocation (XXXX, Deadbeef) error, or something like that. I haven't discovered the exact reason why this happens but I have a feeling it's got something to do with having an incorrect number red dots in the file which means the booter will fail to recognise the correct characters. Sometimes you can get away with just seeing ciphered writing (e.g. APPLE might read BQQMF), or at worst the memory allocation error.  If this happens to you then you can recover by booting from another HDD with a Chameleon install, a bootable USB or a boot-132 CD.

The process of creating fonts has been simplified by cizko's fantastic FontMaker. You can find it at

Things you can’t control

Screen  A
The countdown text. i.e ‘Press any key to enter startup options’. This is hard coded in the booter and there is no option to change it.

Screen  B
The text in the top left hand corner of the device selection screen (screen B in the illustrations) is know as the 'boot banner' and serves a purpose of telling you what version the bootloader is. This text is hard coded in the booter and cannot be changed, though since the release of RC2 you can now turn this off in your /Extra/org.chameleon.Boot.plist (formerly /Extra/ by using the <key>Boot Banner</key> with the <string>No</string> option.

Screen  B
device_selection.png layer. The device_selection always gets drawn underneath the device. This is something to think about when designing how your theme will operate.

Screen  C
Menu wording. This is hard coded in the booter and can’t be changed to read anything different.

Screen  C
Menu size. This is set and can’t be changed to a different size.
UPDATE: I have discovered in the source code that you can use the key 'menu_width' to change the width of the menu.

Tips / Points to remember

• All the theme files must be present in the theme folder*, even if a certain image isn't used in a theme then it's necessary to supply a blank file. For example, with Chameleon's default theme, the background is supplied as an empty file.

* this has changed with RC5 as far as the device icons are concerned. So that includes most of the images in the 'Devices' section of the initial table in this guide. The only mandatory device icon is 'device_generic.png' as the booter is now able to use that icon for any device it can't find a graphic image for. The purpose of this is, if needed, the booter can be complied with an embedded theme but use only the minimum of resources.

• All devices MUST be the same size, though the device_selection.png can be different. See the shipped default theme for an example (thanks for the correction Enzo). Changing the size of the device_selection graphic can sometimes enhance the way a theme works / looks. For example, my blackosx_switch theme uses a glow around the rollover device. By using a device selection graphic that's thinner than the device icons allows the device icons to be drawn closer together, essentially overlapping, which enables the glow to seamlessly blend in to another device icon without ugly spaces between them.

• The device_selection.png is always drawn behind the devices.

• The devices_iconspacing in the theme.plist also has a role to play with the height of the devices cropbox*. I’ve noticed when playing with larger fonts that sometimes they get cropped at the bottom. This is due to the devices_iconspacing being too small. So, if you use larger fonts, you might need to increase the devices_iconspacing. See image below for an example.

* The devices crop box (that’s what I call it), the box that frames the devices, device_selection and device names, you can see it when the devices_transparency is not set to 255.

• If the devices_max_visible is set to 3 and the system has more than 3 devices then the device_scroll_next.png and device_scroll_prev.png graphics are automatically drawn either side of the devices.

• progressbar_width and progressbar_height don’t seem to have any effect.

• devices_layout in the theme.plist can be set to vertical and will display the devices vertically but the keyboard input doesn’t change to allow use of the menu.

Monitor calibration

Something else to remember if you use a calibrated display is that when the theme is drawn by the bootloader, no calibration profiles will be used. So if you use one when designing a theme, bear in mind how it will look without any adjustment.

Building and using your theme

When you have your idea you can start to build your theme. And remember, no ideas are dumb, they are individual and unique to each and every person, with no right or wrong. The more choice available, the better.

The recommended way to use themes is to put all the files in a folder, give the folder a name and add that folder in to the Themes folder. I recommend not using a space in the folder name, so for instance use something like 'My_Great_Theme'. Then edit the /Extra/org.chameleon.Boot.plist (formerly /Extra/ and add the Theme key/string to point Chameleon to your new theme, for example:

--- Code: ---<key>Theme</key>
--- End code ---

By default, without the Theme key/string, Chameleon will always read from the 'default' folder in the Themes folder.

I then photograph the screen at different stages to refer back to when adjusting the theme (otherwise I found I was rebooting again, cos I had forgotten things). Or if you are feeling more adventurous you can create a disc image .iso containing your theme which you can then load in to a VM (VMWare, QEMU, Parallels..) to see your theme in a window without rebooting. Using this method I was successful at getting to see the GUI but I never figured out how to add any other volumes for Chameleon to display so I only ever saw the CD-ROM icon. But it works :) (thanks Zef). For instructions on creating a Chameleon disc image for testing your themes using VMWare Fusion, see here.

Uploading your theme with image previews / thumbnail

Once you have tweaked and tested and are happy with the theme you can zip it up and uploaded it for everyone to see, along with a screen shot of the theme. For making a screenshot you have a couple of options. Personally, as I make my themes in Photoshop, I can easily save an image, but you can always reboot and see it in action when Chameleon draws it onscreen then take a photograph, or try creating a disc image and running in a VM as described above.

Please resize any images before uploading to respect the bandwidth of others and the storage space on the server. As a guide I suggest resizing screenshots to 800pixels wide.

You can now include an image to be used as a thumbnail for the theme in the main 'Theme Park' forum. For this you need to create a JPEG image sized at 200pixels wide and save it with the name thumb.jpg. Then attach it to your theme post where it will be automatically picked up by the forum software for displaying.

Supporting the Lizard app

Sonotone has released an application to assist with editing and tweaking your, SMBIOS.plist and managing themes. For themes, the application uses two extra key/strings in the theme.plist, and a thumbnail icon of the theme in the theme folder. The app has become quite popular now so it make sense for themes to support it. You can read about and find a download link here.

The two new key/strings are as follows.

You can add these anywhere in the theme.plist you like but it's easy to add them to the top like this.....

(obviously replacing Blackosx with your name)

The size of the thumbnail for the theme is 120 pixels square and should be saved as a .png format with the filename 'thumb.png'. Add it in your theme folder along with all the other devices etc.

Here's an example of what a finished thumb.png will look like...

I've attached a photoshop template 'Thumbs Template.psd' for the thumbs icon for reference.

Ah, exactly what I was looking for. I was wading through the Info.plist for too long in trial-and-error mode. Thanks!

Fantastic work Blackosx,

Pure quality post, thank you

Very nice Blackosx :)
We would want to include a PDF version of this in the next (or final) release, if you don't mind.


--- Quote from: rocksteady on May 26, 2009, 02:45:38 PM ---Fantastic work Blackosx,

Pure quality post, thank you

--- End quote ---

Thank you.

--- Quote from: Kabyl on May 26, 2009, 03:17:07 PM ---Very nice Blackosx :)
We would want to include a PDF version of this in the next (or final) release, if you don't mind.

--- End quote ---

Thanks also.
Yes I can supply a PDF. I might update it in the mean time, so let me know when you need it so you can have the most up to date version.


[0] Message Index

[#] Next page

Go to full version