Gluon Mobile Documentation

The jfxmobile plugin will first try to look if an androidSdk property has been set. If not, it will look for the ANDROID_HOME gradle property and finally resort to the ANDROID_HOME system environment variable.

You can get it from the NetBeans plugin portal, or you can directly install it from NetBeans: click Tools→Plugins. Now select Available Plugins…​ and find Gluon Plugin.

Select the plugin, click Install and follow the steps:

Accept the license and click Install:

Click Continue when prompted:

Wait until the Gluon Plugin is installed. And click Finish to restart the IDE.

You will find the plugin under the Installed tab:

Now that we have the plugin installed, we are going to use it to create a sample application.

In NetBeans, click File→New→Project…​ and select Gluon on the left, and one of the available projects on the right. For instance, Gluon Mobile - Single View Project. Press Next.

The first time you use the plugin, you will be asked to enter your email address.

If you already have a Gluon Mobile/Desktop license key for your projects, you can insert them here as well, so they will be added by default to your new projects. If you don’t, you will be using the free (trial) version. Please find more about Gluon Mobile licenses or Gluon Desktop licenses.

Once you have completed this first-time-only form, click Next.

Type the name of the project, find a proper location, add the package name and change the main class name if required. Note that you can select what platforms the project will be deployed to.

Press Finish and the project will be created and opened.

You will notice that a multi-project has been created, with a root project and the Gluon Mobile sub-project.

The plugin includes a series of tasks, and to access them we just need to right click on the root of the project and select Tasks. A menu will appear, showing all the available gradle tasks.

Before deploying on mobile it’s easier to run the application on desktop first and verify that there are no errors.

To do that, select run from the task list. Verify that all the tasks are executed without errors, and the project runs fine on your desktop.

Let’s make a slight change to the code. In the BasicView class, update the text of the label on line 21 to the following:

and run it again to see that the new message shows up on your desktop when you click the button.

Now you are ready for deploying on an Android or iOS device.

For Android, for instance, select android→android from the tasks list to create the apk or android→androidInstall if you have an Android device connected to your PC to create and deploy the apk on it.

After the build completes, the application should be installed on your device. Otherwise, check the output console for errors.

When the installation ends successfully, find the application on your device and open it up:

You can change your Gluon settings at any time. For that, on Windows or Linux go to NetBeans→Tools→Options→Miscellaneous, or on Mac, go to NetBeans→Preferences→Miscellaneous, and select Gluon tab. You will see your currrent settings and you will be able to modify them if needed.

If you have made it here without problems, congratulations!

If you have found any difficulties along the way, please review the lists of prerequisites and try again, and if the problems still persist, you can visit our Forums, and ask any question there if you don’t find a suitable solution.

We encourage you to start developing new projects that can be deployed on desktop, Android and iOS devices using the Gluon plugin on your favorite IDE.

You can get it from here, or you can directly install it from IntelliJ IDEA: click File→Settings and select Plugins on the left. You will see the installed plugins on your system.

Now click Browse Repositories…​, find Gluon Plugin, click Install plugin, and confirm installation:

The Gluon Plugin will be downloaded and installed. You may need to restart the IDE.

Now that we have the plugin installed, we are going to use it to create a sample application.

In IntelliJ IDEA, click File→New→Project…​ and select Gluon on the left, and one of the available projects on the right. For instance, Gluon Mobile - Single View Project. Press Next.

The first time you use the plugin, you will be asked to enter your email address.

If you already have a Gluon Mobile/Desktop license key for your projects, you can insert them here as well, so they will be added by default to your new projects. If you don’t, you will be using the free (trial) version. Please find more about Gluon Mobile licenses or Gluon Desktop licenses.

Once you have completed this first-time-only form, click Next.

Type the package name and the main class name. Note that you can select what platforms the project will be deployed to. Press Next.

Select a valid Java JDK and press Next.

Now add a name and a location for the project and press Finish.

IDEA detects we are trying to import a Gradle project, and asks us for some options. We can select the default ones:

Note that it is really convenient to set the ANDROID_HOME property in the .gradle/gradle.properties file in your user home directory. It should point to an Android SDK folder on your file system.

Press OK and the project will be imported and opened.

You will see the different folders were created:

There’s some default code in our main folders, so we’ll be able to run it without adding a single line of code.

