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_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
       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_ClipboardAppend calls (otherwise someone could retrieve
       a  partially  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