Substance client properties

Client property name

Description

Client property name for specifying the colorization amount applied to the background and foreground of the current color scheme and the specific control. By default, when the application does not use any custom colors, all the controls are painted with the colors of the current theme / skin. The colors coming from the look-and-feel implement the marker UIResource interface which allows the UI delegates to differentiate between application-specific colors which are not changed, and the LAF-provide colors that are changed on LAF switch.

This new client property installs the "smart colorization" mode which uses the colors of the current color scheme and the custom background / foreground colors (when installed by application) to colorize the relevant portions of the control. For example, on checkbox the custom background color will be used to colorize the check box itself, while the custom foreground color will be applied to the check box text and the check mark.

The value of this property specifies the actual colorization amount. Value of 0.0 results in Substance completely ignoring the custom application background and foreground colors set on the components - no colorization. Values closer to 1.0 result in almost full usage of the custom application background and foreground colors set on the components. Note that in order to maintain the gradients (fill, border, etc), even value of 1.0 does not result in full custom color being applied to the relevant visuals of the control.

This property can be specified globally on UIManager, applying on all controls, or on the specific component / container. In the later case, the value will be applied to the component / container itself and all its children that do not specify a custom value for this property.

The default colorization amount (when this property is not set at all) is 0.5. This means that applications that install custom background / foreground colors on their UI controls will see them colorized with 50% "strength", even without setting this property.

The value should be an instance of Double in 0.0-1.0 range.

Note that components in decoration areas registered on the current skin will ignore the colorization on custom background color. The background of such components is always painted by the skin's decoration painter to ensure consistent background painting of the relevant decoration area.

See also

Sample code

import java.awt.*;

import javax.swing.*;
import javax.swing.event.ChangeEvent;
import javax.swing.event.ChangeListener;

import org.pushingpixels.substance.api.SubstanceLookAndFeel;
import org.pushingpixels.substance.api.skin.BusinessBlackSteelSkin;

/**
 * Test application that shows the use of the
 * {@link SubstanceLookAndFeel#COLORIZATION_FACTOR} client property.
 * 
 * @author Kirill Grouchnikov
 * @see SubstanceLookAndFeel#COLORIZATION_FACTOR
 */
public class ColorizationFactor extends JFrame {
  /**
   * Creates the main frame for <code>this</code> sample.
   */
  public ColorizationFactor() {
    super("Colorization factor");

    this.setLayout(new BorderLayout());

    final JPanel panel = new JPanel(new FlowLayout());
    JButton button = new JButton("sample");
    button.setBackground(Color.yellow);
    button.setForeground(Color.red);
    panel.add(button);
    JCheckBox checkbox = new JCheckBox("sample");
    checkbox.setSelected(true);
    checkbox.setBackground(Color.green.brighter());
    checkbox.setForeground(Color.blue.darker());
    panel.add(checkbox);
    JRadioButton radiobutton = new JRadioButton("sample");
    radiobutton.setSelected(true);
    radiobutton.setBackground(Color.yellow);
    radiobutton.setForeground(Color.green.darker());
    panel.add(radiobutton);

    this.add(panel, BorderLayout.CENTER);

    JPanel controls = new JPanel(new FlowLayout(FlowLayout.RIGHT));
    final JSlider colorizationSlider = new JSlider(0, 100, 50);
    colorizationSlider.addChangeListener(new ChangeListener() {
      public void stateChanged(ChangeEvent e) {
        double val = colorizationSlider.getValue() / 100.0;
        panel.putClientProperty(
            SubstanceLookAndFeel.COLORIZATION_FACTOR, new Double(
                val));
        panel.repaint();
      }
    });
    controls.add(colorizationSlider);

    this.add(controls, BorderLayout.SOUTH);

    this.setSize(400, 200);
    this.setLocationRelativeTo(null);
    this.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
  }

  /**
   * The main method for <code>this</code> sample. The arguments are ignored.
   * 
   * @param args
   *            Ignored.
   */
  public static void main(String[] args) {
    JFrame.setDefaultLookAndFeelDecorated(true);
    SwingUtilities.invokeLater(new Runnable() {
      public void run() {
        SubstanceLookAndFeel.setSkin(new BusinessBlackSteelSkin());
        new ColorizationFactor().setVisible(true);
      }
    });
  }
}

The screenshot below shows application frame with a button, a checkbox and a radio button. All three have custom (non-UIResource) background and foreground colors. When this client property is not set, the default colorization value of 0.5 is assumed:

The same application with this client property set to 1.0 on the panel that contains these three controls. Note how the colorization preserves the fill gradients:

The same application with this client property set to 0.25 on the panel that contains these three controls.