feat: pluggable ClipboardProvider for UIText

gradle/common.gradle

@@ -18,10 +18,11 @@ dependencies {
 animalsniffer {
     // java.nio.* APIs can be desugared by D8. java.io.File.toPath() also needs to be excluded.
     //
-    // java.awt.Toolkit/datatransfer.* genuinely don't exist on Android at all - UIText.AwtClipboard
-    // isolates that usage behind a LinkageError-catching caller so it degrades gracefully instead
-    // of crashing, but the check itself can't be satisfied for a real platform absence like this
-    // one, so it's excluded here rather than by leaving the whole check non-fatal.
+    // java.awt.Toolkit/datatransfer.* genuinely don't exist on Android at all - AwtClipboardProvider
+    // (UIText's pluggable, but default, ClipboardProvider) isolates that usage behind a
+    // LinkageError-catching caller so it degrades gracefully instead of crashing, but the check
+    // itself can't be satisfied for a real platform absence like this one, so it's excluded here
+    // rather than by leaving the whole check non-fatal.
     ignore = ['java.nio.file.*', 'java.io.File', 'java.awt.Toolkit', 'java.awt.datatransfer.*']
 }
 

nui-input/src/main/java/org/terasology/input/device/ClipboardProvider.java

@@ -0,0 +1,22 @@
+// Copyright 2020 The Terasology Foundation
+// SPDX-License-Identifier: Apache-2.0
+package org.terasology.input.device;
+
+/**
+ * Abstracts system clipboard access so widgets aren't tied to one platform's clipboard API - desktop
+ * Java has java.awt, Android has its own android.content.ClipboardManager, GWT/HTML has neither.
+ * Implementations are supplied by whatever backend the application is running under (see
+ * nui-libgdx's LibGDXClipboardProvider) rather than by this module.
+ */
+public interface ClipboardProvider {
+    /**
+     * @return the current textual contents of the clipboard, or an empty string if there are none
+     * or the clipboard isn't available on this platform.
+     */
+    String getContents();
+
+    /**
+     * @param value the new textual contents of the clipboard.
+     */
+    void setContents(String value);
+}

nui-libgdx/src/main/java/org/terasology/nui/backends/libgdx/LibGDXClipboardProvider.java

@@ -0,0 +1,27 @@
+// Copyright 2020 The Terasology Foundation
+// SPDX-License-Identifier: Apache-2.0
+package org.terasology.nui.backends.libgdx;
+
+import com.badlogic.gdx.Gdx;
+import org.terasology.input.device.ClipboardProvider;
+
+/**
+ * Clipboard access via libGDX's own cross-platform {@link com.badlogic.gdx.utils.Clipboard}
+ * abstraction ({@code Gdx.app.getClipboard()}), which is backed by java.awt on desktop,
+ * android.content.ClipboardManager on Android, and the browser clipboard on GWT/HTML - unlike
+ * org.terasology.nui.util.AwtClipboardProvider (the default), this one actually works on every
+ * libGDX backend. Applications running NUI under libGDX should call
+ * {@code UIText.setClipboardProvider(new LibGDXClipboardProvider())} during startup.
+ */
+public class LibGDXClipboardProvider implements ClipboardProvider {
+    @Override
+    public String getContents() {
+        String contents = Gdx.app.getClipboard().getContents();
+        return contents != null ? contents : "";
+    }
+
+    @Override
+    public void setContents(String value) {
+        Gdx.app.getClipboard().setContents(value);
+    }
+}

nui/src/main/java/org/terasology/nui/util/AwtClipboardProvider.java

@@ -0,0 +1,46 @@
+// Copyright 2020 The Terasology Foundation
+// SPDX-License-Identifier: Apache-2.0
+package org.terasology.nui.util;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.terasology.input.device.ClipboardProvider;
+
+import java.awt.Toolkit;
+import java.awt.datatransfer.DataFlavor;
+import java.awt.datatransfer.StringSelection;
+import java.awt.datatransfer.Transferable;
+import java.awt.datatransfer.UnsupportedFlavorException;
+import java.io.IOException;
+
+/**
+ * The default {@link ClipboardProvider}: java.awt's system clipboard, available on desktop Java.
+ * java.awt genuinely doesn't exist on Android or GWT/HTML, so callers should catch {@link
+ * LinkageError} around use of this class rather than assume it always loads - see
+ * {@link org.terasology.nui.widgets.UIText#getClipboardContents()}. Platforms without java.awt
+ * should call {@link org.terasology.nui.widgets.UIText#setClipboardProvider} with a
+ * platform-appropriate implementation instead (e.g. nui-libgdx's LibGDXClipboardProvider).
+ */
+public class AwtClipboardProvider implements ClipboardProvider {
+    private static final Logger logger = LoggerFactory.getLogger(AwtClipboardProvider.class);
+
+    @Override
+    public String getContents() {
+        Transferable t = Toolkit.getDefaultToolkit().getSystemClipboard().getContents(null);
+
+        try {
+            if (t != null && t.isDataFlavorSupported(DataFlavor.stringFlavor)) {
+                return (String) t.getTransferData(DataFlavor.stringFlavor);
+            }
+        } catch (UnsupportedFlavorException | IOException e) {
+            logger.warn("Failed to get data from clipboard", e);
+        }
+
+        return "";
+    }
+
+    @Override
+    public void setContents(String value) {
+        Toolkit.getDefaultToolkit().getSystemClipboard().setContents(new StringSelection(value), null);
+    }
+}

nui/src/main/java/org/terasology/nui/widgets/UIText.java

@@ -24,6 +24,7 @@
 import org.terasology.input.Keyboard;
 import org.terasology.input.Keyboard.KeyId;
 import org.terasology.input.MouseInput;
+import org.terasology.input.device.ClipboardProvider;
 import org.terasology.input.device.KeyboardDevice;
 import org.terasology.nui.BaseInteractionListener;
 import org.terasology.nui.Canvas;
@@ -45,15 +46,10 @@
 import org.terasology.nui.events.NUIMouseDoubleClickEvent;
 import org.terasology.nui.events.NUIMouseDragEvent;
 import org.terasology.nui.events.NUIMouseReleaseEvent;
+import org.terasology.nui.util.AwtClipboardProvider;
 import org.terasology.nui.util.NUIMathUtil;
 import org.terasology.nui.util.RectUtility;
 
-import java.awt.Toolkit;
-import java.awt.datatransfer.DataFlavor;
-import java.awt.datatransfer.StringSelection;
-import java.awt.datatransfer.Transferable;
-import java.awt.datatransfer.UnsupportedFlavorException;
-import java.io.IOException;
 import java.util.Arrays;
 import java.util.List;
 
@@ -66,6 +62,21 @@ public class UIText extends WidgetWithOrder {
 
     private static final float BLINK_RATE = 0.25f;
 
+    /**
+     * The clipboard implementation used by every UIText instance. Defaults to java.awt's system
+     * clipboard, which doesn't exist on Android or GWT/HTML - platforms without it should call
+     * {@link #setClipboardProvider} with a platform-appropriate implementation (e.g. nui-libgdx's
+     * LibGDXClipboardProvider) during application startup.
+     */
+    private static ClipboardProvider clipboardProvider = new AwtClipboardProvider();
+
+    /**
+     * @param provider the clipboard implementation every UIText instance should use from now on.
+     */
+    public static void setClipboardProvider(ClipboardProvider provider) {
+        clipboardProvider = provider;
+    }
+
     /** Whether the content needs to be displayed on multiple lines. */
     @LayoutConfig
     protected boolean multiline;
@@ -600,61 +611,32 @@ protected void paste() {
     /**
      * Get the current clipboard contents.
      *
-     * @return The string currently in the clipboard, or an empty string if the system clipboard
-     * isn't available on this platform (e.g. Android, which has no java.awt).
+     * @return The string currently in the clipboard, or an empty string if the clipboard
+     * implementation in use (see {@link #setClipboardProvider}) fails to load on this platform.
      */
     protected String getClipboardContents() {
         try {
-            return AwtClipboard.getContents();
+            return clipboardProvider.getContents();
         } catch (LinkageError e) {
             logger.warn("System clipboard is not available on this platform", e);
             return "";
         }
     }
 
     /**
-     * Set the contents of the clipboard to a given value. Does nothing if the system clipboard
-     * isn't available on this platform (e.g. Android, which has no java.awt).
+     * Set the contents of the clipboard to a given value. Does nothing if the clipboard
+     * implementation in use (see {@link #setClipboardProvider}) fails to load on this platform.
      *
      * @param str The new value of the clipboard contents
      */
     protected void setClipboardContents(String str) {
         try {
-            AwtClipboard.setContents(str);
+            clipboardProvider.setContents(str);
         } catch (LinkageError e) {
             logger.warn("System clipboard is not available on this platform", e);
         }
     }
 
-    /**
-     * Isolates the java.awt.datatransfer clipboard access in its own class, rather than referencing
-     * it directly in getClipboardContents()/setClipboardContents(), so that loading UIText itself
-     * doesn't require java.awt to be resolvable - it genuinely doesn't exist on Android, unlike the
-     * other API-level gaps elsewhere in this codebase that have a same-behavior workaround.
-     * AwtClipboard is only classloaded the first time one of those two methods actually runs, and
-     * the LinkageError (a NoClassDefFoundError, on a platform without java.awt) is caught by the
-     * caller rather than here, since the failure happens on this class's own initialization.
-     */
-    private static final class AwtClipboard {
-        static String getContents() {
-            Transferable t = Toolkit.getDefaultToolkit().getSystemClipboard().getContents(null);
-
-            try {
-                if (t != null && t.isDataFlavorSupported(DataFlavor.stringFlavor)) {
-                    return (String) t.getTransferData(DataFlavor.stringFlavor);
-                }
-            } catch (UnsupportedFlavorException | IOException e) {
-                logger.warn("Failed to get data from clipboard", e);
-            }
-
-            return "";
-        }
-
-        static void setContents(String str) {
-            Toolkit.getDefaultToolkit().getSystemClipboard().setContents(new StringSelection(str), null);
-        }
-    }
-
     /**
      * Moves the cursor to a given position.
      *