Developer Blog – The CyanogenMod Theme Engine

Today we have a guest post from CyanogenMod contributor, Cyanogen Inc. employee, and co-author of the new CM Theme Engine to provide a brief overview of how the Theme Engine works. Please welcome Clark Scheff. – ciwrl

CyanogenMod makes it easy to quickly customize & change the look of your UI, allowing you to really make your device your device.  As someone that loves to tinker, I like to know how things actually work and I wanted to explain how themes actually work in CyanogenMod.

At the most basic level, themes are simply a mechanism to allow resources to be replaced at runtime (as opposed to compilation time – the time when the build is created on the buildbots).

I’ll get into more details about resources, but for now just think of them as the elements which make up the application’s UI.  Whenever an application is started, Android loads up the resources associated with that app and the application makes requests for these resources.

Stock Resource Flow

That’s the normal flow of retrieving resources, but what happens when a theme is applied?  When the system loads the resources for the application, it checks if there is a theme applied and if there is, it adds the themed resources to the original resources.  This is the point at which the magic happens.  When the app requests a resource, the system will check if there is a themed version of it and if so, returns the themed resource, and if not it simply returns the original.  The key point here is the original resources are never modified/moved/altered, the system simply returns a resource from the theme instead of the original.  As you can see in the diagram below, there is no difference as far as the application is concerned.

CM Resource Flow

I’m sure by now you’ve realized that this process doesn’t actually involve any actual magic, so how does the system know which themed resource to replace an application resource with?

This is done by leveraging a framework known as Runtime Resource Overlays, which was contributed to AOSP by Sony in 2014. Part of the RRO framework is a tool called IDMAP.  IDMAP inspects the resources in an application and compares the resource types and names to those in the themed resources.  For those resources that match it stores a mapping of the original resource to the matching resource in the theme.  Once this process is complete we are left with an efficient way to determine if a resource is themed and where that resource resides.

Okay I’ve put off getting into more detail about resources long enough so let’s dive in.

Resources can range from images such as JPEGs or PNGs, XML that defines how things should be laid out on the screen, XML that define various color values that can be used to color text or highlight buttons, and even more XML that describe animations.  The list goes on but there are a couple of resources that warrant a bit more explaining.  One of those is the nine patch image.

A nine patch is a PNG image that has special markers around the borders that tell Android how it can stretch and place content within the image.  Because analyzing those borders at runtime would take a bit of unnecessary processing, the image is processed and the border is removed and encoded into the image at build time.  Android can then quickly read that information and know exactly how to handle the image.  Android also likes to have all the plain text XML that the application developer has written converted it into a more efficient binary format that can be read a lot faster at runtime.  The final step that needs to be done to the resources is to create a special file that indexes all of the applications resources so that they can be quickly retrieved by the android framework.  Fortunately this is not a manual process, as there is a tool called the Android Asset Packaging Tool, AAPT for short.

Now that we’ve got an understanding of how themes work at the framework level, and we know what resources are and what makes Android resources so special, let’s look at what makes our Theme Engine so unique.  With the original implementation of the RRO (from Sony), for every application that you wanted to theme you needed to create a theme just for that app.  Sony’s method also doesn’t account for items like changing fonts, or some of the XML elements – it is primarily just overlays. We wanted theme designers to be able to theme multiple applications for many more elements, just like they were able to do in the legacy theme engine from T-Mobile.

Every application has a unique name, known as the package name, that identifies it.  Fortunately Android has one place, an assets folder, that allows us to put all sorts of files and even create directories that can be accessed later by the application and by using directory names that match the unique package name of an application, a theme designer can include resources for many applications, all within one theme.  This was great but there was one problem.  Anything you place in these locations does not get processed like all the other resources do when an application is be built.  This meant we either needed to require the theme designer use special tools or go through a painstaking process just to get the resources created in the format Android likes, or we could let them easily drag and drop their themed resources into these folders and let the device do a bit of the heavy lifting at install time.  This is a very simple and convenient way for someone to create a theme without jumping through a lot of hoops, but that doesn’t mean a nice tool to create an efficient theme out of the box is out of the question ;).  Letting the resources remain in their original format means we had to come up with a way to keep Android happy and not lose any of the efficiency that RRO provides.  To accomplish this we actually have a version of aapt that runs on the device, and is part of every CyanogenMod build.  When the theme is installed a special service goes through and creates the indexed resource file as well as processes the nine patch images and the XML.  We store this file on the device and that is what provides the themed resources that can be attached to an application at runtime.

