README.md

A clean and easy way to implement this amazing native Windows taskbar-progressbar functionality in javaFX

Background

Since Windows 7 there is a taskbar-progressbar feature in Windows systems that basically means that you can see progress on the program's taskbar icon. A good example for this when you copy something using the file explorer:

This is very useful because you don't have to open the window to see the progress! The problem is that javaFX doesn't provide this functionality by default... however you can easily implement it with this library!

Compatibility

This library has support for java 8 and java 11 too.
The 'v11.x' versions are for java11 users and the 'v8.x' versions are for java 8 users.

Using with java 11

If you use java 11 you have to pass this VM argument: --add-exports javafx.graphics/com.sun.glass.ui=nativejavafx.taskbar. Also, you have to mention the nativejavafx.taskbar module in your module-info.java file:

module YourModule {
    ...
    requires nativejavafx.taskbar;
}

How to include it to your project

Maven example:

Add JitPack.io to your repositories :

<repositories>
   <repository>
     <id>jitpack.io</id>
     <url>https://jitpack.io</url>
   </repository>
</repositories>

Add the dependency:

<dependency>
	<groupId>com.github.Dansoftowner</groupId>
	<artifactId>FXTaskbarProgressBar</artifactId>
	<version>v11.4</version>
</dependency>

Gradle example

Add the repository:

repositories {
    //...
    maven { url 'https://jitpack.io' }
}

Add the dependency:

dependencies {
    //...
    implementation 'com.github.Dansoftowner:FXTaskbarProgressBar:v11.4'
}

Projects using FXTaskbarProgressBar

If this library is used by your project, let me know in the Discussions and I will mention that in this section.

Boomega - A modern book explorer & catalog application

How to use it Tutorial

0. Types of progressbar

Before we jump in, we have to know the 4 types of a taskbar-progressbar:

• NORMAL - a progressbar with normal green color
• PAUSED - a progressbar with a yellow color
• ERROR - a progressbar with a red color
• INDETERMINATE - a progressbar that doesn't show any fix progress
• NO_PROGRESS - a progressbar that doesn't show anything
  
  All these types are represented by the enum called com.nativejavafx.taskbar.TaskbarProgressbar.Type.

Now let's see how can we actually use this through code.
There are multiple ways to create taskbar progressbars with this library:

1.Through static methods:

Firstly you have to import the necessary class:

import com.nativejavafx.taskbar.TaskbarProgressbar; 

...and you have to show the javafx Stage before any operation:

primaryStage.show();

Then call the static method:

TaskbarProgressbar.showCustomProgress(primaryStage, 0.5, TaskbarProgressbar.Type.NORMAL);

Well, the code above looks okay, but it's not safe. This functionality isn't supported by every OS. For example on a Linux system it will definitely throw an UnsupportedSystemException because it's only available on Windows 7+ systems.
If you use static methods to create taskbar-progressbars you always have to check that the current OS supports this functionality!

So let's correct the code:

if (TaskbarProgressbar.isSupported()) {
    TaskbarProgressbar.showCustomProgress(primaryStage, 0.5, TaskbarProgressbar.Type.NORMAL);
}

...now it is safe!

Result:

You have to do a similar thing if you want to show an indeterminate progress:

if (TaskbarProgressbar.isSupported()) {
    TaskbarProgressbar.showIndeterminateProgress(primaryStage);
}

Result:

To stop the progress:

TaskbarProgressbar.stopProgress(primaryStage);

2. Through instantiation (the recommended way)

Firstly (after you imported the necessary class) create a TaskbarProgressbar instance with the help of TaskbarProgressbarFactory:

TaskbarProgressbar progressbar = TaskbarProgressbarFactory.getTaskbarProgressbar(primaryStage);

Before any operation you have to show the Stage:

primaryStage.show();

After that just use the created instance for the operations:

progressbar.showCustomProgress(0.5, TaskbarProgressbar.Type.NORMAL);

Note: in this case to check that the OS supports this functionality is unnecessary because the object checks it automatically!

The result is the same:

If you want an indeterminate process:

progressbar.showIndeterminateProgress();

To stop the progress:

progressbar.stopProgress();

Bonus features

A simple method for showing a fully loaded error progressbar

progressbar.showFullErrorProgress();
//equivalent to progressbar.showCustomProgress(100, 100, TaskbarProgressbar.Type.ERROR) 

Result:

Also:

progressbar.showFullNormalProgress();

progressbar.showFullPausedProgress();

More screenshots

Some more screenshots about what can you do with this library

• A paused progress example:
  Code: progressbar.showCustomProgress(0.7, TaskbarProgressbar.Type.PAUSED);
  
• An error progress example:
  Code: progressbar.showCustomProgress(0.4, TaskbarProgressbar.Type.ERROR);
  

Full demo

A full demo-example class is available here.

Source code

This project has two important branches:

• "master" - for java 8 builds
• "11" - for java 11 builds

Used libraries

• bridj - blazing fast Java / C / C++ interop
• SLF4J - Simple Logging Facade for Java
• Jetbrains Annotations - Annotations for JVM-based languages

Support

If you like this library give it a star!