Import Tk 8.5.15 (as of svn r89086)

doc/GetSelect.3

@@ -0,0 +1,77 @@
+'\"
+'\" 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.
+'\" 
+.so man.macros
+.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures"
+.BS
+.SH NAME
+Tk_GetSelection \- retrieve the contents of a selection
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR)
+.SH ARGUMENTS
+.AS Tk_GetSelProc clientData
+.AP Tcl_Interp *interp in
+Interpreter to use for reporting errors.
+.AP Tk_Window tkwin in
+Window on whose behalf to retrieve the selection (determines
+display from which to retrieve).
+.AP Atom selection in
+The name of the selection to be retrieved.
+.AP Atom target in
+Form in which to retrieve selection.
+.AP Tk_GetSelProc *proc in
+Procedure to invoke to process pieces of the selection as they
+are retrieved.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTk_GetSelection\fR retrieves the selection specified by the atom
+\fIselection\fR in the format specified by \fItarget\fR.  The
+selection may actually be retrieved in several pieces; as each piece
+is retrieved, \fIproc\fR is called to process the piece.  \fIProc\fR
+should have arguments and result that match the type
+\fBTk_GetSelProc\fR:
+.CS
+typedef int Tk_GetSelProc(
+    ClientData \fIclientData\fR,
+    Tcl_Interp *\fIinterp\fR,
+    char *\fIportion\fR);
+.CE
+The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR 
+will be copies of the corresponding arguments to
+\fBTk_GetSelection\fR.  \fIPortion\fR will be a pointer to
+a string containing part or all of the selection.  For large
+selections, \fIproc\fR 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 \fIproc\fR.  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.
+.PP
+\fBTk_GetSelection\fR returns to its caller when the selection has
+been completely retrieved and processed by \fIproc\fR, or when a
+fatal error has occurred (e.g. the selection owner did not respond
+promptly).  \fBTk_GetSelection\fR normally returns \fBTCL_OK\fR;  if
+an error occurs, it returns \fBTCL_ERROR\fR and leaves an error message
+in \fIinterp->result\fR.  \fIProc\fR should also return either
+\fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fIproc\fR encounters an error in dealing with the
+selection, it should leave an error message in \fIinterp->result\fR
+and return \fBTCL_ERROR\fR;  this will abort the selection retrieval.
+
+.SH KEYWORDS
+format, get, selection retrieval