| # GUI Commands User Guide ## Version 2.1 |
| # 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