There is one last topic I want to cover before I wrap things up.  Because we are allowing other designers to provide their themes to all the users, we had to make sure that themes were kept under control.  This meant we had to make sure some resources just could not be themed – things like textual resources or resources that provide the UI layouts, to name two of the big ones, should not be themed.  A malicious theme could easily replace the text of an app to make it appear like another app, aka spoofing.  An app could get updated and changed their layout and an old theme that is theming that layout could end up crashing the app.  We also have to make sure that if a theme omits some important resources or parts of resources  (eg. an incomplete theme), that we bring those in from the original Holo/Material themes.

We have a lot going on under the hood to try and maintain the peace between applications and the themes that give them a fresh coat of paint.  And just in case something does cause an app or apps to misbehave, we have a mechanism in place that will monitor for this and return the user to the default system theme so they can continue to use their device.

I believe our journey today has come to an end so I leave you with these parting words.  CyanogenMod is community driven and all this cool stuff I talked about has been provided to the community as open source! If you have ideas for improvements, find bugs/fixes or just want to take a look at the code, everything is available on the CyanogenMod Github. If you are interested in creating a theme, checkout the Theme Template to get started!


“Awesome stuff! We’d like to thank Clark (|0xD34D|) for taking the time to give us a detailed overview. If you are a fan of this type of post, let us know in the comments – we’ll try and get a more holistic approach to content on this blog. -ciwrl”

  • CJ S

    cant wait for CM12 for my HTC ONE X!

  • fiaw

    waiting CM12 for aries

  • ibrahim biten

    I think kitkat ui is way better then lollipop. But it is my opinion. There is more lollipop fans out there than kitkat.

  • ibrahim biten

    If you are not on the list then you dont have an official maintainer. Search for xda… Maybe you have unofficial maintainers like my little i9100 😉

  • samo733792

    I install this firmware on my phone but it’s warking very slowly.
    Khow i us him but i hope they will bring oficiall cm12.

  • G££K PRINC£

    Its not gonna happen; dont you get it?

  • Xypher

    Nightlies are available already, try them.

  • RASE

    I have yureka mobile with cyanogen os? when I use to try the OTG
    pendrive it will detect and copy to phone from OTG pendrive. But I can’t
    able to copy from my phone to OTG pendrive. It will asked to root my
    phone. Please tell how can I do this?

  • RASE

    I have yureka mobile with cyanogen os? when I use to try the OTG
    pendrive it will detect and copy to phone from OTG pendrive. But I can’t
    able to copy from my phone to OTG pendrive. It will asked to root my
    phone. Please tell how can I do this? Please send a reply as soon as possible.

  • Peter Wilhelmsson

    No need to be. The switch from Dalvik to AVR (which I believe is the culprit) is a nightmare on quite a few devices (my own Nexus 7 included). Had to turn off all location-stuff, turn off all animations and all automatic updates, and sometimes I still have to wait with a frozen home screen after waking the damn thing up. Until I turned all automatic updates off, waking the pad up could take anything from 30 seconds to ten minutes, I shit you not. Ten. Effing. Minutes.

  • Peter Wilhelmsson

    Lolipop *IS* slow. I’m seriously considering completely wiping my Nexus 7 and install a 4.4-ROM on it and call it a day.

  • Peter Wilhelmsson

    Because you haven’t spent your own time making it.

  • aenews

    Did you factory reset? I’d back everything up and factory reset.

  • AymericM – DPlayDzN

    Please, give us CM12 on i9305 !

  • Nikhil

    What about Tab 2 ..?

  • Johnny Javier Velez Franco

    Give us CM12 for i9500

  • exzrael

    Cyanogenmod 12 works perfectly well with my Samsung Galaxy S4. Best upgrade ever in my oppinion. Very few crasches, no glitches that I can think of and everything feels snappier then with KitKat.

    I run a nightly (2015-01-25) and I will stay with this one until they release a more stable version. Good work guys!

  • crosschris richards

    The camrea have stop working completely an bluetooth wend playing music thought my speaker the volume turn up for it self need fixing..

  • Tomas Holik

    Hi, I run still on CM11 last nightly from december.
    Could I install this new version from OTA without some extra settings or backups or deleting caches? Thanks for quick reply.

  • Jensen

    Hi CM, now we have seen many devices have eaten the CM-12 nightly,but some of them are not included, will you give us a list to show us which one will eat the CM-12 ? so that we will know if our device will have this chance, as now my device that I9100G is receiving CM-11 always, does it mean my device can’t ?

  • exzrael


    I was not able to do so. I had to make a completely fresh install with eventyhing wiped.

    Best Regards

  • Vincenzo Romano

    So, in order to change my lockscreen wallpaper I “just” need a new multimegabyte theme!
    Since a few latest nightlies I cannot set an all black wallpaper as I used in the past.
    This doesn’t sound like an advancement to me.

  • SemarY

    when the fuck cm12 will be release for gt-i9500 ???????????????????????????????????????????????????????????????????????????????????????????????????????????????????????

  • yob doog

    Could you tell me which one of CM11 nightly builds is M12 for xperia m (nicki) ??? tell me the build number plzzzz!! And one more question is when I installed CM 12 on my xperia m dual C2005 my device didn’t find any sim card in both slots !!!!(EMERGENCY CALL ONLY)

    plz help me!! I LOVE CM 12 BUT…….

  • St_Holyshi

    CM 12 for d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte! d2lte!

    Any month now!

  • Peter Wilhelmsson

    Did bubkiss. I’ve switched to CM11 instead. Instantly several times faster.

  • Simone Malacrida

    Sony Z3 support?

  • Ricardo De Angelis León

    Hi! Who knows about the CM12 snapshot release date? At least an stimate, thanks.

  • vaishal

    there is no custom rom for my sony xperia t2 ultra dual, i want it

  • Da Kong

    I installed CM12 on my 2012 Nexus 7 after a disastrous “upgrade” to Lollipop that killed the performance and seemingly irrevocably changed the UI to be different from the 12 other Android devices I have. I have been trying for a week to find a way to go back to the KitKat UI (especially the navigation buttons & keyboard), and cannot find it. Anyone have any thoughts?

  • Parks J Daniel

    great thing..

  • Richard Sequeira

    Oh I don’t have to. I have a Nexus 6 White.

  • Siddhant Singla

    Collections in theme app showing ‘no result’ all time
    Pls help

  • Fella Sheamus

    Do you know how to change governor from “performance” tab on settings on cm12? i have to use no frills cpu but doing so i can’t use performance profiles like in cm11s

  • Vural GÖZÜKARA

    CM12 for galaxy s2 I9100???

  • scoty

    Is anyone have issuers with the 2/22

  • scoty

    I have the s4 schr 970 us cell I rooted my phone and flashed lollipop cm 12 imrumning 1-30 update it works like a charm but the 2-22/Google play not working ?

  • Krovius

    Settings > Battery. You’ll find the option there. CM11S had had that and the profiles thing too but they’re both pretty much the same thing.

  • Fella Sheamus

    yeah i know but if i choose battery save balanced or performarce the governor is always interactive(that causes shuttering and lag)

  • joakin2k

    Stable !!! a stable rom , when !!?

  • Nguyễn Văn Lắm

    we are awaiting updates CM12 for “Amazon Tate” (kindle fire hd 7 version 2012)

  • Prince Vicky

    why no official lolipop roms for s3 I9300

  • TheRealChx kay

    Ok. I need some help y’all. I’m running CM12 on Note 2 (Verizon) but I don’t see my Theme Chooser anywhere. I tried downloading a theme but I get “CyanogenMod Theme Chooser was NOT installed or configured correctly”

    I’m using the pico gapps package. Does it have to do with this?

  • vijer

    Is it possible to get an updated theme template that Android Studio doesn’t complain about? Also, some additional instructions for theming the system UI.

  • vijer

    The cunts ant cyanogen never read comments. Either that or they just don’t give a shit and don’t reply.

  • Dee Doe

    When i download themes they dont show up so i cant apply them. Im running cyanogenmod12 on a samsumg galaxy S5. Can anyone help me

  • Murali

    Unable to change fonts installed form playstore. Installed fonts are not loaded in Themes options. my rom version is CM12.1.