This article describes how to create and use an new appearance theme. This is achieved by inheriting from qooxdoo’s default appearance theme qx.theme.appearance.Classic. It is recommended to create a new appearance theme, usually by inheriting from an existing one, rather then directly manipulating the themes that are included in the qooxdoo framework.

First of all you define your new appearance theme class. Here’s an example of an empty appearance theme class. The several parts are explained afterwards.

qx.OO.defineClass("myApp.theme.appearance.myThemeName", qx.theme.appearance.Classic,
function(vTitle) {
  qx.theme.appearance.Classic.call(this, vTitle || "My Appearance Title");
});
 
// Define appearances
qx.Proto._appearances = qx.lang.Object.carefullyMergeWith( {
  /*
   * My custom appearance settings here
   */
}, qx.Super.prototype._appearances);
 
// Singleton instance getter
qx.Class.getInstance = qx.lang.Function.returnInstance;
 
// Register the appearance theme to the appearance manager
qx.manager.object.AppearanceManager.getInstance().registerAppearanceTheme(qx.Class);

The declaration of the full namespace myApp.theme.appearance.myThemeName is not necessary, but the theme.appearance part of the namespace follows the qooxdoo framework style. You can organize your class structure of course in other way. In this example, the fully-qualified class name would correspond to a file myThemeName.js in the directory myApp/theme/appearance/.

qx.Proto._appearances = qx.lang.Object.carefullyMergeWith( {
  // your settings here
}, qx.Super.prototype._appearances);

This is the place where your appearances live. Here you can actually add new or change existing appearances to suit your needs.

For minor changes at existing widgets you can easily add/change the appearance defined by the Classic theme. The following example will add a blue background to all label widgets:

"label" : {
   setup : function() {
     this.backgroundColor = new qx.renderer.color.ColorObject("#0000FF");
   },
 
   initial : function(vTheme) {
     return {
       backgroundColor: this.backgroundColor
     }
   }
}

If you need major changes to a widget or changes that are only affecting specific widgets it is recommended to create an own appearance (e.g. you want to set a different background color to a specific widget) to outline them compared to the default appearances. To get more information about manipulating appearances take a look at the appearance article.

// Singleton Instance getter
qx.Class.getInstance = qx.lang.Function.returnInstance;
 
// registering the appearance theme to the appearance manager
qx.manager.object.AppearanceManager.getInstance().registerAppearanceTheme(qx.Class);

At last it is needed to declare the appearance theme as a singleton and to add it to the appearance manager in order to use this appearance theme.

After you created your new appearance theme you need to make sure that it is used by your application. You can achieve this with two different approaches:

• at application startup
• at application generation

To set the appearance theme at application startup you can use the initialize method of your application. The declaration of

qx.Proto.initialize = function(e)
{
  qx.manager.object.AppearanceManager.getInstance().setAppearanceTheme(new myApp.theme.appearance.myThemeName);
};

will set your appearance theme as default at runtime.

As second approach you can use the option –define-runtime-setting of the generator to set the appearance theme. This will lead the generator to create custom-settings which will be used right before the framework and application classes will be loaded.

The call of the generator with the given options will generate your application with the required framework classes and your appearance theme as default theme.

./generator.py \
   --define-runtime-setting qx.manager.object.AppearanceManager.appearanceTheme:myApp.theme.appearance.myThemeName \
   --class-path FRAMEWORK_SOURCE_PATH/class \
   --class-path APPLICATION_SOURCE_PATH/class

Bold Text