Tk_GetSelection(3Tk)					  Tk_GetSelection(3Tk)

NAME    [Toc]    [Back]

     Tk_GetSelection - retrieve	the contents of	a selection

SYNOPSIS    [Toc]    [Back]

     #include <tk.h>

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

ARGUMENTS    [Toc]    [Back]

     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    [Toc]    [Back]

     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
     corresponding arguments to	Tk_GetSelection.  Portion will be a pointer to
     a string containing part or 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 containing hexadecimal values separated



									Page 1






Tk_GetSelection(3Tk)					  Tk_GetSelection(3Tk)



     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    [Toc]    [Back]

     format, get, selection retrieval


									PPPPaaaaggggeeee 2222