summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Win32/Clipboard.pm
blob: ba4038a5ade72957fc6421de7fdba173e2168df2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
package Win32::Clipboard;
#######################################################################
#
# Win32::Clipboard - Interaction with the Windows clipboard
#
# Version: 0.52
# Author: Aldo Calpini <dada@perl.it>
#
# Modified by: Hideyo Imazu <himazu@gmail.com>
#
#######################################################################

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.5201";

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

This version was released by Hideyo Imazu <F<himazu@gmail.com>>.

Aldo Calpini <F<dada@perl.it>> was the former maintainer.

Original XS porting by Gurusamy Sarathy <F<gsar@activestate.com>>.

=cut