TkClipboardClear(3) Tk Library Procedures TkClipboardClear(3)

NAME
       TkClipboardClear, TkClipboardAppend - Manage the clipboard

SYNOPSIS
       ##iinncclluuddee <>

       int
       TTkkCClliippbbooaarrddCClleeaarr(interp, tkwin)

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

AARRGGUUMMEENNTTSS
       TclInterp          *interp (in)      Interpreter  to use for reporting
                                             errors.

       TkWindow           tkwin   (in)      Window that determines which dis-
                                             play's clipboard to manipulate.

       Atom                target  (in)      Conversion  type  for  this clip-
                                             board item;  has same meaning  as
                                             target  argument to TTkkCCrreeaatteeSSeell-
                                             HHaannddlleerr.

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

       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  TTkkCClliippbbooaarrddCClleeaarr  once,  then  calling
       TTkkCClliippbbooaarrddAAppppeenndd to add data for any number of targets.

       TTkkCClliippbbooaarrddCClleeaarr  claims  the  CLIPBOARD  selection and frees any data
       items previously stored on the clipboard in this application.  It  nor-
       mally  returns  TCLOK, but if an error occurs it returns TCLERROR and
       leaves an error message in interp->result.  TTkkCClliippbbooaarrddCClleeaarr  must  be
       called before a sequence of TTkkCClliippbbooaarrddAAppppeenndd calls can be issued.

       TTkkCClliippbbooaarrddAAppppeenndd  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.   TTkkCClliippbbooaarrddAAppppeenndd  returns  TCLOK  if  the
       buffer  is successfully copied onto the clipboard.  If the clipboard is
       not currently owned by the application,  either  because  TTkkCClliippbbooaarrdd-
       CClleeaarr  has  not  been  called or because ownership of the clipboard has
       changed since the last call  to  TTkkCClliippbbooaarrddCClleeaarr,  TTkkCClliippbbooaarrddAAppppeenndd
       returns TCLERROR and leaves an error message in interp->result.

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

       TTkkCClliippbbooaarrddCClleeaarr  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  TTkkCClliippbbooaarrdd-
       CClleeaarr is invoked.


KKEEYYWWOORRDDSS
       append, clipboard, clear, format, type



Tk                                    4.0                 TkClipboardClear(3)