The plugin includes a series of tasks, and to access them we just need to click View→Tool Windows→Gradle and a panel will show up on the right side revealing a list of all the available gradle tasks.

Before deploying on mobile it’s easier to run the application on desktop first and verify that there are no errors.

To do that, select application→run from the task list. Verify that all the tasks are executed without errors, and the project runs fine on your desktop.

Let’s make a slight change to the code. In the BasicView class, update the text of the label on line 21 to the following:

and run it again to see that the new message shows up on your desktop.

Now you are ready for deploying on an Android or iOS device.

For Android, for instance, select other→android from the tasks list to create the apk or other→androidInstall if you have an Android device connected to your PC to create and deploy the apk on it.

After the build completes, the application should be installed on your device. Otherwise, check the output console for errors.

Find the application and open it up:

You can change at any time your Gluon settings. For that, on Windows or Linux go to IntelliJ-IDEA→File→Settings→Other Settings, or on Mac, go to IntelliJ-IDEA→Preferences→Other Settings, and select Gluon. You will see your currrent settings and you will be able to modify them if needed.

If you have made it here without problems, congratulations!

If you have found any difficulties along the way, please review the lists of prerequisites and try again, and if the problems still persist, you can visit our Forums, and ask any question there if you don’t find a suitable solution.

We encourage you to start developing new projects that can be deployed on desktop, Android and iOS devices using the Gluon plugin on your favorite IDE.

Now that the plugin is installed, we can use it to create a sample application.

In Eclipse, click File→New→Project… and select and one of the available projects under the Gluon category, for instance, Gluon Mobile - Single View Project and click Next.

The first time you use the plugin, you will be asked to enter your email address.

If you already have a Gluon Mobile/Desktop license key for your projects, you can insert them here as well, so they will be added by default to your new projects. If you don’t, you will be using the free (trial) version. Please find more about Gluon Mobile licenses or Gluon Desktop licenses.

Once you have completed this first-time-only form, click Next.

Provide a name for the project, optionally choose a custom location to store the project and click Next.

The plugin will generate a JavaFX application class. In the following step you can configure the name of the package and the name of the class that will be generated. You can select what platforms the project will be deployed to, and the plugin will prepare the directory structure and necessary files for every selected platform. Click Finish to complete the creation of the Gluon project.

Please note, creating a Gluon project for the first time, might take a while to complete. This is because the gradle build process will initially download all the dependencies of the project.

You will see different folders were created:

There’s also the default JavaFX application class, so we’ll be able to run it without adding a single line of code.

The project that is created by the plugin is a Gradle project, which already has the jfxmobile-plugin applied. The jfxmobile-plugin provides a series of gradle tasks that can be used to run your application on any of the supported platforms.

To get an overview of the different tasks, open the Gradle Tasks view by selecting Window→Show View→Other…. You can find the view under the Gradle (STS) category.

In the Gradle Tasks view, select the project you just created in the Project combobox and it will load all the available gradle tasks.

Before deploying on mobile it’s easier to run the application on desktop first to verify there are no errors. Double click the run task from the list of tasks to launch the application on your desktop.

If all went fine we can make a small change to the code. In the BasicView class, update the text of the label on line 21 to the following:

Run the application again to verify that the text inside the label has changed. As a final task, we can try and install the application on a mobile device. Again, make sure that you have followed the prerequisites of the jfxmobile plugin for the platform that you are going to install the application to. When you are ready and your mobile device is plugged in, choose the task androidInstall for Android, or launchIOSDevice for iOS. Please note, that any of these tasks might take a while to complete. Especially for iOS, because when the task is run for the first time, it has to convert the entire RoboVM and JavaFX runtime to iOS native code.

If everything went successful, you should see something on your device like the screenshot below:

You can change at any time your Gluon settings. For that, on Windows or Linux go to Eclipse→Windows→Preferences→Gluon, or on Mac, go to Eclipse→Preferences→Gluon. You will see your currrent settings and you will be able to modify them if needed.

If you have made it this far without problems, congratulations!

If you have found any difficulties along the way, please review the prerequisites and try again. If the problems persist, you can visit our Support Forums and ask any question there if you don’t find a suitable solution.

We encourage you to start developing new applications that can be deployed on desktop, Android and iOS devices using the Gluon Plugin on your favorite IDE.

After having installed the plugin into your IDE, you can create a new project.

