WorkbenchFX

The one and only framework to build large JavaFX Applications!

Maven

To use this framework as part of your Maven build simply add the following dependency to your pom.xml file:

Java 8

<dependency>
  <groupId>com.dlsc.workbenchfx</groupId>
  <artifactId>workbenchfx-core</artifactId>
  <version>8.1.0</version>
</dependency>

Java 11

<dependency>
  <groupId>com.dlsc.workbenchfx</groupId>
  <artifactId>workbenchfx-core</artifactId>
  <version>11.1.0</version>
</dependency>

Gradle

To use this framework as part of your gradle build simply add the following to your build.gradle file and use the following dependency definition:

Java 8

dependencies {
    compile group: 'com.dlsc.workbenchfx', name: 'workbenchfx-core', version: '8.1.0'
}

Java 11

dependencies {
    compile group: 'com.dlsc.workbenchfx', name: 'workbenchfx-core', version: '11.1.0'
}

Table of Contents

• What is WorkbenchFX?
• Advantages
• Main Components
• Documentation
• Basic Structure
  • Workbench Concept
  • Module Lifecycle
• Demos
• Getting Started
  • Extending the WorkbenchModule
  • Creating the Workbench
  • Optional Methods
    • WorkbenchBuilder
    • Workbench
    • WorkbenchModule
• Using the Components
  • ToolbarItem
  • Dialog
    • Predefined Dialog Types
    • Custom Dialog
  • Prevent module from closing
  • Drawer
  • Custom Overlay
• Restyling
  • Basic Styling
    • Changing Colors
    • Setting a Logo
  • Advanced Styling
• Team

What is WorkbenchFX?

WorkbenchFX is an out of the box solution to build large applications from multiple views, called modules. It offers you good user experience and a beautiful design.

As a developer, you often start with the views, so you can quickly show your progress to your customer. After that, some question may arise such as:

• "How do I bring all those views together?"
• "How do I build the navigation between those views?"
• "How do I establish a good user experience?"

Exactly when those questions appear, WorkbenchFX comes into play: With WorkbenchFX you can focus on designing your views and meanwhile we're building the application around them.

WorkbenchFX also scales with growing requirements. In the beginning you just want to navigate through the views, but later on you probably would want to use a menu or a toolbar. Even that is supported by WorkbenchFX and you don't have to build anything by yourself.

If you still manage to start outgrowing the workbench, you can even replace whole parts of it with your own implementations, without having to rewrite the whole workbench.

Advantages

• Less error-prone
• Less code needed
• Easy to learn
• Easy to understand
• Easy to use, especially for developers which have not much experience in working with JavaFX
• A well designed, adaptable UI, inspired by the material design standards
• Multiple, independent workbench modules, displayed in Tabs combine into one great application
• The jdk8 branch works well with JPRO
• FXML & Scene Builder support

Main Components

The most important components are noted in the picture and the corresponding table below:

For further information about the components, refer to the Javadoc

Documentation

The detailed documentation can be found in: workbenchfx-demo/src/main/resources/com/dlsc/workbenchfx/modules/webview/index.html

It can also be read by opening the Documentation module in ExtendedDemo or the CustomDemo.

Basic Structure

Workbench Concept

WorkbenchFX uses the builder pattern to create the Workbench object, since it allows to use optional features in a flexible way. The minimal usage requires only to specify the WorkbenchModule objects to be used in the Workbench. Afterwards, optional features can be defined using their respective method call before calling build().

For better illustration, the basic concept of creating a Workbench object is shown below:

Workbench workbench = 
    Workbench.builder( // Using the static method call
        new CustomWorkbenchModule() // class CustomWorkbenchModule extends WorkbenchModule
        ...
    )
    // .toolbarRight(...) // optional usage of additional features like navigationDrawer(), modulesPerPage(), etc.
    .build(); // The build call creates, initializes and returns the Workbench object

Note:

• The result of the build() call is a Control which can be set in a scene
• For use with FXML & Scene Builder, there is also a default constructor new Workbench(). However, in this case, modules and other optional features need to be defined separately afterwards

Module Lifecycle

The lifecycle methods are implicitly being called by the workbench. You must not call any of the lifecycle methods by yourself. To close and open modules use only workbench.openModule() and workbench.closeModule().

The abstract class WorkbenchModule contains four different lifecycle methods which can be overridden:

When extending WorkbenchModule, it is only required to implement the activate() method. (Extending the WorkbenchModule)

Overriding all other lifecycle methods is optional and only needs to be done to perform additional actions in the lifecycle. Besides a call to super(), no further workbench-related code is required when overriding a lifecycle method.

