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