Win32::Clipboard - Interaction with the Windows clipboard
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";
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:
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;
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;
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);
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 the clipboard.
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().
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.
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.
Returns the clipboard content as an image, or undef
on errors.
Returns the clipboard content as a list of filenames, or undef
on errors.
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).
Returns the clipboard content as a string, or undef
on errors.
Returns a boolean value indicating if the clipboard contains an image. See
also GetBitmap().
Returns a boolean value indicating if the clipboard contains a list of
files. See also GetFiles().
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.
Returns a boolean value indicating if the clipboard contains text. See also
GetText().
Set the clipboard content to the specified string.
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.
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
Aldo Calpini <dada@perl.it>
Original XS porting by Gurusamy Sarathy <gsar@engin.umich.edu>.