Even if you don’t want to use one of the IDE plugins, it’s easy to get started. You can clone our Gluon Samples repository at GitHub: https://github.com/gluonhq/gluon-samples and open the helloworld sample with your IDE or text editor to get you started. All of our samples are gradle projects, so you can run gradle tasks to build the application and run it on any of the three platforms.

If you already have an existing project using gradle, it’s very easy to include Gluon Mobile features.

Open up the build.gradle file (which in NetBeans is located under Build Scripts/Project) and add the Gluon Nexus repository http://nexus.gluonhq.com/nexus/content/repositories/releases/ to the repositories section. To be able to make use of Gluon Charm, you also need to add its dependencies. Your updated build.gradle file will now look something like this:

Clean and build the project and check that those dependencies are downloaded (only the first time).

Now that everything is in place, you can start including Charm features in your project.

Apart from the default dependency configurations compile and runtime, the jfxmobile plugin adds extra configurations for each supported platform. This allows developers to add dependencies that should only be applied to a specific platform. The names of the platform specific configurations are platformCompile and platformRuntime where platform can be one of the following: android, ios, desktop or embedded. The platform specific compile and runtime configurations extend from the default compile and runtime configuration respectively.

For instance, if your android code wants to do some json processing, you configure the dependencies as follows:

The dependency declared above will make sure the json library is only included when targetting the Android platform, e.g. when creating an APK or when installing it on an Android device. In other words, it won’t be part of an iOS build or when running the application directly on your desktop.

Retrolambda is a tool that converts classes that were compiled with Java 8 as the target into bytecode that can be run on a Java 6 runtime. Retrolambda is required for any Java code that needs to run on an Android device. That is because Android platforms before API 19 only support Java 6, while Java 7 is supported by Android platforms starting from API 19. More information about retrolambda can be read here.

When creating the Android APK of your application, the jfxmobile plugin will apply retrolambda to all compiled classes and to all classes from the dependencies that are found in the androidRuntime configuration. In short this applies to all libraries that are declared in either the compile, runtime, androidCompile or androidRuntime configurations. However, in some cases, applying retrolambda to a library that for instance has already been processed with retrolambda itself, can result in the following exception when running the application on an Android device.

In that case, you can use the compileNoRetrolambda or runtimeNoRetrolambda configurations to exclude the library from the retrolambda process. For instance, if you don’t want to apply retrolambda to the afterburner library, you can configure it with the following code:

In this configuration, all three dependencies will be included in the android application, but retrolambda will only be applied to the two gluon libraries, not to the afterburner library. Note that the afterburner version 1.6.3 can be used now with compile, as it doesn’t apply retrolambda anymore.

The MobileApplication class extends from Application, hence for Glisten-based applications it will be considered the base class.

Let’s have a look at the hierarchy of components added to generate the user interface.

In order to understand how Glisten works, let’s have a look at the initial JavaFX application lifecycle. Whenever an application is launched, the JavaFX runtime does the following:

Typically, the developer of a Glisten application will only override the init() method, in order to add one or more View objects, and provide them as factories that can be called on-demand. The MobileApplication implementation will take care of the rest: when start() is called, it will create a Scene, adding a root node to it. Finally, it will put the scene in the primary stage and show it.

When the runtime calls init(), we just provide a Supplier<View> for HOME_VIEW, but the view is not instantiated at this point yet.

Then start(Stage) is called. In this moment, MobileApplication creates an instance of Scene, sets the root an empty instance of a GlassPane and adds the scene to the primary stage.

After some internal settings, like adding the default Swatch, it calls switchView("HOME_VIEW"). This is the moment when an instance of the home view is created and added to the pane.

Finally the stage is shown.

Changing the default Swatch

What if we want to modify some scene settings before it is shown?

Before showing the stage, there’s a call to the postInit(Scene) method, that can be used by the developer for one time initialization.

In case the developer wants to change the swatch for each view, this can be done by listening to the changes in the viewProperty of a MobileApplication instance, and assigning the corresponding Swatch:

Another way to accomplish the same will be by adding a listener to each view’s showingProperty:

A Layer is an overlay that can be shown above any View.

Layers can be provided as factories by using MobileApplication.getInstance().addLayerFactory(), and can be shown on demand by using MobileApplication.getInstance().showLayer().

Layers can also be be shown and hidden, without the use of factories, by calling show() and hide() respectively.

