<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"../dtd/document-v11.dtd">
<!-- $Id$ -->

<document>
 <header>
  <title>HPSF THUMBNAIL HOW-TO</title>
  <authors>
   <person name="Drew Varner" email="Drew.Varner@-deleteThis-sc.edu" />
  </authors>
 </header>
 <body>
  <section><title>The VT_CF Format</title>

   <p>Thumbnail information is stored as a VT_CF, or Thumbnail Variant. The
    Thumbnail Variant is used to store various types of information in a
    clipboard. The VT_CF can store information in formats for the Macintosh or
    Windows clipboard.</p>

   <p>There are many types of data that can be copied to the clipboard, but the
    only types of information needed for thumbnail manipulation are the image
    formats.</p>

   <p>The <code>VT_CF</code> structure looks like this:</p>

   <table>
    <tr>
     <th>Element:</th>
     <td>Clipboard Size</td>
     <td>Clipboard Format Tag</td>
     <td>Clipboard Data</td>
    </tr>
    <tr>
     <th>Size:</th>
     <td>32 bit unsigned integer (DWord)</td>
     <td>32 bit signed integer (DWord)</td>
     <td>variable length (byte array)</td>
    </tr>
   </table>

   <p>The Clipboard Size refers to the size (in bytes) of Clipboard Data
    (variable size) plus the Clipboard Format (four bytes).</p>

   <p>Clipboard Format Tag has four possible values:</p>

   <table>
    <tr>
     <th>Value</th>
     <th>Identifier</th>
     <th>Description</th>
    </tr>
    <tr>
     <td><code>-1L</code></td>
     <td><code>CFTAG_WINDOWS</code></td>
     <td>a built-in Windows&copy; clipboard format value</td>
    </tr>
    <tr>
     <td><code>-2L</code></td>
     <td><code>CFTAG_MACINTOSH</code></td>
     <td>a Macintosh clipboard format value</td>
    </tr>
    <tr>
     <td><code>-3L</code></td>
     <td><code>CFTAG_FMTID</code></td>
     <td>a format identifier (FMTID) This is rarely used.</td>
    </tr>
    <tr>
     <td><code>0L</code></td>
     <td><code>CFTAG_NODATA</code></td>
     <td>No data This is rarely used.</td>
    </tr>
   </table>
  </section>



  <section><title>Windows Clipboard Data</title>

   <p>Windows clipboard data has four image formats for thumbnails:</p>

   <table>
    <tr>
     <th>Value</th>
     <th>Identifier</th>
     <th>Description</th>
    </tr>
    <tr>
     <td>3</td>
     <td><code>CF_METAFILEPICT</code></td>
     <td>Windows metafile format - recommended</td>
    </tr>
    <tr>
     <td>8</td>
     <td><code>CF_DIB</code></td>
     <td>Device Independent Bitmap</td>
    </tr>
    <tr>
     <td>14</td>
     <td><code>CF_ENHMETAFILE</code></td>
     <td>Enhanced Windows metafile format</td>
    </tr>
    <tr>
     <td>2</td>
     <td><code>CF_BITMAP</code></td>
     <td>Bitmap - Obsolete - Use <code>CF_DIB</code> instead</td>
    </tr>
   </table>
  </section>

  <section><title>Windows Metafile Format</title>

   <p>The most common format for thumbnails on the Windows platform is the
    Windows metafile format. The Clipboard places and extra header in front of
    a the standard Windows Metafile Format data.</p>

   <p>The Clipboard Data byte array looks like this when an image is stored in
    Windows' Clipboard WMF format.</p>

   <table>
    <tr>
     <th>Identifier</th>
     <td>CF_METAFILEPICT</td>
     <td>mm</td>
     <td>width</td>
     <td>height</td>
     <td>handle</td>
     <td>WMF data</td>
    </tr>
    <tr>
     <th>Size</th>
     <td>32 bit unsigned int</td>
     <td>16 bit unsigned(?) int</td>
     <td>16 bit unsigned(?) int</td>
     <td>16 bit unsigned(?) int</td>
     <td>16 bit unsigned(?) int</td>
     <td>byte array - variable length</td>
    </tr>
    <tr>
     <th>Description</th>
     <td>Clipboard WMF</td>
     <td>Mapping Mode</td>
     <td>Image Width</td>
     <td>Image Height</td>
     <td>handle to the WMF data array in memory, or 0</td>
     <td>standard WMF byte stream</td>
    </tr>
   </table>
  </section>


  <section><title>Device Independent Bitmap</title>
   <p><strong>FIXME:</strong> Describe the Device Independent Bitmap
    format!</p>
  </section>



  <section><title>Macintosh Clipboard Data</title>
   <p><strong>FIXME:</strong> Describe the Macintosh clipboard formats!</p>
  </section>

 </body>
</document>

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
