Tk_GetSelection(3tk)

______________________________________________________________________________

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 (deter-
                                              mines  display  from  which   to
                                              retrieve).

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

       Atom            target       (in)      Form in which to retrieve selec-
                                              tion.

       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 copies of the cor-
       responding  arguments to Tk_GetSelection.  Portion will be a pointer to
       a string containing part or all of the  selection.   For  large  selec-
       tions,  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 containing hexadecimal val-
       ues separated by white space.

       Tk_GetSelection  returns to its caller when the selection has been com-
       pletely retrieved and processed by proc, or  when  a  fatal  error  has
       occurred (e.g. the selection owner didn't respond promptly).  Tk_GetSe-
       lection 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

Tk                                    4.0                   Tk_GetSelection(3)