Substance look and feel - overlay painters

The decoration painters are used to paint the entire background area of the relevant containers - such as menu bars, tool bars, panels etc. Overlay painters, on the other hand, add the final polish that usually affects relatively small areas at the edges of the relevant decoration areas. Substance also provides a set of published APIs for applications that wish to add visually consistent overlays to custom application containers.

Overlays

The overlays are best illustrated with screenshots. The following screenshot is a skeleton window under the Nebula Brick Wall skin:

This skin defines custom visual appearance for the title pane, the menu bar and the status bar - the background of these areas is painted by the matching decoration painter - in this case, the org.pushingpixels.substance.api.painter.decoration.MarbleNoiseDecorationPainter. To add the final polishing touch and create a unique visual footprint for this skin, we use a number of overlay painters:

The Nebula Brick Wall skin defines two separate overlay painters, each one associated with the relevant decoration areas:

    // add an overlay painter to paint a drop shadow along the top
    // edge of toolbars
    this.addOverlayPainter(TopShadowOverlayPainter.getInstance(),
        DecorationAreaType.TOOLBAR);

    // add an overlay painter to paint separator lines along the bottom
    // edges of title panes and menu bars
    this.bottomLineOverlayPainter = new BottomLineOverlayPainter(
        new ColorSchemeSingleColorQuery() {
          @Override
          public Color query(SubstanceColorScheme scheme) {
            Color dark = scheme.getDarkColor();
            return new Color(dark.getRed(), dark.getGreen(), dark
                .getBlue()160);
          }
        });
    this.addOverlayPainter(this.bottomLineOverlayPainter,
        DecorationAreaType.PRIMARY_TITLE_PANE,
        DecorationAreaType.SECONDARY_TITLE_PANE,
        DecorationAreaType.HEADER);

Here is the same skeleton window under the Gemini skin:

This skin defines custom visual appearance for the title pane, the menu bar, the toolbars and the status bar - the background of these areas is painted by the matching decoration painter - in this case, the org.pushingpixels.substance.api.painter.decoration.MatteDecorationPainter. To add the final polishing touch and create a unique visual footprint for this skin, we use a number of overlay painters:

The Gemini skin defines three separate overlay painters, each one associated with the relevant decoration areas:

    // add an overlay painter to paint a bezel line along the top
    // edge of footer
    this.footerTopBezelOverlayPainter = new TopBezelOverlayPainter(
        ColorSchemeSingleColorQuery.DARK,
        ColorSchemeSingleColorQuery.ULTRALIGHT);
    this.addOverlayPainter(this.footerTopBezelOverlayPainter,
        DecorationAreaType.FOOTER);

    // add two overlay painters to create a bezel line between
    // menu bar and toolbars
    this.menuOverlayPainter = new BottomLineOverlayPainter(
        new ColorSchemeSingleColorQuery() {
          @Override
          public Color query(SubstanceColorScheme scheme) {
            return scheme.getUltraDarkColor().darker();
          }
        });
    this.toolbarOverlayPainter = new TopLineOverlayPainter(
        new ColorSchemeSingleColorQuery() {
          @Override
          public Color query(SubstanceColorScheme scheme) {
            Color fg = scheme.getForegroundColor();
            return new Color(fg.getRed(), fg.getGreen(), fg
                .getBlue()32);
          }
        });
    this.addOverlayPainter(this.menuOverlayPainter,
        DecorationAreaType.HEADER);
    this.addOverlayPainter(this.toolbarOverlayPainter,
        DecorationAreaType.TOOLBAR);

This skin shows two different ways to add double-line bezel separators - the first between the menu bar and tool bar, and the second between the main application area and the footer:

The last example comes from the Twilight skin:

This skin defines custom visual appearance for the title pane, the menu bar, the toolbars and the status bar - the background of these areas is painted by the matching decoration painter - in this case, the org.pushingpixels.substance.api.painter.decoration.MatteDecorationPainter. To add the final polishing touch and create a unique visual footprint for this skin, we use a number of overlay painters:

The Gemini skin defines four separate overlay painters, each one associated with the relevant decoration areas:

    // Add overlay painters to paint drop shadows along the bottom
    // edges of toolbars and footers
    this.addOverlayPainter(BottomShadowOverlayPainter.getInstance(),
        DecorationAreaType.TOOLBAR);
    this.addOverlayPainter(BottomShadowOverlayPainter.getInstance(),
        DecorationAreaType.FOOTER);

    // add an overlay painter to paint a dark line along the bottom
    // edge of toolbars
    this.toolbarBottomLineOverlayPainter = new BottomLineOverlayPainter(
        new ColorSchemeSingleColorQuery() {
          @Override
          public Color query(SubstanceColorScheme scheme) {
            return scheme.getUltraDarkColor().darker();
          }
        });
    this.addOverlayPainter(this.toolbarBottomLineOverlayPainter,
        DecorationAreaType.TOOLBAR);

    // add an overlay painter to paint a dark line along the bottom
    // edge of toolbars
    this.toolbarTopLineOverlayPainter = new TopLineOverlayPainter(
        new ColorSchemeSingleColorQuery() {
          @Override
          public Color query(SubstanceColorScheme scheme) {
            Color fg = scheme.getForegroundColor();
            return new Color(fg.getRed(), fg.getGreen(), fg
                .getBlue()32);
          }
        });
    this.addOverlayPainter(this.toolbarTopLineOverlayPainter,
        DecorationAreaType.TOOLBAR);

    // add an overlay painter to paint a bezel line along the top
    // edge of footer
    this.footerTopBezelOverlayPainter = new TopBezelOverlayPainter(
        new ColorSchemeSingleColorQuery() {
          @Override
          public Color query(SubstanceColorScheme scheme) {
            return scheme.getUltraDarkColor().darker();
          }
        }new ColorSchemeSingleColorQuery() {
          @Override
          public Color query(SubstanceColorScheme scheme) {
            Color fg = scheme.getForegroundColor();
            return new Color(fg.getRed(), fg.getGreen(), fg
                .getBlue()32);
          }
        });
    this.addOverlayPainter(this.footerTopBezelOverlayPainter,
        DecorationAreaType.FOOTER);

The overlay painters used in the Twilight skin are:

Application-facing APIs

To use the matching overlay painters in custom painting routines of your application, call the following published Substance APIs:

The base class for Substance overlay painters is org.pushingpixels.substance.api.painter.overlay.SubstanceOverlayPainter. The only painting method in this class is:

  /**
   * Paints the overlay.
   
   @param graphics
   *            Graphics context.
   @param comp
   *            Component.
   @param decorationAreaType
   *            Decoration area type. Must not be <code>null</code>.
   @param width
   *            Width.
   @param height
   *            Height.
   @param skin
   *            Skin for painting the overlay.
   */
  public void paintOverlay(Graphics2D graphics, Component comp,
      DecorationAreaType decorationAreaType, int width, int height,
      SubstanceSkin skin);

The width and height parameters specify the rectangle for the overlays (the overlay painters can only paint on rectangular areas), the skin specifies the Substance skin to be used to compute the gradient colors, while decorationAreaType indicates the decoration area type.