org.apache.poi.hpsf

## Class Thumbnail

- java.lang.Object
- - org.apache.poi.hpsf.Thumbnail

-     public final class Thumbnail
      extends java.lang.Object

  Class to manipulate data in the Clipboard Variant (`VT_CF`) format.

  See Also:
    `SummaryInformation.getThumbnail()`, Clipboard Operations

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CF_BITMAP` Clipboard Format - Bitmap
    `static int` | `CF_DIB` Clipboard Format - Device Independent Bitmap
    `static int` | `CF_ENHMETAFILE` Clipboard Format - Enhanced Windows metafile format
    `static int` | `CF_METAFILEPICT` Clipboard Format - Windows metafile format.
    `static int` | `CFTAG_FMTID` Clipboard Format Tag - Format ID
    `static int` | `CFTAG_MACINTOSH` Clipboard Format Tag - Macintosh clipboard format
    `static int` | `CFTAG_NODATA` Clipboard Format Tag - No Data
    `static int` | `CFTAG_WINDOWS` Clipboard Format Tag - Windows clipboard format
    `static int` | `OFFSET_CF` Offset in bytes where the Clipboard Format starts in the `byte[]` returned by `SummaryInformation.getThumbnail()`
    `static int` | `OFFSET_CFTAG` Offset in bytes where the Clipboard Format Tag starts in the `byte[]` returned by `SummaryInformation.getThumbnail()`
    `static int` | `OFFSET_WMFDATA` Offset in bytes where the Windows Metafile (WMF) image data starts in the `byte[]` returned by `SummaryInformation.getThumbnail()`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Thumbnail()` Default Constructor.
    `Thumbnail(byte[] thumbnailData)` Creates a `Thumbnail` instance and initializes with the specified image bytes.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `getClipboardFormat()` Returns an `int` representing the Clipboard Format
    `long` | `getClipboardFormatTag()` Returns an `int` representing the Clipboard Format Tag
    `byte[]` | `getThumbnail()` Returns the thumbnail as a `byte[]` in `VT_CF` format.
    `byte[]` | `getThumbnailAsWMF()` Returns the Thumbnail as a `byte[]` of WMF data if the Thumbnail's Clipboard Format Tag is `CFTAG_WINDOWS` and its Clipboard Format is `CF_METAFILEPICT`
    `void` | `setThumbnail(byte[] thumbnail)` Sets the Thumbnail's underlying `byte[]` in `VT_CF` format.

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

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

