MaterialFX

MaterialFX

MaterialFX is an open source Java library which provides material design components for JavaFX
Explore the wiki »

Download Latest Demo · Report Bug · Request Feature

Table of Contents

• Important Notes!
• About the Project and History of JavaFX
• About the Logo
• Some GIFs
• Getting Started
  • Build
  • Usage
    • Gradle
    • Maven
• Documentation
• Changelog
• Roadmap
• Theming System
• Contributing
• License
• Contact
• Donation
• Supporters

Important notes

Please, before using this library and submitting an issue complaining that controls are not styled and bugged check how the styling system has changed since version 11.14.0

About The Project and History of JavaFX

JavaFX is a software platform intended to replace Swing in creating and delivering rich client applications that operate consistently across diverse platforms. With the release of JDK 11 in 2018, Oracle has made JavaFX part of the OpenJDK under the OpenJFX project in order to increase the pace of its development.

Key features:

• FXML and SceneBuilder, A designer can code in FXML or use JavaFX Scene Builder to interactively design the graphical user interface (GUI). Scene Builder generates FXML markup that can be ported to an IDE where a developer can add the business logic.
• Built-in UI controls and CSS, JavaFX provides all the major UI controls required to develop a full-featured application. Components can be skinned with standard Web technologies such as CSS.
• Self-contained application deployment model. Self-contained application packages have all the application resources and a private copy of the Java and JavaFX runtimes. They are distributed as native installable packages and provide the same installation and launch experience as native applications for that operating system. JavaFX is a software platform for creating and delivering desktop applications, as well as rich Internet applications (RIAs) that can run across a wide variety of devices.

Over the years the way of creating GUIs has often changed and JavaFX default appearance is still pretty much the same. That's where this project comes in. The aim of my project is to bring components which follow as much as possible the Google's material design guidelines to JavaFX. The second purpose is to provide a successor to the already available JFoenix library, which is a bit old and has a lot of issues.

In recent months the project has evolved a lot, to the point that it is no longer a simple substitute.
To date MaterialFX offers not only restyled controls, but also: new and unique controls such as the Stepper, controls completely redone from scratch such as ComboBoxes or TableViews (and many others), and many utilities for JavaFX and Java (NodeUtils, ColorUtils, StringUtils ...).

About The Logo

MaterialFX v11.13.0 brought a lot of fixes and new features, but it also brought a new logo, something that is more meaningful for me and that somewhat represents the new version.
The new logo is a Phoenix, the immortal bird from Greek mythology, associated to regeneration/rebirth. When a Phoenix dies it obtains new life by raising from its ashes.
MaterialFX v11.13.0 fixed many critical bugs and broken features, I like to think that it is reborn from the previous version, so I thought a new logo would have been a good idea.

Preview GIFs

Imgur Link: Gallery

Getting Started

In this section you can learn what do you need to use my library in your project or see a preview/demo which I'm planning to release as runtime images here on github.

Build

To build MaterialFX, execute the following command:

gradlew build

To run the main demo, execute the following command:

gradlew run

NOTE: MaterialFX requires Java 11 and above.

Usage

Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.github.palexdev:materialfx:11.17.0'
}

Maven

<dependency>
    <groupId>io.github.palexdev</groupId>
    <artifactId>materialfx</artifactId>
    <version>11.17.0</version>
</dependency>

Documentation

You can read MaterialFX's documentation at javadoc.io

Changelog

See the CHANGELOG file for a list of changes per version.

Roadmap

See the Open Issues for a list of proposed features (and known issues) .
See the ROADMAP for a list of implemented and upcoming features.

Theming System

Since MaterialFX 11.14.0 the way controls are styles through CSS has drastically changed. Before telling you about the new Theming System, and about its pros and cons, let's talk a bit on the history of this project, the causes that brought to this drastic change.

When I started developing MaterialFX I was a complete noob, I knew nothing about JavaFX. But I really wanted to use it and to make it look good. Competitors had broken libraries that made usage difficult for the end user, I didn't like them at all.
And so the journey begun, MaterialFX is born. Like any newbies, what do you do when you know nothing but want to learn?
You check others work and try to copy them but still make the changes you want to implement.
This lead me to create controls that made use of the infamous getUserAgentStylesheet() method. For those of you that do not know about it, a developer of custom controls is supposed to override that method to provide a CSS stylesheet to define the author's intended style for the custom control.
Sounds great right, just the thing I need... Well, I'd say that if only it worked properly. This system has been the root cause of CSS issues right from the start of the project, with little I could do to fix it properly.
(Little secret that almost no one know: I actually sent a PR on the JavaFX repo to improve the system and make it dynamic, guess what, it's still there lol)

The two most annoying issues caused by this system are:

1. The little buggers didn't think of nested custom controls. For example, if a custom control(parent) has a skin that uses other custom controls(children), the user agent of the parent will be completely ignored by the children, the result is a bunch of children that cannot be styled in any way unless you create a custom skin yourself. A fix I implemented for this in the past, was to override inline the getUserAgentStylesheet() method of each children node to use the one of the parent, and even this drastic solution was working half the time (didn't work in some user cases)
2. For some reason, sometimes stylesheets provided by the user were half or completely ignored leading to half/not styled(as intended) custom controls. This was the most annoying issue, as the causes would vary from case to case, not always there was an easy/feasible solution, a nightmare, really

End of the rant
How can I fix it? I asked myself many many times.
Recently I've been working on a rewrite of MaterialFX, this new version will have controls based on the new Material Design 3 Guidelines, will implement modular themes thanks to the usage of SASS and a Theming API that will let user change themes, implement new ones, very easily.
So the idea is to backport at least the concept on the main branch at least until the rewrite is done.

The Theme API

1. Themes: this enumerator defines the default themes of MaterialFX, there is the DEFAULT theme that includes the stylesheets of all MaterialFX controls, as well as dialogs, popups, menus, etc...
2. Stylesheets: this enumerator defines all the stylesheets of every single control, allowing the user to not use a theme (for whatever reason) and instead choose which component he wants to style

MFXThemeManager is a utility class that will help the user add/set themes and stylesheets (which implement Theme) on nodes or scenes.

Pros

• The biggest pro is to have a more reliable styling system. With this users shouldn't hava any issue anymore while styling MaterialFX controls with their custom stylesheets. Of course, I consider the system experimental, I don't expect to not have even a single report about CSS bugs, but they should be way less and much easier to fix
• Another pro is to have less code duplication as now I don't need to override the infamous getUserAgentStylesheet() anymore anywhere
• This change should have also impacted on memory usage in a good way as now controls do not store the "url" to their stylesheet anymore

Cons

• One con is that now themes must be managed by the user. Since controls are not styled by default, the user must use the aforementioned manager or enumerators to load/add the themes on the App.
  The preferred way to do so would be to add the themes/stylesheets on the root scene, like this:
  java复制

  public class App extends Application {
  
    @Override
    public void start(Stage stage) {
     ...
     Scene scene = ...;
     MFXThemeManager.addOn(scene, Themes.DEFAULT, Themes.LEGACY);
    }
  }

• Another con that derives from the above example are dialogs/popups or any separate stage/scene. Since you are applying the themes on the primary stage's scene, it means that all other scenes will be un-styled. You have to add the Themes on every separate scene. To simplify things, MaterialFX automatically applies the Themes on its dialogs and popups, but since now they are added to the getStylesheets() list it's easy to remove them and define your own
• ~~The last con I can think of is SceneBuilder. As of now there is no support for it, I have some ideas on how to style controls inside of it though. The issue is that even if I f