| # GUI Commands User Guide ## Version 2.1 |
| # 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.
Contant | String Value | Description
--- | --- | ---
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.
Context | Alternate 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");