By calling setBackgroundFade(double) the developer will be able to fade the background of a layer to a darker color, obscuring the main application and drawing focus to the popup.

Glisten comes with a collection of cross platform UI controls based on the Material Design Specification: Glisten Controls.

Glisten ships with two CSS themes: light and dark. Despite the connotation, the amount of CSS required to specify these themes is incredibly minimal - and as a courtesy is reproduced here:

There are a number of global properties that can be used by any application that uses Glisten. These properties allow for custom controls to be styled in a way that should relatively closely match up with the Glisten-styled controls. What follows is a list of such properties.

By default, when a UI control is instantiated in Glisten, the control does not receive any additional style classes over what is provided by the underlying JavaFX technology. However, depending on the use case for each individual control, it can make sense to apply additional style classes to have Glisten apply additional styling to these controls.

There exists a class called GlistenStyleClasses that is located in the com.gluonhq.glisten.visual package. This class provides a number of predefined style classes that can be applied to a control, via one of two methods:

Both approaches are more or less equivalent, but the second approach is recommended.

Once these additional style classes have been applied, both Glisten CSS and your own CSS can be applied as applicable. For example, a button that has been styled to be flat (using GlistenStyleClasses.BUTTON_FLAT) will be able to receive alternate styling via css such as the following:

Of course, as noted, any styling of UI controls based on style classes from the GlistenStyleClasses class will be styled differently by Glisten CSS, so there is no need (unless desired) to apply additional styling.

What follows is a list of additional CSS style classes that are available to some UI controls:

Buttons have the CSS style class .button. There are the following additional style classes that are available in Glisten:

Toggle buttons have the CSS style class .toggle-button.

If this document does not answer all your questions regarding Glisten CSS functionality, please reach out to Gluon staff and ask any questions. They will help us to improve future versions of this document.

Glisten 5.0.0 release has a significant number of breaking changes. For a detailed document on how to migrate to 5.0.0, please refer Migration Guide to Gluon Mobile 5.

Charm Down prerequisites are in line with those required by Gluon Mobile.

In addition to the Android Support repository, the Google repository needs to be installed from the Android SDK manager as well. From the SDK Tools section, select and install the latest version of Google Repository.

Each Charm Down service provides the functionality to access the device’s feature. Each of these services are accessed through a single class called com.gluonhq.charm.down.Services. To get a service, you use the Services.get() method, which returns an Optional that contains an instance of the requested service. The returned optional object might be empty if the runtime platform has no available implementation for that specific service.

Another useful class is the enum com.gluonhq.charm.down.Platform, which provides an easy way to detect what platform the application is currently running on: ANDROID, IOS or DESKTOP.

The Gluon samples contain many different use cases of different Charm Down services.

For an overview of all the available services, we refer you to the plugins package overview page in the Charm Down javadoc:

http://docs.gluonhq.com/charm/javadoc/5.1.0-SNAPSHOT/com/gluonhq/charm/down/plugins/package-summary.html

Each service has certain requirements that need to be addressed before deploying the mobile applications, either on Android or on iOS or both.

For instance, the Dialer service requires some modifications in the Android manifest file:

The service javadoc provides detailed info in each case.

During development, setting the system property "com.gluonhq.charm.down.debug" to true, before initializing the service, will enable a more verbose console output.

Don’t forget to remove it before the app is released.

This is the full build.gradle file:

If you clean and build the project, the dependencies will be downloaded the first time. On NetBeans, if you right-click on the project’s root and select Reload Project, the dependencies will show up under the Dependencies folder of the project. On IntelliJ, click on the refresh button on the Gradle Tool Window (View→Tool Windows→Gradle) to refresh the Gradle projects and you will see them under External Libraries in the Project Tool Window.

Have a look at the documentation for MobileApplication. This class should be considered as the base class for any Charm project, in a similar fashion that the Application class is for JavaFX applications.

In fact, MobileApplication extends from Application, and our class will extend it, so there is no need for a start method. We’ll add View instances on its constructor or by overriding the init method.

There is a postInit method that can be used for one time initialization, because it’s called once there is a valid scene instance. In this sample, we will install an indigo Swatch.

If you have a valid license key for Gluon Charm, add it to your application with the @License annotation, and you will avoid the initial nag popup dialog.

