fulibFx is a framework for JavaFX applications adding different utilities and features. It provides a simple way to create and manage controllers, views, routes, subcomponents, modals, and more.
The framework is built on top of JavaFX and uses Dagger for dependency injection and RxJava for reactive programming. It also provides a few utility classes and data structures to simplify the creation of JavaFX applications.
repositories {
mavenCentral()
}
dependencies {
// Framework
implementation 'org.fulib:fulibFx:VERSION'
// Annotation processor
annotationProcessor 'org.fulib:fulibFx-processor:VERSION'
}
compileJava {
// Required for the annotation processor
options.sourcepath = sourceSets.main.resources.getSourceDirectories()
}The framework provides a variety of features to simplify the creation of JavaFX applications. The following list provides an overview of the most important features:
Controllers can be created by annotating a class with @Controller.
To specify methods which should be executed during the lifetime of the controller, they should be annotated with either
@OnInit, @OnRender or @OnDestroy to specify their respective execution points.
A special type of controller is the component. They can be used to create controller which can be used inside other
controllers. Components have to extend from a JavaFX Parent (or any class extending from Parent) and have to be annotated
with @Component. Using @SubComponent on a field containing a component will automatically initialize and render the
component along with the parent controller.
The framework also provides a way to pass parameters to a controller using @Param
or utilities like setting a title using @Title or registering
key events @OnKey.
@Title("Todo List")
@Controller("view/Todo.fxml")
public class TodoController {
@FXML
private VBox container;
@SubComponent
@Inject
TodoListComponent todoListComponent;
@OnInit
public void initialize() {
// Called when the controller is initialized
}
@OnRender
public void render() {
this.container.getChildren().add(todoListComponent);
}
@OnDestroy
public void destroy() {
// Called when the controller is being cleaned up
}
@OnKey(KeyCode.ENTER)
public void onEnterPressed() {
// Called when the enter key is pressed
}
}When using Dagger, add the following snippet module to provide the FulibFxApp to internal components using your app class.
@Module
public class MainModule {
// ...
@Provides
FulibFxApp app(YourApp app) {
return app;
}
}The framework provides a simple way to navigate between controllers using the show method. The method takes a route
as an argument and displays the corresponding controller. The routes can be specified using a router class which gets
registered in the FulibFxApp class.
public class Router {
@Route("")
Provider<HomeController> home;
@Route("todo")
Provider<TodoController> todo;
@Route("todo/settings")
Provider<SettingsController> settings;
}When developing an application, it is often necessary to reload the application to see the changes. The framework provides
a way to refresh a controller's view without having to restart the whole application.
This can be done by calling the refresh method of the FulibFxApp class.
The framework provides an annotation processor that hooks into the Java compiler. It can check for various errors and warnings during compilation, allowing you to find problems early on without having to run the application. Additionally, the annotation processor generates auxiliary classes that encapsulate some of the functionality of your controllers and components, like calling the initialization methods or providing the title. This can greatly improve the performance at runtime and simplifies debugging by reducing stack traces and allowing you to debug the generated code. The annotation processor is optional but strongly recommended.
The framework provides a few utility classes and data structures to simplify the creation of JavaFX applications.
- Subscriber: A class to simplify the creation of subscriptions and to automatically dispose them when the controller is destroyed.
- For Loop: A class for creating a node for each element in a list.
- Internationalization: A way to use resource bundles in your controller and app title.
- Much more ...
The framework provides a comprehensive wiki with detailed information about all features and how to use them. It also includes a few examples to help you get started with the framework.
A list of all possible error codes can be found here.
All exceptions thrown by the framework are listed in the error code documentation.
When the framework throws an exception, it will print the error code and a short description of the error to the console.
If for example the error java.lang.IllegalArgumentException: Class '*' is not a component. [FFX1000] is thrown, you can
check the error code documentation for FFX1000 to find out what the error
means and how to fix it.
When using show("route/to/controller") without a leading "/", the route is relative to the currently displayed controller.
Meaning if you are currently displaying the controller "/foo/bar" and you call show("baz"), the route will be "/foo/bar/baz".
If you want to display a controller from the root, you have to start the route with a "/".
When refreshing a controller, the controller is destroyed and then reloaded with the same parameters as before. If an object has been passed as a parameter and the object has been modified during the lifetime of the controller, the already modified object will be passed after the refresh, just to be modified again. This can lead to unexpected behaviour. To avoid this, you should try to not modify objects passed as parameters. Instead, you should create a copy of the object and modify the copy or modify the object before passing it to the controller.
The framework uses an annotation processor to check if the view file exists.
If the view file is not found, the processor will throw an error.
Please make sure that the view file is in the correct location and that options.sourcepath is set correctly in your compileJava task (see Installation).
When using the SceneBuilder, it might not recognize your controller's FXML file. This can happen when the FXML file contains elements which are not present in the basic JavaFX library. To fix this, you can add a jar file containing the missing elements to the SceneBuilder. The simplest way is to build your project and then add the jar file by clicking on the small gear icon next to the search bar and selecting "JAR/FXML Manager". Then you can add the jar file by clicking on the "Add Library/FXML from file system" button.