Appearance¶

What is it?¶

An appearance theme is the main part of the theme. It contains all appearance definitions which are responsible for holding all styling information for the widgets. Usually the appearance theme is the biggest theme and uses all other theme classes like the Decorator- or Font-theme.

Theme Structure¶

A theme normally consists of a set of entries. Each entry has a key which is basically some kind of selector which matches to a specific widget. Missing selectors are presented as a warning when developing with debug code enabled.

qx.Theme.define("qx.theme.modern.Appearance",
{
  appearances :
  {
    selector : entry,
    [...]
  }
});

Selectors¶

In the most basic form each selector is identical to an appearance ID. This appearance ID is the value stored in the appearance property (API) of each widget.

The child control system ignores this appearance entry for widgets which function as a child control of another widget. In these cases the selector is the combination of the appearance ID of the parent widget plus the ID of the child control.

In a classic Button there is a child control icon for example. The appearance selector for the image element which represents the icon is button/icon. As you can see the divider between the appearance ID and the child control is a simple slash (/).

It is also possible that a widget, which is a child control itself, uses another child control. Generally the mechanism prepends the ID of each parent which is also a child control to the front of the selector. For example:

- pane
  - level1
    - level2
      - level3

the generated selector would be pane/level1/level2/level3. For pane which is not a child control of any other widget the appearance ID is used. For all others the child control ID is used. Again pane is not managed by any other widget so it is basically added by the developer of the application to another widget while level1 to level3 are managed by some type of combined widget and are added to each other without the work of the application developer.

A classic example for this is the Spinner widget. A Spinner is basically a Grid layout with a TextField and two RepeatButtons. The three internal widgets are available under the sub control IDs textfield, upbutton and downbutton. The selectors for these kind of child controls are then:

spinner/textfield
spinner/upbutton
spinner/downbutton

Each of these selectors must be defined by the selected appearance. Otherwise a warning about missing selectors is displayed.

Aliases¶

A entry can be defined with two different values, a string or a map. The first option is named "alias", it is basically a string, redirecting to another selector. In the Spinner example from above we may just want to use aliases for the buttons. See the example:

qx.Theme.define("qx.theme.modern.Appearance",
{
  appearances :
  {
    [...],

    "spinner/upbutton" : "button",
    "spinner/downbutton" : "button",

    [...]
  }
});

So we have mastered one essential part for appearance themes. It is basically the easiest part, but seen quite often. Compared to CSS you always have a full control about the styling of such an child control. There is no type of implicit inheritance. This may also be seen negatively, but most developers tend to like it more.

Such an alias also redirects all child controls of the left hand selector to the right hand selector. This means that the icon inside the button is automatically redirected as well. Internally this mapping looks like this:

"spinner/upbutton" => "button"
"spinner/upbutton/icon" => "button/icon"
"spinner/upbutton/label" => "button/label"

This is super convenient for simple cases and additionally it is still possible to selectively override definitions for specific child controls.

qx.Theme.define("qx.theme.modern.Appearance",
{
  appearances :
  {
    [...],

    "myimage" : [...],

    "spinner/upbutton" : "button",
    "spinner/upbutton/icon" : "myimage",

    [...]
  }
});

Internally the above results into the following remapping:

"spinner/upbutton" => "button"
"spinner/upbutton/icon" => "myimage"
"spinner/upbutton/label" => "button/label"

Entries¶

The more complex full entry is a map with several sub entries where all are optional:

qx.Theme.define("qx.theme.modern.Appearance",
{
  appearances :
  {
    [...],

    "spinner/textfield" :
    {
      base : true/false,
      include : String,
      alias : String,

      style : function(states, styles)
      {
        return {
          property : states.hovered ? value1 : value2,
          [...]
        };
      }
    },

    [...]
  }
});

Style Method¶

Let's start with the style sub entry. The value under this key should be a function which returns a set of properties to apply to the target widget. The first parameter of the function is named states. This is a map containing keys with boolean values which signalize which states are switched on. The data could be used to react on specific states like hovered, focused, selected, etc. The second parameter styles is only available if a include key is given. If so, the styles parameter contains the styles of the included appearance. This may be very handy if you just want to add some padding and don't want to change it completely. In any case, you don't need to return the given styles. The returned styles and the styles argument will be merged by the appearance manager with a higher priority for the local (returned) styles.

It is required that all properties applied in one state are applied in all other states. Something like this is seen as bad style and may result in wrong styling:

style : function(states)
{
  var result = {};

  if (states.hovered) {
    result.backgroundColor = "red";
  }
  // BAD: backgroundColor missing when widget isn't hovered!

  return result;
}

Instead, you should always define the else case:

style : function(states)
{
  var result = {};

  if (states.hovered) {
    result.backgroundColor = "red";
  } else {
    // GOOD: there should be a setting for all possible states
    result.backgroundColor = undefined;
  }

  return result;
}

Note

The undefined value means that no value should be applied. When qooxdoo runs through the returned map it calls the reset method for properties with a value of undefined. In most cases it would be also perfectly valid to use null instead of undefined, but keep in mind that null is stored using the setter (explicit null) and this way it overrides values given through the inheritance or through the init values. In short this means that undefined is the better choice in almost all cases.

