Add getContentsAsync methods to Clipboard

Obtaining data from the clipboard is fundamentally an asynchronous
operation, the event loop, at least at the OS level, needs to run
for the data to become available.

This PR proposes new API that provides asynchronous equivalents of
getContents methods called getContentsAsync that return
CompleteableFutures.

This new API will allow SWT API consumers to interact better with the
clipboard when the OS (window system) API is actually implemented in an
asynchronous manner.

GTK3 and cocoa provides API that spins the event loop as needed so
that a synchronous looking API can be provided to the user of the API.
For example, in SWT we use gtk_clipboard_wait_for_contents which
spins the loop in the GTK library itself
[here](https://gitlab.gnome.org/GNOME/gtk/-/blob/716458e86a222f43e64f7a4feda37749f3469ee4/gtk/gtkclipboard.c#L1436)

GTK4 does not provide such an API and leaves it to the user
of the API to spin the event loop.

Win32 is somewhat of a hybrid. The API appears synchronous, but SWT
needs to spin in a couple of places, such as
[getData](https://github.com/eclipse-platform/eclipse.platform.swt/blob/63e8925dc77db3b93ef521dc6cf2bd6ded7bab64/bundles/org.eclipse.swt/Eclipse%20SWT%20Drag%20and%20Drop/win32/org/eclipse/swt/dnd/Transfer.java#L46)

Part of #2598 and #2126

Author: jonahgraham

bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/Clipboard.java

@@ -13,6 +13,7 @@
  *******************************************************************************/
 package org.eclipse.swt.dnd;
 
+import java.util.concurrent.*;
 
 import org.eclipse.swt.*;
 import org.eclipse.swt.internal.cocoa.*;
@@ -199,6 +200,10 @@ public void dispose () {
  * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
  * determine the type of object returned.
  *
+ * <p>This method may iterate the event loop to be able to complete. Use
+ * {@link #getContentsAsync(Transfer)} to have control over when the event
+ * loop runs.</p>
+ *
  * <p>The following snippet shows text and RTF text being retrieved from the
  * clipboard:</p>
  *
@@ -225,6 +230,7 @@ public void dispose () {
  * </ul>
  *
  * @see Transfer
+ * @see #getContentsAsync(Transfer)
  */
 public Object getContents(Transfer transfer) {
 	return getContents(transfer, DND.CLIPBOARD);
@@ -235,6 +241,10 @@ public Object getContents(Transfer transfer) {
  * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
  * determine the type of object returned.
  *
+ * <p>This method may iterate the event loop to be able to complete. Use
+ * {@link #getContentsAsync(Transfer, int)} to have control over when the event
+ * loop runs.</p>
+ *
  * <p>The following snippet shows text and RTF text being retrieved from the
  * clipboard:</p>
  *
@@ -270,6 +280,7 @@ public Object getContents(Transfer transfer) {
  * @see Transfer
  * @see DND#CLIPBOARD
  * @see DND#SELECTION_CLIPBOARD
+ * @see #getContentsAsync(Transfer, int)
  *
  * @since 3.1
  */
@@ -308,6 +319,90 @@ public Object getContents(Transfer transfer, int clipboards) {
 	return null;
 }
 
+/**
+ * Retrieve the data of the specified type currently available on the system
+ * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
+ * determine the type of object returned.
+ *
+ * <p>This method is asynchronous and may require the SWT event loop to
+ * iterate before the future will complete.</p>
+ *
+ * <p>The following snippet shows text being retrieved from the clipboard:</p>
+ *
+ *    <pre><code>
+ *    Clipboard clipboard = new Clipboard(display);
+ *    TextTransfer textTransfer = TextTransfer.getInstance();
+ *    CompletableFuture&lt;Object&gt; future = clipboard.getContentsAsync(textTransfer);
+ *    future.thenAccept(textData -&gt; System.out.println("Text is "+textData));
+ *    clipboard.dispose();
+ *    </code></pre>
+ *
+ * @param transfer the transfer agent for the type of data being requested
+ * @return the future whose value will resolve to the data obtained from the
+ *     clipboard or will resolve to null if no data of this type is available
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if transfer is null</li>
+ * </ul>
+ *
+ * @see Transfer
+ * @since 3.132
+ */
+public CompletableFuture<Object> getContentsAsync(Transfer transfer) {
+	return getContentsAsync(transfer, DND.CLIPBOARD);
+}
+
+/**
+ * Retrieve the data of the specified type currently available on the specified
+ * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
+ * determine the type of object returned.
+ *
+ * <p>This method is asynchronous and may require the SWT event loop to
+ * iterate before the future will complete.</p>
+ *
+ * <p>The following snippet shows text being retrieved from the clipboard:</p>
+ *
+ *    <pre><code>
+ *    Clipboard clipboard = new Clipboard(display);
+ *    TextTransfer textTransfer = TextTransfer.getInstance();
+ *    CompletableFuture&lt;Object&gt; future = clipboard.getContentsAsync(textTransfer, DND.CLIPBOARD);
+ *    future.thenAccept(textData -&gt; System.out.println("Text is "+textData));
+ *    clipboard.dispose();
+ *    </code></pre>
+ *
+ * <p>The clipboards value is either one of the clipboard constants defined in
+ * class <code>DND</code>, or must be built by <em>bitwise OR</em>'ing together
+ * (that is, using the <code>int</code> "|" operator) two or more
+ * of those <code>DND</code> clipboard constants.</p>
+ *
+ * @param transfer the transfer agent for the type of data being requested
+ * @param clipboards on which to look for data
+ *
+ * @return the future whose value will resolve to the data obtained from the
+ *     clipboard or will resolve to null if no data of this type is available
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if transfer is null</li>
+ * </ul>
+ *
+ * @see Transfer
+ * @see DND#CLIPBOARD
+ * @see DND#SELECTION_CLIPBOARD
+ *
+ * @since 3.132
+ */
+public CompletableFuture<Object> getContentsAsync(Transfer transfer, int clipboards) {
+	return CompletableFuture.completedFuture(getContents(transfer, clipboards));
+}
+
 /**
  * Returns <code>true</code> if the clipboard has been disposed,
  * and <code>false</code> otherwise.

bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Clipboard.java

@@ -14,6 +14,8 @@
 package org.eclipse.swt.dnd;
 
 
+import java.util.concurrent.*;
+
 import org.eclipse.swt.*;
 import org.eclipse.swt.graphics.*;
 import org.eclipse.swt.internal.*;
@@ -215,6 +217,10 @@ public void dispose () {
  * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
  * determine the type of object returned.
  *
+ * <p>This method may iterate the event loop to be able to complete. Use
+ * {@link #getContentsAsync(Transfer)} to have control over when the event
+ * loop runs.</p>
+ *
  * <p>The following snippet shows text and RTF text being retrieved from the
  * clipboard:</p>
  *
@@ -241,6 +247,7 @@ public void dispose () {
  * </ul>
  *
  * @see Transfer
+ * @see #getContentsAsync(Transfer)
  */
 public Object getContents(Transfer transfer) {
 	return getContents(transfer, DND.CLIPBOARD);
@@ -251,6 +258,10 @@ public Object getContents(Transfer transfer) {
  * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
  * determine the type of object returned.
  *
+ * <p>This method may iterate the event loop to be able to complete. Use
+ * {@link #getContentsAsync(Transfer, int)} to have control over when the event
+ * loop runs.</p>
+ *
  * <p>The following snippet shows text and RTF text being retrieved from the
  * clipboard:</p>
  *
@@ -286,6 +297,7 @@ public Object getContents(Transfer transfer) {
  * @see Transfer
  * @see DND#CLIPBOARD
  * @see DND#SELECTION_CLIPBOARD
+ * @see #getContentsAsync(Transfer, int)
  *
  * @since 3.1
  */
@@ -326,6 +338,90 @@ public Object getContents(Transfer transfer, int clipboards) {
 	return result;
 }
 
+/**
+ * Retrieve the data of the specified type currently available on the system
+ * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
+ * determine the type of object returned.
+ *
+ * <p>This method is asynchronous and may require the SWT event loop to
+ * iterate before the future will complete.</p>
+ *
+ * <p>The following snippet shows text being retrieved from the clipboard:</p>
+ *
+ *    <pre><code>
+ *    Clipboard clipboard = new Clipboard(display);
+ *    TextTransfer textTransfer = TextTransfer.getInstance();
+ *    CompletableFuture&lt;Object&gt; future = clipboard.getContentsAsync(textTransfer);
+ *    future.thenAccept(textData -&gt; System.out.println("Text is "+textData));
+ *    clipboard.dispose();
+ *    </code></pre>
+ *
+ * @param transfer the transfer agent for the type of data being requested
+ * @return the future whose value will resolve to the data obtained from the
+ *     clipboard or will resolve to null if no data of this type is available
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if transfer is null</li>
+ * </ul>
+ *
+ * @see Transfer
+ * @since 3.132
+ */
+public CompletableFuture<Object> getContentsAsync(Transfer transfer) {
+	return getContentsAsync(transfer, DND.CLIPBOARD);
+}
+
+/**
+ * Retrieve the data of the specified type currently available on the specified
+ * clipboard.  Refer to the specific subclass of <code>Transfer</code> to
+ * determine the type of object returned.
+ *
+ * <p>This method is asynchronous and may require the SWT event loop to
+ * iterate before the future will complete.</p>
+ *
+ * <p>The following snippet shows text being retrieved from the clipboard:</p>
+ *
+ *    <pre><code>
+ *    Clipboard clipboard = new Clipboard(display);
+ *    TextTransfer textTransfer = TextTransfer.getInstance();
+ *    CompletableFuture&lt;Object&gt; future = clipboard.getContentsAsync(textTransfer, DND.CLIPBOARD);
+ *    future.thenAccept(textData -&gt; System.out.println("Text is "+textData));
+ *    clipboard.dispose();
+ *    </code></pre>
+ *
+ * <p>The clipboards value is either one of the clipboard constants defined in
+ * class <code>DND</code>, or must be built by <em>bitwise OR</em>'ing together
+ * (that is, using the <code>int</code> "|" operator) two or more
+ * of those <code>DND</code> clipboard constants.</p>
+ *
+ * @param transfer the transfer agent for the type of data being requested
+ * @param clipboards on which to look for data
+ *
+ * @return the future whose value will resolve to the data obtained from the
+ *     clipboard or will resolve to null if no data of this type is available
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if transfer is null</li>
+ * </ul>
+ *
+ * @see Transfer
+ * @see DND#CLIPBOARD
+ * @see DND#SELECTION_CLIPBOARD
+ *
+ * @since 3.132
+ */
+public CompletableFuture<Object> getContentsAsync(Transfer transfer, int clipboards) {
+	return CompletableFuture.completedFuture(getContents(transfer, clipboards));
+}
+
 private Object getContents_gtk4(Transfer transfer, int clipboards) {
 
 	long contents = GTK4.gdk_clipboard_get_content(Clipboard.GTKCLIPBOARD);