<HTML>
<HEAD>
<TITLE>Win32::Clipboard - Interaction with the Windows clipboard</TITLE>
<LINK REV="made" HREF="mailto:">
</HEAD>
<BODY>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
<LI><A HREF="#description">DESCRIPTION</A></LI>
<UL>
<LI><A HREF="#reference">REFERENCE</A></LI>
<LI><A HREF="#constants">CONSTANTS</A></LI>
</UL>
<LI><A HREF="#author">AUTHOR</A></LI>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="name">NAME</A></H1>
<P>Win32::Clipboard - Interaction with the Windows clipboard</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
use Win32::Clipboard;</PRE>
<PRE>
$CLIP = Win32::Clipboard();</PRE>
<PRE>
print "Clipboard contains: ", $CLIP->Get(), "\n";</PRE>
<PRE>
$CLIP->Set("some text to copy into the clipboard");</PRE>
<PRE>
$CLIP->Empty();</PRE>
<PRE>
$CLIP->WaitForChange();
print "Clipboard has changed!\n";</PRE>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>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:</P>
<UL>
<LI><STRONG><A NAME="item_text">text (<CODE>CF_TEXT</CODE>)</A></STRONG><BR>
The clipboard contains some text; this is the <STRONG>only</STRONG> format you can use to set
clipboard data; you get it as a single string.
<P>Example:</P>
<PRE>
$text = Win32::Clipboard::GetText();
print $text;</PRE>
<P></P>
<LI><STRONG><A NAME="item_bitmap">bitmap (<CODE>CF_DIB</CODE>)</A></STRONG><BR>
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.
<P>Example:</P>
<PRE>
$image = Win32::Clipboard::GetBitmap();
open BITMAP, ">some.bmp";
binmode BITMAP;
print BITMAP $image;
close BITMAP;</PRE>
<P></P>
<LI><STRONG><A NAME="item_files">list of files (<CODE>CF_HDROP</CODE>)</A></STRONG><BR>
The clipboard contains files copied or cutted from an Explorer-like
application; you get a list of filenames.
<P>Example:</P>
<PRE>
@files = Win32::Clipboard::GetFiles();
print join("\n", @files);</PRE>
<P></P></UL>
<P>
<H2><A NAME="reference">REFERENCE</A></H2>
<P>All the functions can be used either with their full name (eg. <STRONG>Win32::Clipboard::Get</STRONG>)
or as methods of a <CODE>Win32::Clipboard</CODE> object.
For the syntax, refer to <A HREF="#synopsis">SYNOPSIS</A> above. Note also that you can create a clipboard
object and set its content at the same time with:</P>
<PRE>
$CLIP = Win32::Clipboard("blah blah blah");</PRE>
<P>or with the more common form:</P>
<PRE>
$CLIP = new Win32::Clipboard("blah blah blah");</PRE>
<P>If you prefer, you can even tie the Clipboard to a variable like this:</P>
<PRE>
tie $CLIP, 'Win32::Clipboard';
</PRE>
<PRE>
print "Clipboard content: $CLIP\n";</PRE>
<PRE>
$CLIP = "some text to copy to the clipboard...";</PRE>
<P>In this case, you can still access other methods using the <CODE>tied()</CODE> function:</P>
<PRE>
tied($CLIP)->Empty;
print "got the picture" if tied($CLIP)->IsBitmap;</PRE>
<DL>
<DT><STRONG><A NAME="item_Empty"><CODE>Empty()</CODE></A></STRONG><BR>
<DD>
Empty the clipboard.
<P><P></P>
<DT><STRONG><A NAME="item_EnumFormats"><CODE>EnumFormats()</CODE></A></STRONG><BR>
<DD>
Returns an array of identifiers describing the format for the data currently in the
clipboard. Formats can be standard ones (described in the <A HREF="#constants">CONSTANTS</A> section) or
application-defined custom ones. See also IsFormatAvailable().
<P><P></P>
<DT><STRONG><A NAME="item_Get"><CODE>Get()</CODE></A></STRONG><BR>
<DD>
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(), <A HREF="#item_GetBitmap"><CODE>GetBitmap()</CODE></A> or <A HREF="#item_GetFiles"><CODE>GetFiles()</CODE></A> instead. <A HREF="#item_Get"><CODE>Get()</CODE></A> is in fact implemented as:
<PRE>
if( IsBitmap() ) { return GetBitmap(); }
elsif( IsFiles() ) { return GetFiles(); }
else { return GetText(); }</PRE>
<P>See also IsBitmap(), IsFiles(), IsText(), <A HREF="#item_EnumFormats"><CODE>EnumFormats()</CODE></A> and <A HREF="#item_IsFormatAvailable"><CODE>IsFormatAvailable()</CODE></A>
to check the clipboard format before getting data.</P>
<P><P></P>
<DT><STRONG><A NAME="item_GetAs"><CODE>GetAs(FORMAT)</CODE></A></STRONG><BR>
<DD>
Returns the clipboard content in the desired FORMAT (can be one of the constants
defined in the <A HREF="#constants">CONSTANTS</A> section or a custom format). Note that the only
meaningful identifiers are <CODE>CF_TEXT</CODE>, <CODE>CF_DIB</CODE> and <CODE>CF_HDROP</CODE>; any other
format is treated as a string.
<P><P></P>
<DT><STRONG><A NAME="item_GetBitmap"><CODE>GetBitmap()</CODE></A></STRONG><BR>
<DD>
Returns the clipboard content as an image, or <CODE>undef</CODE> on errors.
<P><P></P>
<DT><STRONG><A NAME="item_GetFiles"><CODE>GetFiles()</CODE></A></STRONG><BR>
<DD>
Returns the clipboard content as a list of filenames, or <CODE>undef</CODE> on errors.
<P><P></P>
<DT><STRONG><A NAME="item_GetFormatName"><CODE>GetFormatName(FORMAT)</CODE></A></STRONG><BR>
<DD>
Returns the name of the specified custom clipboard format, or <CODE>undef</CODE> on errors;
note that you cannot get the name of the standard formats (described in the
<A HREF="#constants">CONSTANTS</A> section).
<P><P></P>
<DT><STRONG><A NAME="item_GetText"><CODE>GetText()</CODE></A></STRONG><BR>
<DD>
Returns the clipboard content as a string, or <CODE>undef</CODE> on errors.
<P><P></P>
<DT><STRONG><A NAME="item_IsBitmap"><CODE>IsBitmap()</CODE></A></STRONG><BR>
<DD>
Returns a boolean value indicating if the clipboard contains an image.
See also GetBitmap().
<P><P></P>
<DT><STRONG><A NAME="item_IsFiles"><CODE>IsFiles()</CODE></A></STRONG><BR>
<DD>
Returns a boolean value indicating if the clipboard contains a list of
files. See also GetFiles().
<P><P></P>
<DT><STRONG><A NAME="item_IsFormatAvailable"><CODE>IsFormatAvailable(FORMAT)</CODE></A></STRONG><BR>
<DD>
Checks if the clipboard data matches the specified FORMAT (one of the constants
described in the <A HREF="#constants">CONSTANTS</A> section); returns zero if the data does not match,
a nonzero value if it matches.
<P><P></P>
<DT><STRONG><A NAME="item_IsText"><CODE>IsText()</CODE></A></STRONG><BR>
<DD>
Returns a boolean value indicating if the clipboard contains text.
See also GetText().
<P><P></P>
<DT><STRONG><A NAME="item_Set"><CODE>Set(VALUE)</CODE></A></STRONG><BR>
<DD>
Set the clipboard content to the specified string.
<P><P></P>
<DT><STRONG><A NAME="item_WaitForChange"><CODE>WaitForChange([TIMEOUT])</CODE></A></STRONG><BR>
<DD>
This function halts the script until the clipboard content changes. If you specify
a <CODE>TIMEOUT</CODE> 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, <CODE>undef</CODE> on errors.
<P></P></DL>
<P>
<H2><A NAME="constants">CONSTANTS</A></H2>
<P>These constants are the standard clipboard formats recognized by Win32::Clipboard:</P>
<PRE>
CF_TEXT 1
CF_DIB 8
CF_HDROP 15</PRE>
<P>The following formats are <STRONG>not recognized</STRONG> by Win32::Clipboard; they are,
however, exported constants and can eventually be used with the EnumFormats(),
<A HREF="#item_IsFormatAvailable"><CODE>IsFormatAvailable()</CODE></A> and <A HREF="#item_GetAs"><CODE>GetAs()</CODE></A> functions:</P>
<PRE>
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</PRE>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Aldo Calpini <<EM><A HREF="mailto:dada@perl.it">dada@perl.it</A></EM>></P>
<P>Original XS porting by Gurusamy Sarathy <<EM><A HREF="mailto:gsar@activestate.com">gsar@activestate.com</A></EM>>.</P>
</BODY>
</HTML>