#  Copyright (c) 1990-1994 The Regents of the University of California.
#  Copyright (c) 1994-1996 Sun Microsystems, Inc.
#  See the file "license.terms" for information on usage and redistribution
#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#

=head1 NAME

Tk_GetSelection - retrieve the contents of a selection

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

int
B<Tk_GetSelection>(I<interp, tkwin, selection, target, proc, clientData>)

=head1 ARGUMENTS

=over 4

=item Tcl_Interp *interp (in)

Interpreter to use for reporting errors.

=item Tk_Window tkwin (in)

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

=item Atom selection (in)

The name of the selection to be retrieved.

=item Atom target (in)

Form in which to retrieve selection.

=item Tk_GetSelProc *proc (in)

Procedure to invoke to process pieces of the selection as they
are retrieved.

=item ClientData clientData (in)

Arbitrary one-word value to pass to I<proc>.

=back

=head1 DESCRIPTION

B<Tk_GetSelection> retrieves the selection specified by the atom
I<selection> in the format specified by I<target>.  The
selection may actually be retrieved in several pieces; as each piece
is retrieved, I<proc> is called to process the piece.  I<Proc>
should have arguments and result that match the type
B<Tk_GetSelProc>:

 typedef int Tk_GetSelProc(
 	ClientData clientData,
 	Tcl_Interp *interp,
 	char *portion);

The I<clientData> and I<interp> parameters to I<proc>
will be copies of the corresponding arguments to
B<Tk_GetSelection>.  I<Portion> will be a pointer to
a string containing part or all of the selection.  For large
selections, I<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 I<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 by white space.

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

=head1 KEYWORDS

format, get, selection retrieval