One thing we have also seen in the example is that it is perfectly possible to create the return map using standard JavaScript and fill in keys during the runtime of the style method. This allows to use more complex statements to solve the requirements of today's themes were a lot of states or dependencies between states can have great impact on the result map.

Includes¶

Includes are used to reuse the result of another key and merge it with the local data. Includes may also used standalone without the style key but this is merely the same like an alias. An alias is the faster and better choice in this case.

The results of the include block are merged with lower priority than the local data so it just gets added to the map. To remove a key from the included map just define the key locally as well (using the style method) and set it to undefined.

Includes do nothing to child controls. They just include exactly the given selector into the current selector.

Child Control Aliases¶

Child control aliases are compared to the normal aliases mentioned above, just define aliases for the child controls. They do not redirect the local selector to the selector defined by the alias. An example to make this more clear:

qx.Theme.define("qx.theme.modern.Appearance",
{
  appearances :
  {
    [...],

    "spinner/upbutton" :
    {
      alias : "button",

      style : function(states) {
        return {
          padding : 2,
          icon : "decoration/arrows/up.gif"
        }
      }
    },

    [...]
  }
});

The result mapping would look like the following:

"spinner/upbutton" => "spinner/upbutton"
"spinner/upbutton/icon" => "button/image"
"spinner/upbutton/label" => "button/label"

As you can see the spinner/upbutton is kept in its original state. This allows one to just refine a specific outer part of a complex widget instead of the whole widget. It is also possible to include the original part of the button into the spinner/upbutton as well. This is useful to just override a few properties like seen in the following example:

qx.Theme.define("qx.theme.modern.Appearance",
{
  appearances :
  {
    [...],

    "spinner/upbutton" :
    {
      alias : "button",
      include : "button",

      style : function(states)
      {
        return {
          padding : 2,
          icon : "decoration/arrows/up.gif"
        }
      }
    },

    [...]
  }
});

When alias and include are identically pointing to the same selector the result is identical to the real alias

Base Calls¶

When extending themes the so-named base flag can be enabled to include the result of this selector of the derived theme into the local selector. This is quite comparable to the this.base(arguments, ...) call in member functions of typical qooxdoo classes. It does all the things the super class has done plus the local things. Please note that all local definitions have higher priority than the inheritance. See next paragraph for details.

Priorities¶

Priority is quite an important topic when dealing with so many sources to fill a selector with styles. Logically the definitions of the style function are the ones with the highest priority followed by the include block. The least priority has the base flag for enabling the base calls in inherited themes.

States¶

A state is used for every visual state a widget may have. Every state has flag character. It could only be enabled or disabled via the API addState or removeState.

Performance¶

qooxdoo has a lot of impressive caching ideas behind the whole appearance handling. As one could easily imagine all these features are quite expensive when they are made on every widget instance and more important, each time a state is modified.

Appearance Queue¶

First of all we have the appearance queue. Widgets which are visible and inserted into a visible parent are automatically processed by this queue when changes happen or on the initial display of the widget. Otherwise the change is delayed until the widget gets visible (again).

The queue also minimizes the effect of multiple state changes when they happen at once. All changes are combined into one lookup to the theme e.g. changing hovered and focused directly after each other would only result into one update instead of two. In a modern GUI typically each tap influence a few widgets at once and in these widgets a few states at once so this optimization really pays of.

Selector Caching¶

Each widget comes with an appearance or was created as a child control of another widget. Because the detection of the selector is quite complex with iterations up to the parent chain, the resulting selector of each widget is cached. The system benefits from the idea that child controls are never moved outside the parent they belong to. So a child controls which is cached once keeps the selector for lifetime. The only thing which could invalidate the selectors of a widget and all of its child controls is the change of the property appearance in the parent of the child control.

Alias Caching¶

The support for aliases is resolved once per application load. So after a while all aliases are resolved to their final destination. This process is lazy and fills the redirection map with selector usage. This means that the relatively complex process of resolving all aliases is only done once.

The list of resolved aliases can be seen when printing out the map under qx.theme.manager.Appearance.getInstance().__aliasMap to the log console. It just contains the fully resolved alias (aliases may redirect to each other as well).

Result Caching¶

Further the result of each selector for a specific set of states is cached as well. This is maybe the most massive source of performance tweaks in the system. With the first usage, qooxdoo caches for example the result of button with the states hovered and focused. The result is used for any further request for such an appearance with the identical set of states. This caching is by the way the most evident reason why the appearance has no access to the individual widget. This would interfere with the caching in some way.

This last caching also reduces the overhead of include and base statements which are quite intensive tasks because of the map merge character with which they have been implemented.

qooxdoo

Appearance¶

What is it?¶

Theme Structure¶

Selectors¶

Aliases¶

Entries¶

Style Method¶

Includes¶

Child Control Aliases¶

Base Calls¶

Priorities¶

States¶

Performance¶

Appearance Queue¶

Selector Caching¶

Alias Caching¶

Result Caching¶

» Next topic

« Previous topic

qooxdoo

Appearance¶

What is it?¶

Theme Structure¶

Selectors¶

Aliases¶

Entries¶

Style Method¶

Includes¶

Child Control Aliases¶

Base Calls¶

Priorities¶

States¶

Performance¶

Appearance Queue¶

Selector Caching¶

Alias Caching¶

Result Caching¶

» Next topic

« Previous topic

Quick search