Win32::Clipboard - Interaction with the Windows clipboard

- NAME
- SYNOPSIS
- DESCRIPTION

- REFERENCE
- CONSTANTS

- AUTHOR

# NAME

Win32::Clipboard - Interaction with the Windows clipboard

# SYNOPSIS

        use Win32::Clipboard;

        $CLIP = Win32::Clipboard();

        print "Clipboard contains: ", $CLIP->Get(), "\n";

        $CLIP->Set("some text to copy into the clipboard");

        $CLIP->Empty();

        $CLIP->WaitForChange();
        print "Clipboard has changed!\n";

# DESCRIPTION

This module lets you interact with the Windows clipboard: you can get its content, set it, empty it, or let your script sleep until it changes. This version supports 3 formats for clipboard data:

- text (`CF_TEXT`)
  The clipboard contains some text; this is the only format you can use to set clipboard data; you get it as a single string.

  Example:

          $text = Win32::Clipboard::GetText();
          print $text;

- bitmap (`CF_DIB`)
  The clipboard contains an image, either a bitmap or a picture copied in the clipboard from a graphic application. The data you get is a binary buffer ready to be written to a bitmap (BMP format) file.

  Example:

          $image = Win32::Clipboard::GetBitmap();
          open    BITMAP, ">some.bmp";
          binmode BITMAP;
          print   BITMAP $image;
          close   BITMAP;

- list of files (`CF_HDROP`)
  The clipboard contains files copied or cutted from an Explorer-like application; you get a list of filenames.

  Example:

          @files = Win32::Clipboard::GetFiles();
          print join("\n", @files);

## REFERENCE

All the functions can be used either with their full name (eg. Win32::Clipboard::Get) or as methods of a `Win32::Clipboard` object. For the syntax, refer to SYNOPSIS above. Note also that you can create a clipboard object and set its content at the same time with:

        $CLIP = Win32::Clipboard("blah blah blah");

or with the more common form:

        $CLIP = new Win32::Clipboard("blah blah blah");

If you prefer, you can even tie the Clipboard to a variable like this:

            tie $CLIP, 'Win32::Clipboard';

            print "Clipboard content: $CLIP\n";

            $CLIP = "some text to copy to the clipboard...";

In this case, you can still access other methods using the `tied()` function:

            tied($CLIP)->Empty;
            print "got the picture" if tied($CLIP)->IsBitmap;

`Empty()`
  Empty the clipboard.

`EnumFormats()`
  Returns an array of identifiers describing the format for the data currently in the clipboard. Formats can be standard ones (described in the CONSTANTS section) or application-defined custom ones. See also IsFormatAvailable().

`Get()`
  Returns the clipboard content; note that the result depends on the nature of clipboard data; to ensure that you get only the desired format, you should use GetText(), `GetBitmap()` or `GetFiles()` instead. `Get()` is in fact implemented as:

              if(    IsBitmap() ) { return GetBitmap(); }
              elsif( IsFiles()  ) { return GetFiles();  }
              else                { return GetText();   }

  See also IsBitmap(), IsFiles(), IsText(), `EnumFormats()` and `IsFormatAvailable()` to check the clipboard format before getting data.

`GetAs(FORMAT)`
  Returns the clipboard content in the desired FORMAT (can be one of the constants defined in the CONSTANTS section or a custom format). Note that the only meaningful identifiers are `CF_TEXT`, `CF_DIB` and `CF_HDROP`; any other format is treated as a string.

`GetBitmap()`
  Returns the clipboard content as an image, or `undef` on errors.

`GetFiles()`
  Returns the clipboard content as a list of filenames, or `undef` on errors.

`GetFormatName(FORMAT)`
  Returns the name of the specified custom clipboard format, or `undef` on errors; note that you cannot get the name of the standard formats (described in the CONSTANTS section).

`GetText()`
  Returns the clipboard content as a string, or `undef` on errors.

`IsBitmap()`
  Returns a boolean value indicating if the clipboard contains an image. See also GetBitmap().

`IsFiles()`
  Returns a boolean value indicating if the clipboard contains a list of files. See also GetFiles().

`IsFormatAvailable(FORMAT)`
  Checks if the clipboard data matches the specified FORMAT (one of the constants described in the CONSTANTS section); returns zero if the data does not match, a nonzero value if it matches.

`IsText()`
  Returns a boolean value indicating if the clipboard contains text. See also GetText().

`Set(VALUE)`
  Set the clipboard content to the specified string.

`WaitForChange([TIMEOUT])`
  This function halts the script until the clipboard content changes. If you specify a `TIMEOUT` value (in milliseconds), the function will return when this timeout expires, even if the clipboard hasn't changed. If no value is given, it will wait indefinitely. Returns 1 if the clipboard has changed, `undef` on errors.

## CONSTANTS

These constants are the standard clipboard formats recognized by Win32::Clipboard:

            CF_TEXT             1
            CF_DIB              8
            CF_HDROP            15

The following formats are not recognized by Win32::Clipboard; they are, however, exported constants and can eventually be used with the EnumFormats(), `IsFormatAvailable()` and `GetAs()` functions:

            CF_BITMAP           2
            CF_METAFILEPICT     3
            CF_SYLK             4
            CF_DIF              5
            CF_TIFF             6
            CF_OEMTEXT          7
            CF_PALETTE          9
            CF_PENDATA          10
            CF_RIFF             11
            CF_WAVE             12
            CF_UNICODETEXT      13
            CF_ENHMETAFILE      14
            CF_LOCALE           16

# AUTHOR

Aldo Calpini <dada@perl.it>

Original XS porting by Gurusamy Sarathy <gsar@activestate.com>.