Substance look and feel - skins overview

Skin

A skin must implement org.jvnet.substance.skin.SubstanceSkin interface. This interface defines the following methods:

  /*
   * (non-Javadoc)
   
   * @see org.jvnet.substance.utils.SubstanceTrait#getDisplayName()
   */
  public String getDisplayName();

  /**
   * Sets <code>this</code> skin. Can call any public static method in
   {@link SubstanceLookAndFeel} class.
   
   @return <code>true</code> if skin has been set successfully,
   *         <code>false</code> otherwise.
   */
  public boolean set();

  /**
   * Returns the theme of <code>this</code> skin. The result may be
   <code>null</code> if <code>this</code> skin doesn't define a custom
   * theme.
   
   @return The theme of <code>this</code> skin. The result may be
   *         <code>null</code> if <code>this</code> skin doesn't define a
   *         custom theme.
   */
  public SubstanceTheme getTheme();

  /**
   * Returns the watermark of <code>this</code> skin. The result may be
   <code>null</code> if <code>this</code> skin doesn't define a custom
   * watermark.
   
   @return The watermark of <code>this</code> skin. The result may be
   *         <code>null</code> if <code>this</code> skin doesn't define a
   *         custom watermark.
   */
  public SubstanceWatermark getWatermark();

In order to set a skin, you can either call the set method or invoke the following API available on the org.jvnet.substance.SubstanceLookAndFeel class:

  /**
   * Sets the specified skin.
   
   @param skin
   *            Skin to set.
   @return <code>true</code> if the specified skin has been set
   *         successfully, <code>false</code> otherwise.
   @since version 3.1
   */
  public static boolean setSkin(SubstanceSkin skin) {

  /**
   * Sets the specified skin.
   
   @param skinClassName
   *            Skin to set.
   @return <code>true</code> if the specified skin has been set
   *         successfully, <code>false</code> otherwise.
   @since version 3.1
   */
  public static boolean setSkin(String skinClassName) {

It is highly recommended to use the API from the SubstanceLookAndFeel class since it also updates all the open frames and notifies listeners on the skin change event.

Available skins

Providing custom skins

Substance provides an option for specifying custom skin. This option uses the Substance plugin mechanism that discovers the additional skins at runtime. As with all Substance plugins, you must pack an additional XML configuration file in one of your runtime jarfiles. The name of this file must be substance-plugin.xml and it must comply with the following syntax:
<laf-plugin>
   additional optional tags
   <skin-plugin-class>...</skin-plugin-class>
   additional optional tags
</laf-plugin>

The contents of skin-plugin-class tag must be the fully-qualified class name of a class that implements the SubstanceSkinPlugin interface. This interface specifies the following methods:

  /**
   * Returns information on all available skins in <code>this</code> plugin.
   
   @return Information on all available skins in <code>this</code> plugin.
   */
  public Set<SkinInfo> getSkins();

  /**
   * Returns the class name of the default skin.
   
   @return The class name of the default skin.
   */
  public String getDefaultSkinClassName();

The SkinInfo class contains information on a single (base or custom) skin.

Note that using this option you may override the skins supplied with Substance base package (by specifying the same display name). This behaviour, however, is not guaranteed to be consistent across various VMs and class loaders, since the skin plugins are processed in random order.