util/src/TclTk/tk8.6.12/doc/Clipboard.3

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tk.h>\fR
  16 .sp
  17 int
  18 \fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR)
  19 .sp
  20 int
  21 \fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR)
  22 .SH ARGUMENTS
  23 .AS Tk_ClipboardClear tkwin
  24 .AP Tcl_Interp *interp in
  25 Interpreter to use for reporting errors.
  26 .AP Tk_Window tkwin in
  27 Window that determines which display's clipboard to manipulate.
  28 .AP Atom target in
  29 Conversion type for this clipboard item;  has same meaning as
  30 \fItarget\fR argument to \fBTk_CreateSelHandler\fR.
  31 .AP Atom format in
  32 Representation to use when data is retrieved;  has same meaning as
  33 \fIformat\fR argument to \fBTk_CreateSelHandler\fR.
  34 .AP "const char" *buffer in
  35 Null terminated string containing the data to be appended to the clipboard.
  36 .BE
  37 .SH DESCRIPTION
  38 .PP
  39 These two procedures manage the clipboard for Tk.
  40 The clipboard is typically managed by calling \fBTk_ClipboardClear\fR
  41 once, then calling \fBTk_ClipboardAppend\fR to add data for any
  42 number of targets.
  43 .PP
  44 \fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any
  45 data items previously stored on the clipboard in this application.
  46 It normally returns \fBTCL_OK\fR, but if an error occurs it returns
  47 \fBTCL_ERROR\fR and leaves an error message in interpreter
  48 \fIinterp\fR's result.
  49 \fBTk_ClipboardClear\fR must be called before a sequence of
  50 \fBTk_ClipboardAppend\fR calls can be issued.
  51 .PP
  52 \fBTk_ClipboardAppend\fR appends a buffer of data to the clipboard.
  53 The first buffer for a given \fItarget\fR determines the \fIformat\fR
  54 for that \fItarget\fR.
  55 Any successive appends for that \fItarget\fR must have
  56 the same format or an error will be returned.
  57 \fBTk_ClipboardAppend\fR returns \fBTCL_OK\fR if the buffer is
  58 successfully copied onto the clipboard.  If the clipboard is not
  59 currently owned by the application, either
  60 because \fBTk_ClipboardClear\fR has not been called or because
  61 ownership of the clipboard has changed since the last call to
  62 \fBTk_ClipboardClear\fR,
  63 \fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error
  64 message in the result of interpreter \fIinterp\fR.
  65 .PP
  66 In order to guarantee atomicity, no event handling should occur
  67 between \fBTk_ClipboardClear\fR and the following
  68 \fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve
  69 a partially completed clipboard or claim ownership away from
  70 this application).
  71 .PP
  72 \fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary
  73 Tcl scripts, as a result of losing the CLIPBOARD selection, so
  74 any calling function should take care to be re-entrant at the point
  75 \fBTk_ClipboardClear\fR is invoked.
  76 .SH KEYWORDS
  77 append, clipboard, clear, format, type