https://github.com/http-rpc/sierra
Declarative UI for Java
https://github.com/http-rpc/sierra
declarative-ui java swing xml
Last synced: 3 months ago
JSON representation
Declarative UI for Java
- Host: GitHub
- URL: https://github.com/http-rpc/sierra
- Owner: HTTP-RPC
- License: apache-2.0
- Created: 2022-07-18T16:51:23.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2025-04-08T18:41:09.000Z (3 months ago)
- Last Synced: 2025-04-12T05:43:46.070Z (3 months ago)
- Topics: declarative-ui, java, swing, xml
- Language: Java
- Homepage:
- Size: 15.7 MB
- Stars: 127
- Watchers: 6
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/HTTP-RPC/Sierra/releases)
[](https://repo1.maven.org/maven2/org/httprpc/sierra/)
[](https://javadoc.io/doc/org.httprpc/sierra)
# Introduction
Sierra is an open-source framework for simplifying development of Java Swing applications. It is extremely lightweight and has minimal external dependencies. The project's name comes from the nautical _S_ or _Sierra_ flag, representing the first letter in "Swing":
This guide introduces the Sierra framework and provides an overview of its key features.
# Getting Sierra
Sierra is distributed via Maven Central at [org.httprpc:sierra](https://repo1.maven.org/maven2/org/httprpc/sierra/). Java 17 or later is required. [FlatLaf](https://www.formdev.com/flatlaf/) is recommended.
A [DTD](sierra.dtd) is provided to assist with editing. It is not used for validation and is not required.
# Sierra Classes
Sierra provides the `UILoader` class, which can be used in conjunction with the following types to to declaratively establish a hierarchy of user interface elements:
* `RowPanel` - arranges sub-components in a horizontal line, optionally aligning to baseline
* `ColumnPanel` - arranges sub-components in a vertical line, optionally aligning nested elements to a grid
* `StackPanel` - sizes sub-components to fill the available space
* `Spacer` - provides fixed or flexible space between other components
These classes offer an alternative to the standard Java layout managers, which can often be limiting or difficult to use in practice.
Sierra also includes the `TextPane` and `ImagePane` components, which provide an alternative to `JLabel` for displaying basic text or image content, respectively. `TextPane` supports wrapping without requiring HTML, and `ImagePane` supports scaling without requiring an intermediate `BufferedImage`.
For example, the following markup declares a column panel containing a graphic and a simple greeting:
```xml
```
This markup could be deserialized and set as the content pane of a frame or dialog as follows:
```java
setContentPane(UILoader.load(this, "greeting-test.xml"));
```
The complete source code for this example can be found [here](sierra-test/src/main/java/org/httprpc/sierra/test/GreetingTest.java).
## Elements
XML elements represent component instances. Most Swing and all Sierra components are supported by default. Support for additional elements can be added via the `bind()` method of the `UILoader` class.
Elements can be nested to create a component hierarchy. For example:
```xml
```
## Attributes
XML attributes generally represent component properties. For example, this markup creates an instance of `TextPane` and sets its "text" property to "Hello, World!":
```xml
```
Numeric and boolean values are automatically converted to the appropriate type. Properties that expect values defined by the `SwingConstants` class (such as "horizontalAlignment") can be specified via a lowercase version of the constant name. Enum values are specified using [kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case).
### Color and Font Values
Color and font properties can be specified using the formats supported by `Color#decode()` and `Font#decode()`, respectively. For example, this markup creates an instance of `JLabel` and sets its "foreground" property to gray:
```xml
```
Colors and fonts can also be referenced by name:
```xml
```
Sierra includes support for the 16 "basic" [web colors](https://en.wikipedia.org/wiki/Web_colors) by default. Support for additional colors and fonts can be added via the `define()` methods of the `UILoader` class.
### Image and Icon Values
Image and icon properties can be specified via a path to an image document on the application's classpath. The path is relative to the document's "owner", the value passed as the first argument to `UILoader#load()`. For example:
```xml
```
Icon support is currently limited to SVG documents and requires the [FlatLaf Extras](https://github.com/JFormDesigner/FlatLaf/tree/main/flatlaf-extras) library:
```xml
```
### Border and Padding Values
The "border" and "padding" attributes are used to create a solid border and reserve space around a component, respectively. For example, this markup creates a label with a light gray border and four pixels of padding on each side:
```xml
```
Border thickness can be specified as shown below:
```xml
border="#00ff00, 4"
```
Padding values for multiple sides can be specified in _top_, _left_, _bottom_, _right_ order:
```xml
padding="8, 8, 8, 8"
```
### Weight and Size Values
The "weight" attribute specifies the amount of excess space in a container that should be allocated to a component, relative to other weighted components in the container. When applied to a `Spacer` instance, it creates a "glue" component that automatically shrinks or stretches depending on the size of its container. However, weights are not limited to spacers and can be applied to any component type:
```xml
```
The "size" attribute specifies a fixed dimension for a component. It is typically used with `Spacer` instances to create "struts" between components, as an alternative to the "spacing" property provided by `RowPanel` and `ColumnPanel`:
```xml
...
```
Size values for multiple dimensions can be specified in _width_, _height_ order:
```xml
size="20, 20"
```
### FlatLaf Client Properties
FlatLaf style and [style class](https://www.formdev.com/flatlaf/typography/) values can be specified via the "style" and "styleClass" attributes, respectively. For example, this markup applies the "h2" style class to a `JLabel` instance used by a list cell renderer:
```xml
```
Several FlatLaf text field [properties](https://www.formdev.com/flatlaf/client-properties/#JTextField) are also supported. For example:
```xml
```
### Button Groups
The "group" attribute associates a button with a button group. For example, the following markup creates two radio buttons belonging to the "orientation" group:
```xml
```
### Element Names
The "name" attribute associates an identifier with a component. The value is automatically injected into a field with the same name defined by the document's owner (called an "outlet").
For example, the following markup declares outlets named "greetingButton" and "greetingLabel":
```xml
```
When the `load()` method returns, the corresponding fields in the owner will be populated with the instances declared in the markup:
```java
public class ActionTest extends JFrame implements Runnable {
private JButton greetingButton = null;
private JLabel greetingLabel = null;
...
@Override
public void run() {
setContentPane(UILoader.load(this, "action-test.xml", resourceBundle));
...
}
}
```
See [ActionTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/ActionTest.java) for more information.
### Resource Bundles
If a non-`null` value is passed as the third argument to the `load()` method, values of text properties are considered resource keys and are used to look up the associated strings in the provided resource bundle. For example:
```xml
...
```
```properties
title = Form Test
firstName = First Name
lastName = Last Name
streetAddress = Street Address
...
```
```java
public class FormTest extends JFrame implements Runnable {
private static final ResourceBundle resourceBundle = ResourceBundle.getBundle(FormTest.class.getName());
...
@Override
public void run() {
var scrollPane = new JScrollPane(UILoader.load(this, "form-test.xml", resourceBundle));
...
}
}
```
See [FormTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/FormTest.java) for more information.
## Cell Alignment
When grid alignment is enabled in a `ColumnPanel`, the sub-components of every `RowPanel` in the column are vertically aligned in a grid, as in a spreadsheet or HTML table. The width of each sub-column is the maximum preferred width of the "cells" in that column (i.e. the components having the same index in each row).
Cell contents are aligned based on the component's _x_ and _y_ alignment values (returned by `getAlignmentX()` and `getAlignmentY()`, respectively). For most components, the default is 0.5, indicating that the component should fill the entire cell along both axes. Values between 0.0 and 0.5 will align the component to the cell's leading or top edge, and values between 0.5 and 1.0 will align the component to the cell's trailing or bottom edge. In both cases, a proportional amount of the excess space will be allocated to the component. A value of 0 or 1 will result in no excess space being given to the component (i.e. it will be aligned to the appropriate edge and will be given its preferred size along that axis).
For example, the following markup demonstrates x-alignment:
```xml
```
This markup demonstrates y-alignment:
```xml
```
Row spacing and cell weights are ignored when grid alignment is enabled.
## Utility Components
In addition to the features outlined above, Sierra also includes some common user interface elements not provided by Swing.
### Menu Buttons
The `MenuButton` component displays a popup menu when pressed. For example:
See [MenuButtonTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/MenuButtonTest.java) for more information.
### Date and Time Pickers
The `DatePicker` and `TimePicker` components allow a user to select a local date and time, respectively:
These classes are localized. See [DateTimePickerTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/DateTimePickerTest.java) for more information.
### Suggestion Pickers
The `SuggestionPicker` component allows a user to choose from a list of predefined values:
See [SuggestionPickerTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/SuggestionPickerTest.java) for more information.
### Activity Indicators
The `ActivityIndicator` component shows indeterminate progress:
See [ActivityIndicatorTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/ActivityIndicatorTest.java) for more information.
## Focus Management
The `ScrollingKeyboardFocusManager` class ensures that components are automatically scrolled into view when focused (something that Swing oddly does not do by default). It can be installed at application startup as follows:
```java
KeyboardFocusManager.setCurrentKeyboardFocusManager(new ScrollingKeyboardFocusManager());
```
See [FormTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/FormTest.java) for more information.
## Task Execution
The `TaskExecutor` class performs a task in the background and and invokes a callback on the UI thread when the task is complete:
```java
public void execute(Callable task, BiConsumer handler) { ... }
```
For example:
```java
taskExecutor.execute(() -> {
// Perform long-running task that may throw
return result;
}, (result, exception) -> {
if (exception == null) {
// Handle success
} else {
// Handle failure
}
});
```
Internally, tasks are submitted to an executor service provided to the `TaskExecutor` constructor. See [TaskExecutorTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/TaskExecutorTest.java) for more information.
# Complete Example
The following is a complete example of an application built using Sierra. It uses the Tiingo [End-of-Day](https://www.tiingo.com/documentation/end-of-day) API to retrieve historical stock pricing information:
The application consists of the following source files:
* [TiingoTest.java](sierra-test/src/main/java/org/httprpc/sierra/test/TiingoTest.java) - primary application logic
* [TiingoServiceProxy.java](sierra-test/src/main/java/org/httprpc/sierra/test/TiingoServiceProxy.java) - proxy interface used to submit API requests
* [Asset.java](sierra-test/src/main/java/org/httprpc/sierra/test/Asset.java) and [AssetPricing.java](sierra-test/src/main/java/org/httprpc/sierra/test/AssetPricing.java) - data types used by `TiingoServiceProxy`
* [tiingo-test.xml](https://github.com/HTTP-RPC/Sierra/blob/master/sierra-test/src/main/resources/org/httprpc/sierra/test/tiingo-test.xml) - UI declaration
* [TiingoTest.properties](https://github.com/HTTP-RPC/Sierra/blob/master/sierra-test/src/main/resources/org/httprpc/sierra/test/TiingoTest.properties) - localized string resources
An API token is required and must be specified as a system property at application startup:
```
-Dtoken=
```