- - ### Field Detail

    - #### OFFSET_CFTAG

          public static final int OFFSET_CFTAG

      Offset in bytes where the Clipboard Format Tag starts in the `byte[]` returned by `SummaryInformation.getThumbnail()`

      See Also:
        Constant Field Values

    - #### OFFSET_CF

          public static final int OFFSET_CF

      Offset in bytes where the Clipboard Format starts in the `byte[]` returned by `SummaryInformation.getThumbnail()`

      This is only valid if the Clipboard Format Tag is `CFTAG_WINDOWS`

      See Also:
        Constant Field Values

    - #### OFFSET_WMFDATA

          public static final int OFFSET_WMFDATA

      Offset in bytes where the Windows Metafile (WMF) image data starts in the `byte[]` returned by `SummaryInformation.getThumbnail()`

      There is only WMF data at this point in the `byte[]` if the Clipboard Format Tag is `CFTAG_WINDOWS` and the Clipboard Format is `CF_METAFILEPICT`.

      Note: The `byte[]` that starts at `OFFSET_WMFDATA` and ends at `getThumbnail().length - 1` forms a complete WMF image. It can be saved to disk with a `.wmf` file type and read using a WMF-capable image viewer.

      See Also:
        Constant Field Values

    - #### CFTAG_WINDOWS

          public static final int CFTAG_WINDOWS

      Clipboard Format Tag - Windows clipboard format

      A `DWORD` indicating a built-in Windows clipboard format value

      See Also:
        Constant Field Values

    - #### CFTAG_MACINTOSH

          public static final int CFTAG_MACINTOSH

      Clipboard Format Tag - Macintosh clipboard format

      A `DWORD` indicating a Macintosh clipboard format value

      See Also:
        Constant Field Values

    - #### CFTAG_FMTID

          public static final int CFTAG_FMTID

      Clipboard Format Tag - Format ID

      A GUID containing a format identifier (FMTID). This is rarely used.

      See Also:
        Constant Field Values

    - #### CFTAG_NODATA

          public static final int CFTAG_NODATA

      Clipboard Format Tag - No Data

      A `DWORD` indicating No data. This is rarely used.

      See Also:
        Constant Field Values

    - #### CF_METAFILEPICT

          public static final int CF_METAFILEPICT

      Clipboard Format - Windows metafile format. This is the recommended way to store thumbnails in Property Streams.

      Note: This is not the same format used in regular WMF images. The clipboard version of this format has an extra clipboard-specific header.

      See Also:
        Constant Field Values

    - #### CF_DIB

          public static final int CF_DIB

      Clipboard Format - Device Independent Bitmap

      See Also:
        Constant Field Values

    - #### CF_ENHMETAFILE

          public static final int CF_ENHMETAFILE

      Clipboard Format - Enhanced Windows metafile format

      See Also:
        Constant Field Values

    - #### CF_BITMAP

          public static final int CF_BITMAP

      Clipboard Format - Bitmap

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Thumbnail

          public Thumbnail()

      Default Constructor. If you use it then one you'll have to add the thumbnail `byte[]` from `SummaryInformation.getThumbnail()` to do any useful manipulations, otherwise you'll get a `NullPointerException`.

    - #### Thumbnail

          public Thumbnail(byte[] thumbnailData)

      Creates a `Thumbnail` instance and initializes with the specified image bytes.

      Parameters:
        `thumbnailData` - The thumbnail data

  - ### Method Detail

    - #### getThumbnail

          public byte[] getThumbnail()

      Returns the thumbnail as a `byte[]` in `VT_CF` format.

      Returns:
        The thumbnail value
      See Also:
        `SummaryInformation.getThumbnail()`

    - #### setThumbnail

          public void setThumbnail(byte[] thumbnail)

      Sets the Thumbnail's underlying `byte[]` in `VT_CF` format.

      Parameters:
        `thumbnail` - The new thumbnail value
      See Also:
        `SummaryInformation.getThumbnail()`

    - #### getClipboardFormatTag

          public long getClipboardFormatTag()

      Returns an `int` representing the Clipboard Format Tag

      Possible return values are:

      - `CFTAG_WINDOWS`
      - `CFTAG_MACINTOSH`
      - `CFTAG_FMTID`
      - `CFTAG_NODATA`
      Returns:
        A flag indicating the Clipboard Format Tag

    - #### getClipboardFormat

          public long getClipboardFormat()
                                  throws HPSFException

      Returns an `int` representing the Clipboard Format

      Will throw an exception if the Thumbnail's Clipboard Format Tag is not `CFTAG_WINDOWS`.

      Possible return values are:

      - `CF_METAFILEPICT`
      - `CF_DIB`
      - `CF_ENHMETAFILE`
      - `CF_BITMAP`
      Returns:
        a flag indicating the Clipboard Format
      Throws:
        `HPSFException` - if the Thumbnail isn't CFTAG_WINDOWS

    - #### getThumbnailAsWMF

          public byte[] getThumbnailAsWMF()
                                   throws HPSFException

      Returns the Thumbnail as a `byte[]` of WMF data if the Thumbnail's Clipboard Format Tag is `CFTAG_WINDOWS` and its Clipboard Format is `CF_METAFILEPICT`

      This `byte[]` is in the traditional WMF file, not the clipboard-specific version with special headers.

      See http://www.wvware.com/caolan/ora-wmf.html for more information on the WMF image format.

      Returns:
        A WMF image of the Thumbnail
      Throws:
        `HPSFException` - if the Thumbnail isn't CFTAG_WINDOWS and CF_METAFILEPICT

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.