Note:

• For further information, refer to our documentation or the Javadoc
• The full documentation about the module lifecycle can be found in the documentation file workbenchfx-demo/src/main/resources/com/dlsc/workbenchfx/modules/webview/index.html, in the section WorkbenchModule Lifecycle

Demos

We created several demos to visualize the capabilities of WorkbenchFX in the workbenchfx-demo folder:

Getting started

Extending the WorkbenchModule

It is required to create a new class and extend WorkbenchModule, in order to create a custom module:

public class CustomModule extends WorkbenchModule {
  
}

It is then required to call the super() constructor and pass in a String as the name and either an Image, FontAwesomeIcon or MaterialDesignIcon as an icon for the module (icon cheatsheets: materialdesignicons.com, fontawesome.com):

public CustomModule() {
  super("My first Workbench module", MaterialDesignIcon.THUMB_UP); // a name and an icon is required
}

Furthermore, overriding the activate() method is also required. This lifecycle method will be called when clicking on the Tile to open the module (see Module Lifecycle):

@Override
public Node activate() {
  return new Label("Hello World"); // return here the actual content to display
}

The minimal implementation of a custom WorkbenchModule finally looks like the code snippet below. Returning a Hello World Label represents the view which will be displayed in the final application. For further information, refer to the Javadoc.

public class CustomModule extends WorkbenchModule {
  public CustomModule() {
      super("My first Workbench module", MaterialDesignIcon.THUMB_UP); // A name and an icon is required
  }
  @Override
  public Node activate() {
      return new Label("Hello World"); // return here the actual content to display
  }
}

Creating the Workbench

After extending the WorkbenchModule, the Workbench can be created. To do this, access the WorkbenchBuilder by calling Workbench.builder(), passing in the previously created module as an object and build the Workbench by calling workbench.build():

// Creating the Workbench
Workbench customWorkbench = Workbench.builder( // Getting a WorkbenchBuilder
    new CustomModule()                         // Adding the CustomModule
).build();                                     // Building the Workbench

For the final application, it can then be used in a Scene as follows:

public class CustomDemo extends Application {
  public static void main(String[] args) {
    launch(args);
  }

  @Override
  public void start(Stage primaryStage) {
    
    Workbench customWorkbench = Workbench.builder(
        new CustomModule()
    ).build();
    
    Scene myScene = new Scene(customWorkbench);
    primaryStage.setScene(myScene);
    primaryStage.setWidth(700);
    primaryStage.setHeight(450);
    primaryStage.show();
  }
}

This code snippet results in the following application:

The default implementation comes with a clickable Tile to open the module. Opening the module, creates a Tab with the defined icon and text. The content returned in the activate() method is displayed in the center. By clicking on the add button, you can get back to the AddModulePage. Closing the opened module is achieved through clicking on the close button in the Tab.

Single Module Layout

If the workbench consists of only one module, a single module layout is used to display the module. In the single module layout, the tab bar and the add module button are not visible and the module is automatically opened on startup.
This results in a very basic application as can be seen below

Optional Methods

WorkbenchBuilder

These optional method calls are called after adding the custom modules to the builder:

Workbench workbench = Workbench.builder(...)
.modulesPerPage(6) // call the optional methods
.build();

The following methods are optionally available to further configure the Workbench:

When the default layout of Page, Tab, Tile or NavigationDrawer don't fulfill the desired requirements, it is possible to replace them:

Workbench

After the build() call on WorkbenchBuilder, the Workbench is created. The following selective calls might be of interest:

WorkbenchModule

The WorkbenchModule also provides useful functionality. It is possible to add ToolbarItems to the toolbar of the module (just like in the workbench):

Using the Components

ToolbarItem

The ToolbarItems which can be set in the toolbars of either the workbench or the module are styled and behave differently based on their content. If for example the item contains a String as text and a MenuItem it is automatically assumed that the styling and behavior of a MenuButton is needed. If on the other hand only an IconView is defined, it is assumed, the behavior of a Label is desired.

Adding different attributes to the ToolbarItem results in different representations: They can also be seen in the toolbar of the CustomDemo

