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

This version was released by Hideyo Imazu <himazu@gmail.com>.

Aldo Calpini <dada@perl.it> was the former maintainer.

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