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