Syntax	Representation
// Label with text ToolbarItem toolbarItem = new ToolbarItem("Hello World");
// Label with graphic ToolbarItem toolbarItem = new ToolbarItem( new MaterialDesignIconView(MaterialDesignIcon.THUMB_UP) );
// Label with text and graphic ToolbarItem toolbarItem = new ToolbarItem( "Hello World", new MaterialDesignIconView(MaterialDesignIcon.THUMB_UP) );
// Button with text ToolbarItem toolbarItem = new ToolbarItem( "Hello World", event -> System.out.println("Hello World") );
// Button with graphic ToolbarItem toolbarItem = new ToolbarItem( new MaterialDesignIconView(MaterialDesignIcon.THUMB_UP), event -> System.out.println("Hello World") );
// Button with text and graphic ToolbarItem toolbarItem = new ToolbarItem( "Hello World", new MaterialDesignIconView(MaterialDesignIcon.THUMB_UP), event -> System.out.println("Hello World") );
// MenuButton with text ToolbarItem toolbarItem = new ToolbarItem( "Hello World", new MenuItem("Content 1"), new MenuItem("Content 2") );
// MenuButton with graphic ToolbarItem toolbarItem = new ToolbarItem( new MaterialDesignIconView(MaterialDesignIcon.THUMB_UP), new MenuItem("Content 1"), new MenuItem("Content 2") );
// MenuButton with text and graphic ToolbarItem toolbarItem = new ToolbarItem( "Hello World", new MaterialDesignIconView(MaterialDesignIcon.THUMB_UP), new MenuItem("Content 1"), new MenuItem("Content 2") );
// MenuButton with a MenuItem containing custom content ToolbarItem toolbarItem = new ToolbarItem( "Account", new MaterialDesignIconView(MaterialDesignIcon.ACCOUNT), new MenuItem("", new HBox( new Label("Login: "), new TextField(), new Button("", new MaterialDesignIconView( MaterialDesignIcon.PLUS)) ) ) );

Dialog

A demo of the dialogs can be found in the DialogTestModule of the Custom Demo

Predefined Dialog Types

WorkbenchFX comes with a lot of predefined dialog types. Using them is as simple as calling workbench.show...Dialog() with the desired dialog type. After clicking on one of the Buttons of a dialog, the corresponding ButtonType is returned as the result of the dialog. Therefore it is required to define a Consumer<ButtonType> for every dialog to validate the answer. A few examples on how to use them are listed below:

// Precondition
Workbench workbench = Workbench.builder(...).build; // Creating the workbench
Button dialogBtn = new Button("Show Dialog"); // Assuming the button is used in a module

Syntax	Outcome
// Confirmation Dialog dialogBtn.setOnAction(event -> workbench.showConfirmationDialog( "Continue without saving?", "Are you sure you want to continue without saving" + "your document?", buttonType -> { // Proceed and validate the result } ) );
// Error Dialog dialogBtn.setOnAction(event -> workbench.showErrorDialog( "Button click failed!", "During the click of this button, something went" + "horribly wrong.", buttonType -> { // Proceed and validate the result } ) );
// Error Dialog with exception dialogBtn = null; // Provokes an exception try { dialogBtn.setOnAction( event -> System.out.println("Throws NPE!")); } catch (NullPointerException exception) { workbench.showErrorDialog( "Button click failed!", "During the click of this button, something went " + "horribly wrong. Please forward the content " + "below to anyone but the WorkbenchFX " + "developers to track down the issue:", exception buttonType -> { // Proceed and validate the result } ); }
// Error Dialog with details dialogBtn.setOnAction(event -> workbench.showErrorDialog( "Button click failed!", "During the click of this button, something went" + "horribly wrong.", "Details about this exception are not present.", buttonType -> { // Proceed and validate the result } ) );
// Warning Dialog dialogBtn.setOnAction(event -> workbench.showWarningDialog( "Reset settings?", "This will reset your device to its default" + "factory settings.", buttonType -> { // Proceed and validate the result } ) );
// Information Dialog dialogBtn.setOnAction(event -> workbench.showInformationDialog( "Just to let you know", "(This is an information dialog)", buttonType -> { // Proceed and validate the result } ) );

Custom Dialog

Sometimes just using the default dialog types are not enough. For such special cases, the workbench.showDialog() method can be used. With WorkbenchDialog.builder() a custom dialog can be created. The builder provides some useful methods which can be used:

Note:

• Defining content will override further definitions of message, details or exception

Using the builder it is possible to write some interesting custom dialogs:

// Precondition
Workbench workbench = Workbench.builder(...).build; // Creating the workbench
Button dialogBtn = new Button("Show Dialog"); // Assuming the button is used in a module

Syntax

Outcome

