NAME

       Tk_ClipboardClear,  Tk_ClipboardAppend  - Manage the clip­
       board


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  deter­
                                             mines   which   dis­
                                             play'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_Cre­
                                             ateSelHandler.

       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_Clipboard­
       Clear  once,  then  calling Tk_ClipboardAppend to add data
       for any number of targets.

       Tk_ClipboardClear claims the CLIPBOARD selection and frees
       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 clip­
       board.  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  clip­
       board  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_Clip­
       boardAppend calls (otherwise someone could retrieve a par­
       tially completed clipboard or claim  ownership  away  from
       this application).

       Tk_ClipboardClear  may  invoke  callbacks, including arbi­
       trary 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