TkGetSelection(3) Tk Library Procedures TkGetSelection(3)

NAME
       TkGetSelection - retrieve the contents of a selection

SYNOPSIS
       ##iinncclluuddee <>

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

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

       TkWindow       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.

       TkGetSelProc   *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
       TTkkGGeettSSeelleeccttiioonn 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 TTkkGGeettSSeellPPrroocc:
              typedef int TkGetSelProc(
                ClientData clientData,
                TclInterp *interp,
                char *portion);
       The clientData and interp parameters to proc will be copies of the cor-
       responding  arguments to TTkkGGeettSSeelleeccttiioonn.  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.

       TTkkGGeettSSeelleeccttiioonn  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).  TTkkGGeettSSee-
       lleeccttiioonn normally returns  TCLOK;   if  an  error  occurs,  it  returns
       TCLERROR  and  leaves an error message in interp->result.  Proc should
       also return either TCLOK or TCLERROR. If proc encounters an error  in
       dealing  with  the  selection,  it  should  leave  an  error message in
       interp->result and return TCLERROR;  this  will  abort  the  selection
       retrieval.


KKEEYYWWOORRDDSS
       format, get, selection retrieval



Tk                                    4.0                   TkGetSelection(3)