// Dialog which requires input to proceed // Create a CheckBox which will be set as content CheckBox checkBox = new CheckBox("I accept the Terms and Conditions"); dialogBtn.setOnAction(event -> { // Building the dialog with the CheckBox as content WorkbenchDialog dialog = WorkbenchDialog.builder( "Check the box to continue", checkBox, ButtonType.OK) .blocking(true) .build(); // Bind the OK button to the CheckBox dialog.setOnShown(event1 -> { dialog.getButton(ButtonType.OK).ifPresent( button -> button.disableProperty().bind( checkBox.selectedProperty().not())); }); getWorkbench().showDialog(dialog); });

Other examples can be found in the DialogTestModule of the Custom Demo

Prevent module from closing

In some cases it is necessary to prevent a module from closing. For example, the following dialog asks about saving before closing:

As mentioned in Module Lifecycle, the destroy() method will be called when closing the module. The module will be closed as soon as the destroy() method returns true. If you want to prevent the module from closing, return false and then close the module by calling close(), as soon as you are ready.

The code snippet below results in the dialog displayed in the image on top:

@Override
public boolean destroy() {
  
  // Perform an asynchronous task (in our case showing a dialog)
  getWorkbench().showDialog(WorkbenchDialog.builder(
      "Save before closing?",
      "Do you want to save your progress? Otherwise it will be lost.",
      ButtonType.YES, ButtonType.NO, ButtonType.CANCEL)
      .blocking(true)
      .onResult(buttonType -> {
        // If CANCEL was not pressed
        if (!ButtonType.CANCEL.equals(buttonType)) {
          if (ButtonType.YES.equals(buttonType)) {
            // YES was pressed -> Proceed with saving
            ...
          }
          close(); // Close the module since CANCEL was not pressed 
        }
      })
      .build());
  
  return false; // return false, because we're closing manually
}

Drawer

Calling workbench.showDrawer(), enables you to show a custom drawer (like the NavigationDrawer). There are two possibilities for showing a drawer:

workbench.showDrawer(
    Region drawer, // Drawer to be shown
    Side side      // From which side the drawer should come from
);

Calling this, the width of the drawer is calculated automatically and takes the width which fits best for the drawer content defined. The other possibility comes into action when a specific width is desired:

workbench.showDrawer(
    Region drawer, // Drawer to be shown
    Side side      // From which side the drawer should come from
    int percentage // Defines how much of the screen should be covered
);

The percentage can be defined in an Integer range between 0 and 100. It represents the percentage of the window the drawer covers when showing.

Examples of drawers can be found in the DrawerTestModule of the Custom Demo

Custom Overlay

The foundation of Dialogs and Drawers are overlays. It is possible to define a custom overlay by calling workbench.showOverlay(). The defined overlay will be stacked on top of a GlassPane.

workbench.showOverlay(
    Region overlay,  // Overlay to be shown
    boolean blocking // true, if the overlay should not be closed when clicking on the GlassPane
);

The overlay can essentially be any Region (for example a custom Control). Per default, the defined content will be displayed in the top-left corner of the window. To center the content of an overlay, perform the following call on the overlay:

StackPane.setAlignment(overlay, Pos.CENTER); // is needed to center the overlay on the screen

Restyling

Basic Styling

First of all: WorkbenchFX does not interfere with the styles of the individual modules. This way each module can be styled independently and you do not have to worry about the workbench influencing the styling.

But it is possible to alter the styles of the workbench itself. WorkbenchFX comes with an out of the box styling. It is strongly inspired by Material Design.

The workbench's styling can be altered by referencing a stylesheet, like in the Custom Demo:

workbench.getStylesheets().add(CustomDemo.class.getResource("customTheme.css").toExternalForm());

In the file customTheme.css, some default colors are referenced:

* {
  -primary-color: #6200EE;
  -primary-variant-color: #3700b3;
  -secondary-color: #6300ff;
  -secondary-variant-color: #1e005f;
  -background-color: #FFFFFF;
  -surface-color: #FFFFFF;
  -error-color: #B00020;
  -on-primary-color: #FFFFFF;
  -on-secondary-color: #FFFFFF;
  -on-background-color: #000000;
  -on-surface-color: #000000;
  -on-error-color: #FFFFFF;
}

.logo {
  /* Reference to the applications logo */
  -fx-graphic: url("logo.png");
}

The colors are named according to the Material Design guidelines. Changing those colors leads to a complete restyling of the workbench. For example, a file darkTheme.css is also referenced in the demo and leads to the following result:

Changing Colors

If you want to change the colors of the application, create a new css file customTheme.css and add it to the workbench:

workbench.getStylesheets().add(CustomDemo.class.getResource("customTheme.css").toExternalForm());

In context, the code looks like this:

