Guide to the UI

Working With the UI

This page aims to be an overview of how LEGUP's UI is structured and present a standard for how developers should interact with the UI in the future.

Table of Contents

• Libraries
• Styling
• Icons
  • Icon Color Changing
• The Tree and Board

Libraries

LEGUP is made with Swing, itself built on AWT. Some background knowledge of this library will prove very helpful as its procedures and quirks are likely to result in painful debugging when used haphazardly. It is highly recommended that you familiarize yourself with Swing beforehand, such as with these tutorials.

FlatLaf is used for the program's LookAndFeel. Documentation can be found here. FlatLaf Extras is used for rendering SVG images, which is itself dependent on JSVG.

Styling

Styling for the UI is primarily handled by the LookAndFeel. FlatLaf allows for overwriting of its styling properties and importing new properties with the FlatPropertiesLaf class. Most of the styling is located .properties files in the resources/themes directory, which makes editing styling significantly easier and allows users to overwrite styling properties with their own .properties files.

Icons

LEGUP is currently transitioning from using a medley of .png, .jpeg, and .gif images for its icons to using .svg's. Not only do these look significantly better, but they also allow for colors to be dynamically changes in accordance with the styling in the LookAndFeel.

Icon Color Changing

Changing the colors of the FlatSVGIcon icons is accomplished with the class FlatSVGIcon.ColorFilter. This class allows for the mapping of one explicit color to another, defined directly by their RGB values. This means that to properly accomplish unified color switching across the entire program, all .svg icons must be using the same set of expected values. These are defined in resources/themes/FlatLaf.properties under # Expected, and all keys in the LookAndFeel that intend to replace a color in these icons must provide a duplicate prepended with Expected.. In addition, since ColorFilter uses a map for its color replacements, any collisions in expected values will result in both being replaced by the same color. This can be disregarded between puzzle-specific keys as they will never be entered into the ColorFilter at the same time. Finally, no expected value should be equal to any of the SVG named colors.

The Tree and Board

LEGUP's TreeView and BoardView are the most complicated UI elements in the application. As opposed to the rest of the UI, they are drawn to Graphics2D instances directly. They are both extended from ui/ScrollView and wrapped in ui/DynamicView which define their clipping and when and how they are drawn. This direct control over the rendering is very powerful but also requires care to ensure nothing goes wrong. For example, any instance of Graphics2D::setRenderingHint, Graphics2D::setColor, Graphics2D::setStroke, etc. should be wrapped in calls to Graphics2D::create and Graphics2D::dispose if that Graphics2D object is not created within the purview function, which will ensure none of the settings changed will leak out into any other objects being drawing with the same instance of Graphics2D. Similarly to the rest of the UI, any styling done to anything drawn on the board or tree should be defined in the .properties files and retrieved with UIManager::getColor, UIManager::getInt, and so on.