org.rexxla.bsf.engines.rexx

## Class BsfSystemClipboard

- java.lang.Object
- - org.rexxla.bsf.engines.rexx.BsfSystemClipboard

-     public class BsfSystemClipboard
      extends java.lang.Object

  This class employs the java.awt.datatransfer.Clipboard class and allows for setting (and getting from) the system clipboard Java images (java.awt.Image) and strings.
  Since:
    2023-06-10
  Author:
    Rony G. Flatscher

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `version`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BsfSystemClipboard()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `clear()` Clears (empties) the system clipboard.
    `static java.awt.datatransfer.DataFlavor[]` | `getDataFlavors()` Returns an array of java.awt.datatransfer.DataFlavors (formats) currently available on the system clipboard.
    `static java.awt.Image` | `getImage()` Gets an image from the system clipboard and returns it.
    `static java.lang.String` | `getString()` Returns the string currently in the system clipboard.
    `static byte[]` | `getString(java.lang.String codepage)` Returns the string currently in the system clipboard as a byte array encoded according to the supplied codepage.
    `static boolean` | `isEmpty()` Tests whether the system clipboard is empty (if no data flavors are present).
    `static void` | `setImage(java.awt.Image img)` This copies the received image to the clipboard.
    `static java.awt.Image` | `setImageWithoutAlpha(java.awt.Image img)` This allows a java.awt.Image image to be copied as a JPG/JPEG (!) image to the system clipboard.
    `static void` | `setString(java.lang.String str)` Sets the supplied string to the system clipboard.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### version

          public static final java.lang.String version

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BsfSystemClipboard

          public BsfSystemClipboard()

  - ### Method Detail

    - #### isEmpty

          public static boolean isEmpty()

      Tests whether the system clipboard is empty (if no data flavors are present).
      Returns:
        true if empty, false else

    - #### getDataFlavors

          public static java.awt.datatransfer.DataFlavor[] getDataFlavors()

      Returns an array of java.awt.datatransfer.DataFlavors (formats) currently available on the system clipboard. If no data is availalbe the array will have a length of 0 and the method `static boolean isEmpty()` will return .true.
      Returns:
        an array of type java.awt.datatransfer.DataFlavor

    - #### clear

          public static void clear()

      Clears (empties) the system clipboard.

    - #### setImageWithoutAlpha

          public static java.awt.Image setImageWithoutAlpha(java.awt.Image img)

      This allows a java.awt.Image image to be copied as a JPG/JPEG (!) image to the system clipboard. The supplied image will therefore be transformed into a JPG/JPEG (with a white background).
      Parameters:
        `img` - the image to be copied (without alpha/translucency on white background) to the clipboard)
      Returns:
        image that was used to set the clipboard
      See Also:
        `public static void setImage(Image img)}`

    - #### setImage

          public static void setImage(java.awt.Image img)

      This copies the received image to the clipboard.
      Note 1: if the image has an alpha channel there will be a non catchable stack trace created by the default ImageIIO writer when creating a JPG/JPEG rendering. In order to intercept that stack trace, this method will temporarily reassign System.err to a PrintStream that is to receive that output in order to hide it.
      Note 2: even if the JPG/JPEG is not created usually a "BITMAP" and a "GDI metafile" get created in the Windows clipboard.
      Note 3: Use `static void setImageNoAlpha(Image img)` to make sure that the image does not have alpha (translucency) such that creating a JPG/JPEG is possible in any case.
      Parameters:
        `img` - the image to copy to the clipboard
      See Also:
        `public static void setImageWithoutAlpha(Image img)}`

    - #### getImage

          public static java.awt.Image getImage()

      Gets an image from the system clipboard and returns it.
      Returns:
        image from the system clipboard or null if no image available

    - #### setString

          public static void setString(java.lang.String str)

      Sets the supplied string to the system clipboard.

    - #### getString

          public static java.lang.String getString()

      Returns the string currently in the system clipboard.
      Returns:
        the string currently in the system clipboard, null if no string available

    - #### getString

          public static byte[] getString(java.lang.String codepage)

      Returns the string currently in the system clipboard as a byte array encoded according to the supplied codepage. *@param codepage the codepage to be used for creating the byte array, if null then defaults to "UTF-8"
      Returns:
        the string currently in the system clipboard, null if no string available