Face Configuration Guide

Faces can be defined for both commands and groups. In both cases the syntax is identical.

The following is a quick example of a typical face configuration:

   paste@face.text=_Paste@default P
   paste@face.icon=classpath:images/paste-icon.png
   paste@face.description=\
      Pastes the content of the clipboard into \
      the current document ($accelerator)

This example configures the default face of the paste command. For information on context specific configuration please refer to the Face Contexts documentation.

Text

The text property allows you to define the text, mnemonic and accelerator for a specific face. The mnemonic character is simply prefixed by an underscore _ and the accelerator is specified following an @ symbol.

The following example defines a "Cut" command:

   cut-command@face.text=Cu_t@default X

Accelerators are defined using the same syntax as KeyStroke.getKeyStroke(String). It's also possible to specify that an accelerator use the platform default menu shortcut. In this case you use the string default as you would control or meta.

Explicit Accelerator Element

You can also define an accelerator using an explicit accelerator property. The following is an example:

   command@face.accelerator=default X

Text Positioning

Text positioning is controlled via the horizontalTextPosition and verticalTextPosition properties. In cases where both are specified, the vertical positioning takes precedence.

   command@face.horizontalTextPosition=trailing
   command@face.verticalTextPostion=bottom

The allowed values for horizontal position are: leading, trailing, center, left and right.

The allowed values for vertical position are: top, center and bottom.

Icons

Faces support the full range of icons defined by Swing buttons. Icons can be loaded from the classpath, URLs and from user defined icon factories. The following demonstrates specifying the icon from each:

   # classpath
   command@face.icon=classpath:images/my-icon.png
   # url
   command@face.icon=url:http://my-server/images/my-icon.png
   # factory
   command@face.icon=factory:my-factory-parameters

The following icon types are supported: icon, selectedIcon, rolloverIcon, rolloverSelectedIcon, pressedIcon and disabledIcon.

The following is for your cut and paste convenience:

   face.icon=
   face.selectedIcon=
   face.rolloverIcon=
   face.rolloverSelectedIcon=
   face.pressedIcon=
   face.disabledIcon=

Icon Text Gap

It is also possible to specify the gap between the icon and text using the iconTextGap property. The following is an example:

   # creates a 10 pixel gap between the icon and text
   command@face.iconTextGap=10

Specifying an Icon Factory

Prior to loading factory based icons you must install the icon factory to be used. The factory is configured globally as follows:

   GuiCommands.defaults().setIconFactory(new CustomIconFactory());

The AbstractReflectionIconFactory class provides a basic IconFactory implementation that converts the icon specification into a method call. To use it you simply create a method to match each of your icon specifications.

   // add a method for each icon type
   public class CustomIconFactory extends AbstractReflectionIconFactory
   {
      public Icon createColoredIcon(String r, String g, String b)
      {
         return ...;
      }
   }

Then specify the method and parameters in your configuration.

   # define a icon
   command@face.icon=factory:createColoredIcon(200,127,127)

Descriptions

Faces support both a description and longDescription property. The description is used by the library to configure tooltips. The long description is not used but is intended for supplying more detailed information for use on status bars or notification areas. See the section on Hovering for an example.

Both the description and longDescription properties support the $text and $accelerator macros. When specified they will be automatically replaced with the text and accelerator of the face respectively.

   command@face.text=Hello World!!!@default H
   command@face.description=Says Hello ($accelerator)
   command@face.longDescription=\
      This commands text is "$text" and \
      the accelerator is "$accelerator".

Client Properties

Client properties are defined using a simple map style syntax. To define the client property foo for example, you'd use the following syntax: command@face.clientProperties[foo]. You can define any number of client properties which will then be applied to any buttons or menus created with the face. The following example shows setting the Quaqua.Button.style client property:

   command@face.text=Quaqua
   command@face.icon=images/smile.gif
   command@face.clientProperties[Quaqua.Button.style]=square