Face Contexts

To provide greater control over the appearance of buttons and menus GUI Commands allows you to specify faces for different contexts. Commands and groups will then use the best for the button or menu they are creating. Additional contexts are created as per the following example:

   # configure the default face
   command@face.text=Default Face
   # configure the menu face
   command@face[menu].text=Menu Face

Extending Other Faces

When declaring a face for a particular context you often only need to change a small aspect of an existing face. In this case you can extend other faces and override only the properties that change. The following example creates a toolbar face that inherits from the default face but specifies a larger icon:

   command@face.text=_Open@default O
   command@face.icon=classpath:images/file-open.png
   command@face[toolbar].extends=default
   command@face[toolbar].icon=classpath:images/file-open-large.png

You can also remove properties:

   command@face.text=_Open@default O
   command@face.icon=classpath:images/file-open.png
   # clear the text on the toolbar
   command@face[toolbar].extends=default
   command@face[toolbar].text=
Note: The above example is only an illustration as you can globally configure GUI Commands to hide text on toolbars. Please refer to the Renderers section for more information.

Predefined Contexts

The following lists the contexts that are defined within GUI Commands.

ContantString ValueDescription
Face.DEFAULT"default"Used when no matching face is defined
Face.BUTTON"button"Used for all normal buttons.
Face.MENU"menu"Used for all normal menu items.
Face.POPUP"popup"Used menu items on popup menus.
Face.TOOLBAR"toolbar"Used for buttons on toolbars.
Face.TOOLBAR_POPUP"toolbarPopup"Used for popup menus created by toolbar buttons.
Face.HTML"html"Used by CommandHyperlinkListener when creating anchor strings.
Face.HTML_POPUP"htmlPopup"Used for popup menus created by html links.

Configuring the Context Search Order

GUI Commands uses a predefined search order to find the best matching face when creating buttons for a specific context. These are only used if there is no face defined for the requested context.

ContextAlternate Search Order
Face.DEFAULT N/A
Face.BUTTON Face.DEFAULT
Face.MENU Face.DEFAULT
Face.POPUP Face.MENU, Face.DEFAULT
Face.TOOLBAR Face.BUTTON, Face.DEFAULT
Face.TOOLBAR_POPUP Face.POPUP, Face.MENU, Face.DEFAULT
Face.HTML Face.BUTTON, Face.DEFAULT
Face.HTML_POPUP Face.POPUP, Face.MENU, Face.DEFAULT

It is possible to configure the search order for any context as shown in the following example. The default face doesn't need to be specified as it is always used as the last option.

   // Faces created with `myCustomContext` to use the
   // toolbar, button then default face as a fallback.
   GuiCommands.defaults().setAlternativeFaceContexts("myCustomContext",
                                                     Face.TOOLBAR,
                                                     Face.BUTTON);

Setting Popup Face Contexts

In a similar way, you can also configure what face will be used when creating popup menus. A typical example is when you create a toolbar button from a CommandGroup. In this case the group will use Face.TOOLBAR for the button it creates, but will use Face.TOOLBAR_POPUP for the buttons popup menu. You can configure the popup context used for any given context as shown in the following example.

   // Buttons created with `myCustomContext` will use
   // "myCustomPopupContext" for the popups they create.
   GuiCommands.defaults().setPopupContext("myCustomContext",
                                          "myCustomPopupContext");