Implement desktop integrations in Platform plugins

A new DesktopIntegrationProvider interface adds on to Platform plugin
functions, enabling them to query and modify the state of desktop-level
integrations, including web links support and desktop icon presence.

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: ctrueden

README.md

@@ -1,66 +1,267 @@
+# scijava-desktop
+
 [![Build Status](https://github.com/scijava/scijava-desktop/actions/workflows/build.yml/badge.svg)](https://github.com/scijava/scijava-desktop/actions/workflows/build.yml)
 
-This component provides supporting code for SciJava applications
-to manage their integration with the system native desktop:
+Unified desktop integration for SciJava applications.
 
-* SciJava Platform plugins for macOS and Windows
-* A links subsystem to handle URI-based links via plugins
+## Features
 
-The scijava-desktop component requires Java 11 as a minimum, due
-to its use of java.awt.Desktop features not present in Java 8.
+The scijava-desktop component provides three kinds of desktop integration:
 
-## Features
+1. **URI Link Scheme Registration & Handling**
+   - Register custom URI schemes (e.g., `myapp://`) with the operating system
+   - Handle URI clicks from web browsers and other applications
+   - Automatic scheme registration on application startup
+
+2. **Desktop Icon Generation**
+   - Linux: `.desktop` file creation in application menus
+   - Windows: Start Menu shortcuts (planned)
+   - macOS: Application bundle support
+
+3. **File Extension Registration** (planned)
+   - Associate file types with your application
+   - Platform-specific MIME type handling
+
+## Platform Support
+
+- **Linux**: Full support for URI schemes and desktop icons via `.desktop` files
+- **Windows**: URI scheme registration via Windows Registry (desktop icons planned)
+- **macOS**: Read-only support (configuration via Info.plist at build time)
+
+## Requirements
+
+- Java 11 or later (due to use of `java.awt.Desktop` features)
+- Platform-specific tools:
+  - Linux: `xdg-utils` (for `xdg-mime` and `update-desktop-database`)
+  - Windows: `reg` command (built-in)
+  - macOS: No runtime dependencies
+
+## Quick Start
 
-- **Link handling**: Register custom handlers for URI schemes through the `LinkHandler` plugin interface
-- **CLI integration**: Automatic handling of URI arguments passed on the command line via `ConsoleArgument`
-- **OS integration**: Automatic registration of URI schemes with the operating system (Windows supported, macOS/Linux planned)
+### 1. Add Dependency
 
-## Usage
+```xml
+<dependency>
+    <groupId>org.scijava</groupId>
+    <artifactId>scijava-desktop</artifactId>
+    <version><!-- latest version --></version>
+</dependency>
+```
+
+### 2. Configure System Properties
 
-### Creating a Link Handler
+Set these properties when launching your application:
 
-Implement the `LinkHandler` interface to handle custom URI schemes:
+```bash
+java -Dscijava.app.executable="/path/to/myapp" \
+     -Dscijava.app.name="My Application" \
+     -Dscijava.app.icon="/path/to/icon.png" \
+     -jar myapp.jar
+```
+
+### 3. Create a LinkHandler Plugin
 
 ```java
+package com.example;
+
+import org.scijava.desktop.links.AbstractLinkHandler;
+import org.scijava.desktop.links.LinkHandler;
+import org.scijava.plugin.Plugin;
+
+import java.net.URI;
+import java.util.Arrays;
+import java.util.List;
+
 @Plugin(type = LinkHandler.class)
-public class MyLinkHandler extends AbstractLinkHandler {
+public class MyAppLinkHandler extends AbstractLinkHandler {
 
     @Override
-    public boolean supports(URI uri) {
+    public boolean supports(final URI uri) {
         return "myapp".equals(uri.getScheme());
     }
 
     @Override
-    public void handle(URI uri) {
-        // Handle the URI
+    public void handle(final URI uri) {
+        // Handle the URI (e.g., open a file, navigate to a view)
         System.out.println("Handling: " + uri);
     }
 
     @Override
     public List<String> getSchemes() {
-        // Return schemes to register with the OS
+        // Schemes to register with the OS
         return Arrays.asList("myapp");
     }
 }
 ```
 
-### OS Registration
+### 4. Launch and Test
 
-On Windows, URI schemes returned by `LinkHandler.getSchemes()` are automatically registered
-in the Windows Registry when the `LinkService` initializes. This allows users to click
-links like `myapp://action` in web browsers or other applications, which will launch your
-Java application with the URI as a command-line argument.
+1. Start your application
+2. The `myapp://` scheme is automatically registered with your OS
+3. Click a `myapp://action?param=value` link in your browser
+4. Your application launches and handles the URI
 
-The registration uses `HKEY_CURRENT_USER` and requires no administrator privileges.
+## Architecture
 
-See [doc/WINDOWS.md](doc/WINDOWS.md) for details.
+### Link Handling System
 
-## Architecture
+- **LinkService**: Service for routing URIs to appropriate handlers
+- **LinkHandler**: Plugin interface for implementing URI handlers
+- **LinkArgument**: Console argument plugin for command-line URI handling
+- **SchemeInstaller**: Platform-specific OS registration
+
+### Platform Integration
+
+- **Platform Plugins**: LinuxPlatform, WindowsPlatform, MacOSPlatform
+- **DesktopIntegrationProvider**: Interface for querying/toggling desktop features
+- **OptionsDesktop**: User-facing options plugin (Edit > Options > Desktop...)
+
+### State Management
+
+Desktop integration state is queried directly from the OS (not saved to preferences):
+- On load: Query OS for current registration state
+- On save: Apply changes directly to OS (e.g. registry, .desktop files)
+- Keeps UI in sync with actual OS state
+
+## System Properties
+
+| Property                   | Description                    | Platforms | Required                                                  |
+|----------------------------|--------------------------------|-----------|-----------------------------------------------------------|
+| `scijava.app.executable`   | Path to application executable | All       | Yes (for URI schemes)                                     |
+| `scijava.app.name`         | Application name               | All       | No (default: "SciJava")                       |
+| `scijava.app.icon`         | Icon path                      | All       | No                                                        |
+| `scijava.app.directory`    | Application directory          | All       | No                                                        |
+| `scijava.app.desktop-file` | Override .desktop file path    | Linux     | No (default: `~/.local/share/applications/<app>.desktop`) |
+
+## User Interface
+
+Users can manage desktop integration via **Edit > Options > Desktop...** in your application:
+
+- **Enable web links**: Register/unregister URI schemes
+- **Add desktop icon**: Install/remove application launcher
+
+The UI automatically grays out features that are not available on the current platform.
+
+## Documentation
+
+- [doc/WINDOWS.md](doc/WINDOWS.md) - Windows Registry-based URI scheme registration
+
+## Examples
+
+### Parse URI Components
+
+```java
+import org.scijava.desktop.links.Links;
+
+URI uri = new URI("myapp://view/document?id=123&mode=edit");
+
+String operation = Links.operation(uri);  // "view"
+List<String> pathFragments = Links.pathFragments(uri);  // ["view", "document"]
+Map<String, String> query = Links.query(uri);  // {"id": "123", "mode": "edit"}
+```
+
+### Multiple Schemes
+
+```java
+@Plugin(type = LinkHandler.class)
+public class MultiSchemeLinkHandler extends AbstractLinkHandler {
+
+    @Override
+    public boolean supports(final URI uri) {
+        String scheme = uri.getScheme();
+        return "myapp".equals(scheme) || "myapp-dev".equals(scheme);
+    }
+
+    @Override
+    public void handle(final URI uri) {
+        if ("myapp-dev".equals(uri.getScheme())) {
+            // Handle development scheme
+        } else {
+            // Handle production scheme
+        }
+    }
+
+    @Override
+    public List<String> getSchemes() {
+        return Arrays.asList("myapp", "myapp-dev");
+    }
+}
+```
+
+## Platform-Specific Details
+
+### Linux
+
+URI schemes are registered by:
+1. Creating a `.desktop` file in `~/.local/share/applications/`
+2. Adding `x-scheme-handler/<scheme>` to the MimeType field
+3. Registering with `xdg-mime default <app>.desktop x-scheme-handler/<scheme>`
+4. Updating the desktop database with `update-desktop-database`
+
+Desktop icons are created by installing the `.desktop` file with appropriate fields (Name, Exec, Icon, Categories).
+
+### macOS
+
+URI schemes are declared in the application's `Info.plist` file within the `.app` bundle. This is configured at build time (bundle is code-signed and immutable), so runtime registration is not supported.
 
-- `LinkService` - Service for routing URIs to appropriate handlers
-- `LinkHandler` - Plugin interface for implementing custom URI handlers
-- `LinkArgument` - Console argument plugin that recognizes URIs on the command line
-- `SchemeInstaller` - Interface for OS-specific URI scheme registration
-- `WindowsSchemeInstaller` - Windows implementation using registry commands
+The MacOSPlatform correctly reports read-only status for all desktop integration features.
 
-The launcher should set the `scijava.app.executable` system property to enable URI scheme registration.
+### Windows
+
+URI schemes are registered in the Windows Registry under `HKEY_CURRENT_USER\Software\Classes\<scheme>`. No administrator privileges are required.
+
+The registry structure:
+```
+HKCU\Software\Classes\myapp
+    (Default) = "URL:myapp"
+    URL Protocol = ""
+    shell\open\command\
+        (Default) = "C:\Path\To\App.exe" "%1"
+```
+
+## Known Issues
+
+### Hardcoded Elements (Needs Fixes)
+
+1. **Hardcoded "fiji" scheme**: WindowsPlatform:86,102 and LinuxPlatform:112,129 hardcode the "fiji" scheme instead of querying LinkHandler plugins.
+   - Impact: Only works for Fiji application
+   - Fix: See NEXT.md Work Item #1
+
+2. **Hardcoded OS checks**: DefaultLinkService:119-132 directly checks OS name instead of using PlatformService.
+   - Impact: Violates plugin architecture
+   - Fix: See NEXT.md Work Items #2 and #3
+
+### Missing Features
+
+- File extension registration
+- Windows desktop icon (Start Menu shortcut)
+- First launch dialog for opt-in
+
+See [NEXT.md](NEXT.md) for details on planned improvements.
+
+## Manual Testing
+
+**Windows**:
+```bash
+# Check registry after running your app
+regedit
+# Navigate to HKCU\Software\Classes\myapp
+```
+
+**Linux**:
+```bash
+# Check .desktop file
+cat ~/.local/share/applications/myapp.desktop
+
+# Check MIME associations
+xdg-mime query default x-scheme-handler/myapp
+```
+
+**Test URI handling**:
+```bash
+# Linux/macOS
+xdg-open "myapp://test"
+
+# Windows
+start "myapp://test"
+```