NAME

       Tk_GetSelection - retrieve the contents of a selection


SYNOPSIS

       #include <tk.h>

       int
       Tk_GetSelection(interp, tkwin, selection, target, proc, clientData)


ARGUMENTS

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

       Tk_Window       tkwin        (in)      Window   on   whose
                                              behalf to  retrieve
                                              the       selection
                                              (determines display
                                              from    which    to
                                              retrieve).

       Atom            selection    (in)      The  name  of   the
                                              selection   to   be
                                              retrieved.

       Atom            target       (in)      Form  in  which  to
                                              retrieve selection.

       Tk_GetSelProc   *proc        (in)      Procedure to invoke
                                              to  process  pieces
                                              of the selection as
                                              they are retrieved.

       ClientData      clientData   (in)      Arbitrary  one-word
                                              value  to  pass  to
                                              proc.
_________________________________________________________________


DESCRIPTION

       Tk_GetSelection retrieves the selection specified  by  the
       atom  selection  in  the  format specified by target.  The
       selection may actually be retrieved in several pieces;  as
       each  piece  is  retrieved,  proc is called to process the
       piece.  Proc should have arguments and result  that  match
       the type Tk_GetSelProc:
              typedef int Tk_GetSelProc(
                ClientData clientData,
                Tcl_Interp *interp,
                char *portion);
       The  clientData  and  interp  parameters  to  proc will be
       all of the selection.  For large selections, proc will  be
       called  several  times  with  successive  portions  of the
       selection.  The X Inter-Client  Communication  Conventions
       Manual  allows a selection to be returned in formats other
       than strings, e.g. as an array of atoms or  integers.   If
       this happens, Tk converts the selection back into a string
       before calling proc.  If a selection  is  returned  as  an
       array  of atoms, Tk converts it to a string containing the
       atom names separated by white space.  For any other format
       besides  string,  Tk converts a selection to a string con­
       taining hexadecimal values separated by white space.

       Tk_GetSelection returns to its caller when  the  selection
       has  been  completely  retrieved and processed by proc, or
       when a fatal error has occurred (e.g. the selection  owner
       didn't   respond   promptly).    Tk_GetSelection  normally
       returns TCL_OK;  if an error occurs, it returns  TCL_ERROR
       and  leaves  an  error  message  in  interp->result.  Proc
       should also return either TCL_OK  or  TCL_ERROR.  If  proc
       encounters  an  error  in  dealing  with the selection, it
       should leave an error message in interp->result and return
       TCL_ERROR;  this will abort the selection retrieval.



KEYWORDS

       format, get, selection retrieval