Clipboard(3) User Contributed Perl Documentation Clipboard(3)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>.
perl v5.14.2 2005-09-17 Clipboard(3)
