Fork us on GitHub

Migrating Legacy Applications to CSS

Adding CSS support to legacy applications is easier than you think
Migrating Legacy Applications to CSS

Migrating Legacy Applications to CSS

If you have an existing Codename One app that uses the designer for its theme, then you may have been reluctant to try to migrate it to CSS. Codename One projects are assumed to be using either CSS or the designer for their themes. But not both at the same time. When an app has CSS enabled, it compiles the css/theme.css to src/theme.res when the app is built, and it is kept in sync when changes are made to the theme.css file. Changes that you make manually to the theme.res file, would be lost the next time it synchronizes with the theme.css file. This doesn’t jive with legacy projects where you have customized the theme.res using the designer.

I don’t blame you if you don’t feel like converting your theme.res file into CSS. After years of customization, a theme.res file may contain hundreds of images and styles. In addition, if your app is using the old GUI Builder, your theme.res file may include actual form designs, which can’t be migrated to CSS.

Fortunately, there is a way to add CSS support for your application without having to lose all of your work. Codename One allows you to “layer” themes over top of each other, thus allowing you to use multiple themes. It does this, for example, if you are using the native theme in your app. It uses the native theme for the platform as a base, but overrides it with the styles in your app’s theme.


  1. Before you begin, make sure that your theme.res is not currently opened in the designer.

  2. Rename your "theme.res" file to "theme_legacy.res" (This is found in the src directory)

    Change theme.res to theme_legacy.res
  3. Delete the res/theme directory, and the res/theme.xml file from your project.

    Delete the res/theme directory and res/theme.xml file
  4. Open the theme_legacy.res file in the designer.

  5. Under theme constants, add the constant “OverlayThemes”, with a value of “theme”.

    Set OverlayThemes constant

    Then Save

  6. Open your app’s main file, and find where the "theme.res" file is loaded. Look for a line like:

    theme = UIManager.initFirstTheme("/theme");

    And change it to

    theme = UIManager.initFirstTheme("/theme_legacy");

    If your app is an old GUI Builder app, then it might be new StateMachine(“/theme”) instead.

    Change the theme reference in you app main class


  7. Open Codename One Preferences.

    Click on CSS support
  8. Click on “CSS Support”

    Activate CSS now
  9. Click “Activate CSS Now”

    The screen should then change to a menu as shown here:

    CSS menu after activating CSS
  10. Press “Open CSS File For Editing” Open the CSS file for editing, and make a change that you’ll definitely notice, for testing. Here I’ll just change the color of labels to “Green”.

    Editing CSS File
  11. Save the CSS file, and run your project.

    You should see the CSS take effect. In my example, my label is now green.

    App running in simulator with CSS applied

What did all this do?

This tells the app to load your theme_legacy.res file instead of theme.res. Because of the “OverlayThemes” constant in your theme_legacy.res, Your app will automatically load the theme.res file’s styles over top of your legacy theme. The theme.res file will then be generated from your css/theme.css file, and kept in sync.

Share this Post:

Posted by Steve Hannah

Steve writes software for Codename One. He is an open source enthusiast who loves to tinker with new technologies.