Tk_GetSelection(3Tk)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 (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
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
format, get, selection retrieval
Page 2
