Creating Themes

This page explains the process of developing theme files for delivery to users for use with ZipThemer and/or MetaMorph.

The theme is a zip file with a special directory structure and one or more XML "theme control files" in the root of the zip.

The goal of ZipThemer is "system theming" -- e.g., to modify resources such as images, etc, inside system applications and files. Almost all system files that you would want to modify for theming are either APK or JAR files. Both of these file types are just Zip files with specific internal content and structure. Both can be processed using normal Zip file utilities -- for example, to list the contents, etc.

Compared to MetaMorph Theme Development

If you're already familiar with the development of MetaMorph theme files, then there won't be much new to learn for ZipThemer. This section compares the differences.

ZipThemer performs the same function as the MetaMorph application but in a different way. MetaMorph modifies system files on the device directly, whereas ZipThemer creates an update zip file which, when flashed, applies the changes to the system files.

Both applications require the same folder structure inside a theme zip file. The only differences are with the XML theme control files used by the application to provide the user with options and information regarding the theme installation, and allow the application to process the entries contained in the zip while patching files.

In MetaMorph the name of the theme control file must match the name of the containing zip file, but with an .xml extension -- e.g., MetaMorph looks for "HtcBlackStatusBar.xml" in the theme file.  On the other hand, the ZipThemer XML control file is always named "zip-themer.xml". Since the folder structure is the same and the control files have different names, it is possible to create theme files that work well with both applications by simply including both control files in the zip file.

Folder Structure

Each top-level folder in the zip must have a name that matches the basename of a system file to be patched, minus its file extension.

For example, if your theme modifies the icons in the calendar app and its pathname is /system/app/Calendar.apk, then the basename is "Calendar.apk". Remove the extension and we're left with "Calendar".

Case is important, so in the example above the folder must be named "Calendar" and not "calendar".

My HtcBlackStatusBar theme modifies icons in the following system files:

  • /system/app/Calendar.apk
  • /system/app/Mms.apk
  • /system/framework/framework-res.apk

In the root of the HtcBlackStatusBar theme file are the following folders

  • Calendar
  • Mms
  • framework-res

The contents of each of these folders contains the same directory structure as the system file to be patched, but only the files necessary for patching.

Continuing with the same example, HtcBlackStatusBar updates the status bar notification icon for calendar events. If the Calendar.apk file is unpacked you'll find lots of files, but only one notification icon, and with the path:


The theme-modified version of this file must have the following path within the theme file:


In a nutshell, the process of building the theme content involves the following steps: - Extract system files containing images you want to modify. - Find and modify the images - Move the updated version into a folder that begins with the system file basename (minus extension), followed by the same parent folder names as it had inside the system file.

Theme Control XML Files:

Your theme file must have one or more XML files in the root.  You can add one or both of the XML format files for compatibility either or both of MetaMorph and ZipThemer.  Your theme will be compatible with both installers if you only include the MetaMorph XML file.  If you want to take advantage of the unique features of ZipThemer you'll need to include the ZipThemer XML file.

Click here to continue reading on the ZipThemer XML Format or the MetaMorph XML Format.