Manpage of Clipboard::Clipboard

Clipboard::Clipboard

Section: User Contributed Perl Documentation (3)
Updated: 2004-12-02
Index Return to Main Contents

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>.

This document was created by man2html, using the manual pages.
Time: 21:21:44 GMT, May 16, 2005