Views (check the docs) can be added easily, just by placing JavaFX nodes on the top, center or bottom of the View, or by using FXML files created with Scene Builder. In this sample, we’ll use the mobile-enabled version of the Afterburner MVP framework.

You can check the FXML file code. Besides the View pane, an Icon is used, selected from the MaterialDesignIcon list of icons, based on the Material Design style guide.

This sample uses Gluon CloudLink to store and synchronize data. The Data Storage section in the Gluon CloudLink documentation contains detailed information for the following steps.

Gluon CloudLink Portal

Before you can start using Gluon CloudLink, you will need to register your application. Go to the Gluon CloudLink Product page and click on "Sign up" under "Free".

Select Sign up and register for a new account (or login if you already have one). You will be able to see the dashboard with your existing applications and their key and secret tokens. As a word of advice, keep them safe and don’t send them to anyone.

The DataClientProvider class

We can now build a new DataClient, which is the access point to the Data Storage service of Gluon CloudLink.

The CommentsService class

Once you have a DataClient reference, you can retrieve data from and store data to Gluon CloudLink. In this case, the data will be a list with comments. The way we can get this list from this service is:

Finally, we wrap this observable list into an ObjectProperty in order to expose it to the view and bind it with the ListView content.

You can find out how the rest of the views are added to this application by following this link.

The version of the jfxmobile plugin has been updated to 1.1.0. Change the version at the top of the build.gradle file.

Gluon Mobile 4 requires only one dependency declaration instead of the four declarations that were needed previously. That will include the dependencies to Charm Glisten and Gluon Connect.

The dependency to Charm Down has been removed from the dependency defined above. This is because Charm Down has been refactored a bit. Previously, the Charm Down project bundled all the features in one jar dependency for the core classes and one jar dependency for each of the implemented platforms: android, ios and desktop. The disadvantage of this approach is that you can’t exclude certain features from your application. Since Gluon Mobile 4, Charm Down features have been divided into separate plugins, that allows a developer to choose which Charm Down feature he likes to include in his Gluon Mobile project. While doing that, we also increased the number of features from 10 to 21.

The current way of selecting a Charm Down plugin is done in the build.gradle file, using the new downConfig configuration. When using Gluon Mobile, the following four plugins are mandatory in the configuration: display, lifecycle, statusbar and storage.

This is the complete list of available plugins: accelerometer, barcode-scan, battery, ble, browser, cache, compass, connectivity, device, dialer, display, lifecycle, local-notifications, magnetometer, orientation, pictures, position, settings, statusbar, storage and vibration.

With jfxmobile plugin 1.1.0, building for android will apply retrolambda to all dependencies of the androidRuntime gradle configuration, while in previous versions, retrolambda was only applied to the compiled sources of the project. This means that all dependencies that are declared in compile, runtime, androidCompile and androidRuntime will be processed by retrolambda before handing it over to the android build tools for generating the android application bundle. Applying retrolambda to a dependency on which retrolambda was already applied will cause build failures. Examples of such dependencies are com.airhacks:afterburner.mfx:1.6.2 and de.jensd:fontawesomefx:8.8.

Two new configurations have been added to be able to exclude the dependency from the retrolambda process: compileNoRetrolambda and runtimeNoRetrolambda. It can be used in conjunction with the other configurations when declaring your dependencies:

In Gluon Mobile 3.x, accessing a Charm Down feature was done through the com.gluonhq.charm.down.common.PlatformFactory class. With the refactoring of Charm Down into separate plugins, the common package, along with its classes, have been removed. Starting from Gluon Mobile 4, accessing a feature is done through the com.gluonhq.charm.down.Services class by using the method named get(). This returns an instance of java.util.Optional containing the service implementation for the platform where the application is currently running on. The Optional will be empty if the service has no implementation for the specific platform, so be sure to always check if the returned Optional isn’t empty.

Another useful class is com.gluonhq.charm.down.Platform. Using this enum you can easily determine what platform the application is currently running on. For instance, you can execute code that should only be run on a desktop with the following code:

The minimum charm down version has been bumped to 3.8.0.

Significant changes have been made to the Gluon Mobile framework. Most of the changes are towards our continual effort to make it easier for developers to create mobile applications using Java. We have tried to maintain backward compatibility, however, some tweaking might be needed when you upgrade existing projects to Gluon Mobile 5.

Here are a list of changes that one needs to keep in mind while upgrading to 5.0.0.