Merge pull request #3 from RedlanceMinecraft/progressbars

In-dock progressbars

Author: dima-dencep

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Redlance
+Copyright (c) 2026 Redlance
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.MD

@@ -10,6 +10,9 @@
 * **[File Origin Metadata (Windows & macOS)](#3-file-origin--referrer):** Retrieve the source URL of downloaded files.
     * **macOS:** Reads `kMDItemWhereFroms` metadata.
     * **Windows:** Reads **Alternate Data Streams (ADS)**, specifically `Zone.Identifier`.
+* **[Taskbar Progress Bars](#4-taskbar-progress-bars):** Display progress indicators on the taskbar/dock icon.
+    * Supports multiple stacked progress bars (up to 8).
+    * *Note: Windows taskbar support is planned for future releases.*
 * **Java 8 Compatible:** Built on Java 17 but distributed with a Java 8 compatible version (Multi-Release JAR).
 
 ## 📦 Installation
@@ -114,7 +117,7 @@ public class ReferrerExample {
     public void printOrigin(File file) {
         try {
             Set<String> referrers = PlatformFileReferer.INSTANCE.getFileReferer(file);
-            
+
             if (!referrers.isEmpty()) {
                 System.out.println("File downloaded from:");
                 referrers.forEach(System.out::println);
@@ -128,6 +131,46 @@ public class ReferrerExample {
 }
 ```
 
+### 4. Taskbar Progress Bars
+Display progress indicators on the taskbar/dock icon. Supports multiple stacked progress bars.
+
+> **Note:** Windows taskbar support is currently in development. On Windows, these methods will currently perform no action.
+
+```java
+import org.redlance.platformtools.PlatformProgressBars;
+import org.redlance.platformtools.PlatformProgressBars.PlatformProgressBar;
+
+public class ProgressExample {
+    public void downloadFile() {
+        // Create a progress bar
+        try (PlatformProgressBar progress = PlatformProgressBars.INSTANCE.create()) {
+            progress.setMaxValue(100);
+
+            for (int i = 0; i <= 100; i++) {
+                progress.setValue(i);
+                Thread.sleep(50);
+            }
+        } // Automatically closes and removes from dock
+    }
+
+    public void multipleProgressBars() {
+        // Create multiple progress bars (up to 8)
+        PlatformProgressBar bar1 = PlatformProgressBars.INSTANCE.create();
+        PlatformProgressBar bar2 = PlatformProgressBars.INSTANCE.create();
+
+        bar1.setMaxValue(100);
+        bar2.setMaxValue(50);
+
+        bar1.setValue(75);
+        bar2.setValue(25);
+
+        // Clean up when done
+        bar1.close();
+        bar2.close();
+    }
+}
+```
+
 ## 🛠 System Requirements
 * **Java:** 8 or higher.
 * **Operating Systems:**

build.gradle

@@ -6,7 +6,7 @@ plugins {
 }
 
 base.archivesName = "PlatformTools"
-version = "3.1.5"
+version = "3.2.0"
 group = "org.redlance"
 
 repositories {

src/main/java/org/redlance/platformtools/PlatformProgressBars.java

@@ -0,0 +1,116 @@
+package org.redlance.platformtools;
+
+import org.redlance.platformtools.impl.PlatformProgressBarImpl;
+
+import java.io.Closeable;
+
+/**
+ * Factory interface for creating platform-specific progress bar indicators.
+ * <p>
+ * This interface provides a platform-agnostic way to display progress bars
+ * in native UI elements (such as the macOS dock icon).
+ * <p>
+ * Usage example:
+ * <pre>{@code
+ * PlatformProgressBars.PlatformProgressBar progressBar = PlatformProgressBars.INSTANCE.create();
+ * progressBar.setMaxValue(100);
+ * progressBar.display();
+ * progressBar.setValue(50);
+ * // ... when done
+ * progressBar.close();
+ * }</pre>
+ *
+ * @see PlatformProgressBar
+ * @see BasePlatformFeature#isAvailable()
+ */
+@SuppressWarnings("unused") // API
+public interface PlatformProgressBars extends BasePlatformFeature {
+    /**
+     * Singleton instance of the platform-specific progress bar factory.
+     */
+    PlatformProgressBars INSTANCE = new PlatformProgressBarImpl();
+
+    /**
+     * Creates a new platform-specific progress bar instance.
+     * <p>
+     * The returned progress bar is not visible until {@link PlatformProgressBar#display()} is called.
+     *
+     * @return a new {@link PlatformProgressBar} instance
+     * @throws TooManyProgressBarsException if the maximum number of progress bars has been reached
+     */
+    PlatformProgressBar create() throws TooManyProgressBarsException;
+
+    /**
+     * Represents a platform-specific progress bar that can be displayed
+     * in native UI elements.
+     */
+    interface PlatformProgressBar extends Closeable {
+        /**
+         * Displays the progress bar in the native UI element.
+         * <p>
+         * This method should be called after configuring the progress bar
+         * with {@link #setMaxValue(double)} and optionally {@link #setValue(double)}.
+         */
+        void display();
+
+        /**
+         * Removes the progress bar from the native UI element.
+         * <p>
+         * After calling this method, the progress bar will no longer be visible.
+         */
+        @Override
+        void close();
+
+        /**
+         * Increments the current progress value by the specified amount.
+         *
+         * @param progress the amount to add to the current value
+         */
+        void incrementBy(double progress);
+
+        /**
+         * Sets the maximum value of the progress bar.
+         *
+         * @param maxValue the maximum progress value
+         */
+        void setMaxValue(double maxValue);
+
+        /**
+         * Sets the current progress value.
+         *
+         * @param value the current progress value (should be between 0 and maxValue)
+         */
+        void setValue(double value);
+
+        /**
+         * Sets whether the progress bar is in indeterminate mode.
+         * <p>
+         * In indeterminate mode, the progress bar shows an animated state
+         * indicating that work is in progress but the amount is unknown.
+         *
+         * @param indeterminate true for indeterminate mode, false for determinate
+         */
+        void setIndeterminate(boolean indeterminate);
+    }
+
+    /**
+     * Thrown when attempting to create more progress bars than the platform supports.
+     */
+    class TooManyProgressBarsException extends RuntimeException {
+        private final int maxAllowed;
+
+        public TooManyProgressBarsException(int maxAllowed) {
+            super("Too many progress bars. Maximum allowed: " + maxAllowed);
+            this.maxAllowed = maxAllowed;
+        }
+
+        /**
+         * Returns the maximum number of progress bars allowed on this platform.
+         *
+         * @return maximum allowed progress bars
+         */
+        public int getMaxAllowed() {
+            return this.maxAllowed;
+        }
+    }
+}

src/main/java/org/redlance/platformtools/impl/PlatformProgressBarImpl.java

@@ -0,0 +1,24 @@
+package org.redlance.platformtools.impl;
+
+import com.sun.jna.Platform;
+import org.jetbrains.annotations.NotNull;
+import org.redlance.platformtools.PlatformProgressBars;
+import org.redlance.platformtools.impl.macos.MacProgressBar;
+import org.redlance.platformtools.impl.unsupported.UnsupportedPlatform;
+
+public class PlatformProgressBarImpl implements PlatformProgressBars {
+    private final @NotNull PlatformProgressBars nativeProgressBar = switch (Platform.getOSType()) {
+        case Platform.MAC -> new MacProgressBar();
+        default -> UnsupportedPlatform.INSTANCE;
+    };
+
+    @Override
+    public PlatformProgressBar create() {
+        return this.nativeProgressBar.create();
+    }
+
+    @Override
+    public boolean isAvailable() {
+        return this.nativeProgressBar.isAvailable();
+    }
+}

src/main/java/org/redlance/platformtools/impl/TestingApp.java

@@ -3,6 +3,7 @@
 import org.redlance.platformtools.PlatformAccent;
 import org.redlance.platformtools.PlatformFileReferer;
 import org.redlance.platformtools.PlatformFinderFavorites;
+import org.redlance.platformtools.PlatformProgressBars;
 
 import javax.swing.*;
 import java.awt.*;
@@ -17,7 +18,7 @@ public class TestingApp extends JFrame {
 
     public TestingApp(Color initialColor) {
         setTitle("Color Window");
-        setSize(400, 300);
+        setSize(640, 480);
         setDefaultCloseOperation(EXIT_ON_CLOSE);
         setLocationRelativeTo(null);
 
@@ -35,6 +36,10 @@ public void mouseMoved(MouseEvent e) {
         JPanel controlsPanel = new JPanel();
         add(controlsPanel, BorderLayout.SOUTH);
 
+        JButton progressBarButton = new JButton("Progress Bar");
+        progressBarButton.addActionListener(this::onProgressBar);
+        controlsPanel.add(progressBarButton);
+
         JButton pinFolderButton = new JButton("Pin folder");
         pinFolderButton.addActionListener(this::onPinFolder);
         controlsPanel.add(pinFolderButton);
@@ -168,4 +173,54 @@ private void onRecreate(ActionEvent e) {
         setVisible(true);
         PlatformAccent.INSTANCE.resubscribe();
     }
+
+    private void onProgressBar(ActionEvent e) {
+        showProgressDialog();
+    }
+
+    private void showProgressDialog() {
+        JDialog dialog = new JDialog(this, "Progress Bars Manager", false);
+        dialog.setSize(400, 300);
+        dialog.setLocationRelativeTo(this);
+        dialog.setLayout(new BorderLayout());
+
+        JPanel barsPanel = new JPanel();
+        barsPanel.setLayout(new BoxLayout(barsPanel, BoxLayout.Y_AXIS));
+        JScrollPane scrollPane = new JScrollPane(barsPanel);
+        dialog.add(scrollPane, BorderLayout.CENTER);
+
+        JButton addButton = new JButton("Add Progress Bar");
+        addButton.addActionListener(event -> {
+            PlatformProgressBars.PlatformProgressBar bar = PlatformProgressBars.INSTANCE.create();
+            bar.setMaxValue(100);
+
+            JPanel barPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
+            barPanel.setBorder(BorderFactory.createEtchedBorder());
+
+            JLabel label = new JLabel("Bar " + (barsPanel.getComponentCount() + 1) + ":");
+
+            JSlider slider = new JSlider(0, 100, 0);
+            slider.setPreferredSize(new Dimension(200, 30));
+            slider.addChangeListener(ev -> bar.setValue(slider.getValue()));
+
+            JButton removeButton = new JButton("X");
+            removeButton.addActionListener(ev -> {
+                bar.close();
+                barsPanel.remove(barPanel);
+                barsPanel.revalidate();
+                barsPanel.repaint();
+            });
+
+            barPanel.add(label);
+            barPanel.add(slider);
+            barPanel.add(removeButton);
+
+            barsPanel.add(barPanel);
+            barsPanel.revalidate();
+            barsPanel.repaint();
+        });
+
+        dialog.add(addButton, BorderLayout.SOUTH);
+        dialog.setVisible(true);
+    }
 }