Skip to content

Commit 1a4a40c

Browse files
kaifoxkaifox
committed
first version of organization page
1 parent 08f9710 commit 1a4a40c

5 files changed

+218
-2
lines changed

‎README.md

+209-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,209 @@
1-
# minifx.github.io
2-
The github organization page for minifx (also linked from minifx.org)
1+
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/fc1500db4cb34e398616c2085a509612)](https://app.codacy.com/app/minifx-developers/minifx-workbench?utm_source=github.com&utm_medium=referral&utm_content=minifx/minifx-workbench&utm_campaign=Badge_Grade_Dashboard)
2+
[![GitHub release](https://img.shields.io/github/release/minifx/minifx-workbench.svg)](https://github.com/minifx/minifx-workbench/releases/)
3+
[![Build Status](https://travis-ci.com/minifx/minifx-workbench.svg?branch=master)](https://travis-ci.com/minifx/minifx-workbench)
4+
[![License](https://img.shields.io/github/license/minifx/minifx-workbench.svg)](https://opensource.org/licenses/Apache-2.0)
5+
[![codecov](https://codecov.io/gh/minifx/minifx-workbench/branch/master/graph/badge.svg)](https://codecov.io/gh/minifx/minifx-workbench)
6+
7+
8+
# MiniFx Workbench
9+
10+
We believe that organizing java applications inside a dependency-injection container (like spring) is (almost) always beneficial.
11+
Even when writing GUIs. Doing so makes such applications very modular. Further, we wanted to organize our applications
12+
in a workbench manner (e.g. like eclipse does), but without a big overhead of osgi or similar. Based on these two premises, minifx-workbench was born:
13+
It is based on spring and additional custom annotations.
14+
15+
## Gradle
16+
17+
To add a dependency on minifx-workbench in gradle, add the following to your ```build.gradle``` file:
18+
19+
```gradle
20+
dependencies {
21+
compile "org.minifx:minifx-workbench:x.x.x"
22+
}
23+
```
24+
25+
```x.x.x``` corresponds to the latest version, which can be found at the top of this page.
26+
27+
## Maven
28+
29+
To add a dependency on minifx-workbench in maven, add the following to your ```pom.xml``` file:
30+
31+
```xml
32+
<dependency>
33+
<groupId>org.minifx</groupId>
34+
<artifactId>minifx-workbench</artifactId>
35+
<version>x.x.x</version>
36+
</dependency>
37+
```
38+
39+
```x.x.x``` corresponds to the latest version, which can be found at the top of this page.
40+
41+
42+
43+
## The Workbench
44+
When organizing our javafx applications in a workbench-like manner within minifx, then we have to understand two
45+
main concepts:
46+
* __perspectives:__ If you are familiar with e.g. eclipse, then you know intuitively what we mean by this:
47+
In short, perspectives are kind of pages within a GUI, in which several views can be arranged. All views in
48+
one perspective are visible at the same time. Perspectives can be switched by buttons in a toolbar at the right
49+
top corner of the application.
50+
* __views__: A view can be any javafx node which can be placed within a perspective. Per default each perspective
51+
is organized like a border layout, so each view can be placed either left, right, top, bottom or center within
52+
the perspective.
53+
54+
### The most simplistic example
55+
Lets assume, we have a spring configuration class that defines one bean:
56+
```java
57+
@Configuration
58+
public class SimplisticConfiguration {
59+
60+
@View
61+
@Bean
62+
public Label helloWorldLabel() {
63+
return new Label("Hello World");
64+
}
65+
66+
}
67+
```
68+
Note the custom annotation ```@View``` on the factory method of the bean: It tells minifx to place this bean as a
69+
view within the application. This can be further customized, as we will see later.
70+
71+
A simple application can then be run by the following main method:
72+
```java
73+
public class SimplisticMiniFxApplication {
74+
public static void main(String... args) {
75+
MiniFx.launcher(SimplisticConfiguration.class).launch(args);
76+
}
77+
}
78+
```
79+
80+
This would bring up something like this:
81+
82+
![SimplisticMiniFxApplication](images/SimplisticMiniFxApplication.PNG "SimplisticMiniFxApplication")
83+
84+
### Defining Custom Perspectives
85+
As seen in the simplistic example, per default MiniFx creates one perspective (the 'Default perspective') in which it
86+
places all the views for which nothing else is specified. Usually, we want to group our views in different perspectives.
87+
The minimal thing to define a new perspective, is to create an interface (or a class) that inherits from
88+
[```Perspective```](https://github.com/minifx/minifx-workbench/blob/master/src/java/org/minifx/workbench/domain/Perspective.java).
89+
90+
For example, we could create a new perspective like:
91+
```java
92+
public interface DebugPerspective extends Perspective {}
93+
```
94+
95+
This then could be used in a configuration like:
96+
```java
97+
@Configuration
98+
public class ConfigurationWithCustomPerspective {
99+
100+
@View(in = DebugPerspective.class, at = CENTER)
101+
@Bean
102+
public Label helloWorldLabel() {
103+
return new Label("Hello World");
104+
}
105+
106+
}
107+
```
108+
In this example, the ```@View``` applied to the bean specifies that the bean shall be put at the center of the debug perspective.
109+
110+
### MiniFx Configuration by Annotations
111+
MiniFx is configured through custom annotations which complement the spring built in annotations for the purpose of layouting GUIs.
112+
As shown in the previous examples, it is very easy to bootstrap a javafx application with minifx. MiniFx assumes
113+
proper defaults so that all the views are displayed in the application. However, usually we want to have a bit more
114+
fine-grained control how our components are layed out. This can be achieve with a combination of annotations, partially
115+
particular to minifx, partially spring built-in annotations.
116+
117+
Some general remarks:
118+
* All of the annotations described in the following can be placed on both factory methods and types (e.g. on classes
119+
annotated with the spring ```@Component``` or ```@Service``` annotation). Most of them can be used on both, views and
120+
perspectives (where they always will be placed on the type, as perspectives are types).
121+
* The MiniFx custom annotations do __NOT REPLACE__ the spring annotations like ```@Bean``` or ```@Component```. As long
122+
as a view is not detected as a bean in the spring context, the minifx annotations have no effect and the views will be
123+
not be shown in the application.
124+
* For the moment, we assume that all the beans which shall become views in MiniFx have to be javafx nodes already.
125+
However, as we will see later, there are extensions (built-in or custom ```NodeCreator```s) which lift this constraints.
126+
127+
When layouting the final application, MiniFx follows the following procedure:
128+
1. It collects all the beans which are annotated by a ```@View``` annotation, either on their type or their factory method.
129+
2. It extracts the display information from the annotations converts the beans to javafx nodes (See NodeCreators for more details)
130+
3. It collects all used perspectives from the views. Perspectives in which no nodes are shown, will not be visible in the final layout.
131+
4. It creates a pane for each used perspective and places the views accordingly (left, right, bottom, top, center).
132+
If more then one view shall be placed into the same position in the same perspective, then automatically a tab pane is
133+
created at this position.
134+
135+
The following table lists the annotations to be used for configuring components within MiniFx:
136+
137+
| Annotation | Can be used on | Description | Default Value (if not specified)
138+
|----------|-----------|------------|--------|
139+
|[```@View```](https://github.com/minifx/minifx-workbench/blob/master/src/java/org/minifx/workbench/annotations/View.java)| View | Specifies in which perspective and at what position the node represented by the given bean shall be placed.| CENTER in the default perspective|
140+
|[```@Name```](https://github.com/minifx/minifx-workbench/blob/master/src/java/org/minifx/workbench/annotations/Name.java)| View, Perspective, Footer | Specifies the name which shall be used for displaying the view/perspective | The name of the bean if constructed by a factory method, otherwise the class name of the view/perspective. |
141+
|[```@Icon```](https://github.com/minifx/minifx-workbench/blob/master/src/java/org/minifx/workbench/annotations/Icon.java)| View, Perspective, Footer | Specifies the icon and its color for a view/perspective | a default icon in black |
142+
|[```@Order```](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/annotation/Order.html)|View, Perspective, Footer | Per default, minifx guarantees no order when it inserts Views and Footers. However, if an integer value for the order is provided through this spring-internal annotation, then this is taken into account when placing perspectives, views at the same position and footers. | No order guaranteed. |
143+
|[```@Footer```](https://github.com/minifx/minifx-workbench/blob/master/src/java/org/minifx/workbench/annotations/Icon.java)|Footer | Specifies that the given bean shall be laid out as a footer in the workbench. This is basically a view outside of all perspectives, placed at the lower part of the GUI and thus always visible. | If no footer specified, the footer region is suppressed. |
144+
|[```@ToolbarItem```](https://github.com/minifx/minifx-workbench/blob/master/src/java/org/minifx/workbench/annotations/ToolbarItem.java)|ToolbarItem | Specifies that the given bean shall be placed in the toolbar. This item is NOT converted and thus has to be a javafx Node! No order is guaranteed! | |
145+
146+
147+
### Supported Views
148+
As already briefly mentioned above, different type of beans are supported out of the box to be placed as views inside
149+
minifx workbench. The following table lists, what view will be created if a ```@View``` annotation is place on
150+
different type of beans:
151+
152+
| Bean Type | Resulting View |
153+
|-----------|----------------|
154+
| JavaFx Node | This is the most common and most basic use case. The node itself is put as view into the GUI. |
155+
| Swing Component | Will be wrapped into a javfx SwingNode. |
156+
| URL or String starting with 'http://' or 'https://'| Will be converted into a WebView which displays the given URL.|
157+
158+
## Some more examples
159+
160+
* An example, demonstrating some more of the minifx features, can be found in the test package under
161+
[org/minifx/workbench/examples/simpledemo](https://github.com/minifx/minifx-workbench/blob/master/src/test/org/minifx/workbench/examples/simpledemo).
162+
When running the [corresponding main class](https://github.com/minifx/minifx-workbench/blob/master/src/test/org/minifx/workbench/examples/simpledemo/DemoMain.java),
163+
it looks somehow like this:
164+
![ChartDemo](images/ChartDemo.PNG "ChartDemo")
165+
166+
* Another example, with even more views, can be found in the test package under
167+
[org/minifx/workbench/conf/fullyconfigured](https://github.com/minifx/minifx-workbench/blob/master/src/test/org/minifx/workbench/conf/fullyconfigured).
168+
The corresponding screenshot is not so beautiful, but still can be found here: [docs/images/FullyConfiguredExample.PNG](images/FullyConfiguredExample.PNG)
169+
170+
## Launching other JavaFx applications from spring contexts
171+
172+
In the background, MiniFx uses a proprietary launcher to construct javafx applications from spring context.
173+
This launcher can be also used to launch general javafx applications from spring contexts, even if the features
174+
of the workbench are not intended to be used.
175+
176+
Assuming, we would have a spring configuration class ```MyConfiguration```, which provides _exactly one(!)_ scene
177+
in its resulting application context, then we can launch a new javafx application like this:
178+
179+
```java
180+
public class MyJavaFxApplication {
181+
public static void main(String... args) {
182+
SingleSceneSpringJavaFxApplication.launcher().configurationClasses(MyConfiguration.class).launch(args);
183+
}
184+
}
185+
```
186+
187+
Note that in this case, ```MyJavaFxApplication``` does not inherit from ```javafx.application.Application```.
188+
189+
The reason for this proprietary launcher is that at a first glance,
190+
it is not trivial to bootstrap a javafx application from a spring context:
191+
All the javafx components have to be created within the javafx thread. This is usually accomplished
192+
by inheriting from ```javafx.application.Application``` and overriding the ```start(Stage primaryStage)```
193+
method. However, when using spring we want already our primary stage to be configured (e.g. autowired)
194+
by spring...
195+
196+
#### Optional Launcher Parameters
197+
To Further customize the resulting application, the javafx launcher has some more options. For example:
198+
```java
199+
public class MyJavaFxApplication {
200+
public static void main(String... args) {
201+
SingleSceneSpringJavaFxApplication.launcher()
202+
.configurationClasses(MyConfiguration.class)
203+
.windowTitle("First JavaFx Application")
204+
.windowCloseHandler(evt -> System.exit(0))
205+
.launch(args);
206+
}
207+
}
208+
```
209+
This provides a custom window title and an handler for the event of closing the window.

‎images/ChartDemo.PNG

60.7 KB
Loading

‎images/FullyConfiguredExample.PNG

131 KB
Loading

‎images/SimplisticMiniFxApplication.PNG

10.8 KB
Loading

‎minifx.github.io.iml

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<module type="WEB_MODULE" version="4">
3+
<component name="NewModuleRootManager" inherit-compiler-output="true">
4+
<exclude-output />
5+
<content url="file://$MODULE_DIR$" />
6+
<orderEntry type="inheritedJdk" />
7+
<orderEntry type="sourceFolder" forTests="false" />
8+
</component>
9+
</module>

0 commit comments

Comments
 (0)