PC World 2005 June/PCWorld_2005-06_cd.bin/software/vyzkuste/firewally/firewally.exe/framework-2.3.exe/Clipboard.pm

Text File | 2002-07-08 | 9KB | 364 lines

package Win32::Clipboard;
#######################################################################
#
# Win32::Clipboard - Interaction with the Windows clipboard
#
# Version: 0.51
# Author: Aldo Calpini <[e-mail]>
#
#######################################################################

require Exporter;       # to export the constants to the main:: space
require DynaLoader;     # to dynuhlode the module.

@ISA = qw( Exporter DynaLoader );
@EXPORT = qw(
    CF_TEXT
    CF_BITMAP
    CF_METAFILEPICT
    CF_SYLK
    CF_DIF
    CF_TIFF
    CF_OEMTEXT
    CF_DIB
    CF_PALETTE
    CF_PENDATA
    CF_RIFF
    CF_WAVE
    CF_UNICODETEXT
    CF_ENHMETAFILE
    CF_HDROP
    CF_LOCALE
);

#######################################################################
# This AUTOLOAD is used to 'autoload' constants from the constant()
# XS function.  If a constant is not found then control is passed
# to the AUTOLOAD in AutoLoader.
#

sub AUTOLOAD {
    my($constname);
    ($constname = $AUTOLOAD) =~ s/.*:://;
    #reset $! to zero to reset any current errors.
    local $! = 0;
    my $val = constant($constname, @_ ? $_[0] : 0);
    if ($! != 0) {
        if ($! =~ /Invalid/) {
            $AutoLoader::AUTOLOAD = $AUTOLOAD;
            goto &AutoLoader::AUTOLOAD;
        } else {
            my ($pack, $file, $line) = caller;
            die "Win32::Clipboard::$constname is not defined, used at $file line $line.";
        }
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}


#######################################################################
# STATIC OBJECT PROPERTIES
#
$VERSION = "0.51";

#######################################################################
# FUNCTIONS
#

sub new {
    my($class, $value) = @_;
    my $self = "I'm the Clipboard!";
    Set($value) if defined($value);
    return bless(\$self);
}

sub Version {
    return $VERSION;
}

sub Get {
    if(    IsBitmap() ) { return GetBitmap(); }
    elsif( IsFiles()  ) { return GetFiles();  }
    else                { return GetText();   }
}

sub TIESCALAR {
    my $class = shift;
    my $value = shift;
    Set($value) if defined $value;
    my $self = "I'm the Clipboard!";
    return bless \$self, $class;
}

sub FETCH { Get() }
sub STORE { shift; Set(@_) }

sub DESTROY {
    my($self) = @_;
    undef $self;
    StopClipboardViewer();
}

END {
    StopClipboardViewer();
}

#######################################################################
# dynamically load in the Clipboard.pll module.
#

bootstrap Win32::Clipboard;

#######################################################################
# a little hack to use the module itself as a class.
#

sub main::Win32::Clipboard {
    my($value) = @_;
    my $self={};
    my $result = Win32::Clipboard::Set($value) if defined($value);
    return bless($self, "Win32::Clipboard");
}

1;

__END__

=head1 NAME

Win32::Clipboard - Interaction with the Windows clipboard

=head1 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";


=head1 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:

=over 4

=item *
text (C<CF_TEXT>)

The clipboard contains some text; this is the B<only> format you can use to set
clipboard data; you get it as a single string.

Example:

    $text = Win32::Clipboard::GetText();
    print $text;

=item *
bitmap (C<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;

=item *
list of files (C<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);

=back

=head2 REFERENCE

All the functions can be used either with their full name (eg. B<Win32::Clipboard::Get>)
or as methods of a C<Win32::Clipboard> object.
For the syntax, refer to L</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;

=over 4

=item Empty()

Empty the clipboard.

=for html <P>

=item EnumFormats()

Returns an array of identifiers describing the format for the data currently in the
clipboard. Formats can be standard ones (described in the L</CONSTANTS> section) or
application-defined custom ones. See also IsFormatAvailable().

=for html <P>

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

=for html <P>

=item GetAs(FORMAT)

Returns the clipboard content in the desired FORMAT (can be one of the constants
defined in the L</CONSTANTS> section or a custom format). Note that the only
meaningful identifiers are C<CF_TEXT>, C<CF_DIB> and C<CF_HDROP>; any other
format is treated as a string.

=for html <P>

=item GetBitmap()

Returns the clipboard content as an image, or C<undef> on errors.

=for html <P>

=item GetFiles()

Returns the clipboard content as a list of filenames, or C<undef> on errors.

=for html <P>

=item GetFormatName(FORMAT)

Returns the name of the specified custom clipboard format, or C<undef> on errors;
note that you cannot get the name of the standard formats (described in the
L</CONSTANTS> section).

=for html <P>

=item GetText()

Returns the clipboard content as a string, or C<undef> on errors.

=for html <P>

=item IsBitmap()

Returns a boolean value indicating if the clipboard contains an image.
See also GetBitmap().

=for html <P>

=item IsFiles()

Returns a boolean value indicating if the clipboard contains a list of
files. See also GetFiles().

=for html <P>

=item IsFormatAvailable(FORMAT)

Checks if the clipboard data matches the specified FORMAT (one of the constants
described in the L</CONSTANTS> section); returns zero if the data does not match,
a nonzero value if it matches.

=for html <P>

=item IsText()

Returns a boolean value indicating if the clipboard contains text.
See also GetText().

=for html <P>

=item Set(VALUE)

Set the clipboard content to the specified string.

=for html <P>

=item WaitForChange([TIMEOUT])

This function halts the script until the clipboard content changes. If you specify
a C<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, C<undef> on errors.

=back

=head2 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 B<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

=head1 AUTHOR

Aldo Calpini <F<[e-mail]>>

Original XS porting by Gurusamy Sarathy <F<[e-mail]>>.

=cut