public class CustomDemo extends Application {
  public static void main(String[] args) {
    launch(args);
  }

  @Override
  public void start(Stage primaryStage) {
    
    Workbench customWorkbench = Workbench.builder(
        new CustomModule()
    ).build();
    
    // Adding the stylesheet to the workbench to restyle it
    customWorkbench.getStylesheets().add(CustomDemo.class.getResource("customTheme.css").toExternalForm());
    
    Scene myScene = new Scene(customWorkbench);
    primaryStage.setScene(myScene);
    primaryStage.setWidth(700);
    primaryStage.setHeight(450);
    primaryStage.show();
  }
}

Changing the colors in the css file to something like this:

* {
  -primary-color: #9db668;
  -primary-variant-color: #7f975f;
  -secondary-color: #9db668;
  -secondary-variant-color: #7f975f;
  -background-color: #FFFFFF;
  -surface-color: #FFFFFF;
  -error-color: #B00020;
  -on-primary-color: #FFFFFF;
  -on-secondary-color: #FFFFFF;
  -on-background-color: #747474;
  -on-surface-color: #747474;
  -on-error-color: #FFFFFF;
}

Leads to following design:

Setting a Logo

In the upper section of the NavigationDrawer, there is a section for a logo. The logo is defined in the custom stylesheet (how to create one and reference it is described in the previous chapter). An example implementation of the logo can be found in the customTheme.css of the Custom Demo:

.logo {
  /* Reference to the application's logo */
  -fx-graphic: url("logo.png");
}

Changing the logo can easily be done by adding an image with the correct size in the resources folder and referring to its name in the stylesheet:

.logo {
  /* Reference to the applications logo */
  -fx-graphic: url("myCustomLogo.png"); /* Replacing logo.png with a different image. */
}

Note:

• WorkbenchFX does not resize the image. We suggest a maximum image height of 250px

Advanced Styling

Sometimes just changing the colors is not enough. Every component in the workbench has its own .class or #id. This way, the components can be restyled if needed.

For example, every generated Tab and Tile has its own unique #id. The naming conventions for the #id are defined as:

• Prefix: tab / tile (depending on the component)
• Body: the name of the module
  • all special characters besides hyphens are removed
  • all spaces are replaced by hyphens (-)
  • uppercase letters are converted to lowercase

Setting the LOGGER level to debug will print each module's tab and tile id as soon as they are set:

• Set Tab-ID of '(MODULE NAME)' to: '(TAB ID)'
• Set Tile-ID of '(MODULE NAME)' to: '(TILE ID)'

For further information, refer to the Javadoc of WorkbenchUtils.convertToId()

#id example:

Module name:
    François' Module
    
Results in:
    tab-franois-module // Tab id
    tile-franois-module // Tile id
    
LOGGER output:
    Set Tab-ID of 'François' Module' to: 'tab-franois-module'
    Set Tile-ID of 'François' Module' to: 'tile-franois-module'

Starting with the result after chapter Getting Started:

Assuming the Tab and Tile need to be restyled, add the following code snippet to the customTheme.css file:

/* Styling the Tile */
#tile-my-first-workbench-module .tile-box {
  -fx-background-color: -primary-color !important; /* The background of the Tile */
}

#tile-my-first-workbench-module .tile-box .text, /* The icon and the text */
#tile-my-first-workbench-module .tile-box .glyph-icon {
  -fx-fill: -on-primary-color !important;
}

/* Styling the Tab */
#tab-my-first-workbench-module:selected {
  -fx-background-color: #747474 !important; /* The background of the Tab */
  -fx-background-radius: 5px 5px 0 0 !important;
}

#tab-my-first-workbench-module:selected .text, /* The icon and the text */
#tab-my-first-workbench-module:selected .glyph-icon {
  -fx-fill: #ffffff !important;
}

#tab-my-first-workbench-module:selected .shape {
  -fx-background-color: #ffffff !important; /* The close icon */
}

Leads to following styling:

Note:

• The css color variables can still be used in the customTheme.css file
• Since the styling of the workbench is more specific, the !important tag is required when styling the workbench
• A tool like ScenicView helps to determine the style classes

Team

• Marco Sanfratello

  • [email protected]
  • Skype: [email protected]
  • GitHub: Genron

• François Martin

  • [email protected]
  • Skype: francoisamimartin
  • GitHub: martinfrancois

• Dirk Lemmermann

  • [email protected]
  • Skype: dlemmermann
  • GitHub: dlemmermann

• Dieter Holz

  • [email protected]
  • Skype: dieter.holz.canoo.com
  • GitHub: DieterHolz

License