clipboard(3Tk)

NAME
     Tk_ClipboardClear, Tk_ClipboardAppend - Manage the clipboard

SYNOPSIS
     #include <tk.h>

     int
     Tk_ClipboardClear(interp, tkwin)

     int
     Tk_ClipboardAppend(interp, tkwin, target, format, buffer)

ARGUMENTS
     Tcl_Interp          *interp (in)      Interpreter to use for reporting
                                           errors.

     Tk_Window           tkwin   (in)      Window that determines which
                                           display's clipboard to manipulate.

     Atom                target  (in)      Conversion type for this clipboard
                                           item;  has same meaning as target
                                           argument to Tk_CreateSelHandler.

     Atom                format  (in)      Representation to use when data is
                                           retrieved;  has same meaning as
                                           format argument to
                                           Tk_CreateSelHandler.

     char                *buffer (in)      Null terminated string containing
                                           the data to be appended to the
                                           clipboard.


DESCRIPTION
     These two procedures manage the clipboard for Tk.  The clipboard is
     typically managed by calling Tk_ClipboardClear once, then calling
     Tk_ClipboardAppend to add data for any number of targets.

     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 interp->result.  Tk_ClipboardClear must be called before
     a sequence of Tk_ClipboardAppend calls can be issued.

     Tk_ClipboardAppend appends a buffer of data to the clipboard.  The first
     buffer for a given target determines the format for that target.  Any
     successive appends for that target must have the same format or an error
     will be returned.  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 Tk_ClipboardClear has
     not been called or because ownership of the clipboard has changed since
     the last call to Tk_ClipboardClear, Tk_ClipboardAppend returns TCL_ERROR
     and leaves an error message in interp->result.

     In order to guarantee atomicity, no event handling should occur between
     Tk_ClipboardClear and the following Tk_ClipboardAppend calls (otherwise
     someone could retrieve a partially completed clipboard or claim ownership
     away from this application).

     Tk_ClipboardClear may invoke callbacks, including arbitrary Tcl scripts,
     as a result of losing the CLIPBOARD selection, so any calling function
     should take care to be reentrant at the point Tk_ClipboardClear is
     invoked.


KEYWORDS
     append, clipboard, clear, format, type