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
|
# Copyright (c) 1994 The Regents of the University of California.
# Copyright (c) 1994-1996 Sun Microsystems, Inc.
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#
=head1 NAME
Tk_ClipboardClear, Tk_ClipboardAppend - Manage the clipboard
=for category C Programming
=head1 SYNOPSIS
B<#include E<lt>tk.hE<gt>>
int
B<Tk_ClipboardClear>(I<interp, tkwin>)
int
B<Tk_ClipboardAppend>(I<interp, tkwin, target, format, buffer>)
=head1 ARGUMENTS
=over 4
=item Tcl_Interp *interp (in)
Interpreter to use for reporting errors.
=item Tk_Window tkwin (in)
Window that determines which display's clipboard to manipulate.
=item Atom target (in)
Conversion type for this clipboard item; has same meaning as
I<target> argument to B<Tk_CreateSelHandler>.
=item Atom format (in)
Representation to use when data is retrieved; has same meaning as
I<format> argument to B<Tk_CreateSelHandler>.
=item char *buffer (in)
Null terminated string containing the data to be appended to the clipboard.
=back
=head1 DESCRIPTION
These two procedures manage the clipboard for Tk.
The clipboard is typically managed by calling B<Tk_ClipboardClear>
once, then calling B<Tk_ClipboardAppend> to add data for any
number of targets.
B<Tk_ClipboardClear> claims the CLIPBOARD selection and frees any
data items previously stored on the clipboard in this application.
It normally returns TCL_OK, but if an error occurs it returns
TCL_ERROR and leaves an error message in I<interp-E<gt>result>.
B<Tk_ClipboardClear> must be called before a sequence of
B<Tk_ClipboardAppend> calls can be issued.
B<Tk_ClipboardAppend> appends a buffer of data to the clipboard.
The first buffer for a given I<target> determines the I<format>
for that I<target>.
Any successive appends for that I<target> must have
the same format or an error will be returned.
B<Tk_ClipboardAppend> returns TCL_OK if the buffer is
successfully copied onto the clipboard. If the clipboard is not
currently owned by the application, either
because B<Tk_ClipboardClear> has not been called or because
ownership of the clipboard has changed since the last call to
B<Tk_ClipboardClear>,
B<Tk_ClipboardAppend> returns TCL_ERROR and leaves an error message in
I<interp-E<gt>result>.
In order to guarantee atomicity, no event handling should occur
between B<Tk_ClipboardClear> and the following
B<Tk_ClipboardAppend> calls (otherwise someone could retrieve
a partially completed clipboard or claim ownership away from
this application).
B<Tk_ClipboardClear> may invoke callbacks, including arbitrary
Callbacks, as a result of losing the CLIPBOARD selection, so
any calling function should take care to be reentrant at the point
B<Tk_ClipboardClear> is invoked.
=head1 KEYWORDS
append, clipboard, clear, format, type
|
