Tk_GetSelection - retrieve the contents of a selection
Tk_GetSelection(interp, tkwin, selection, target, proc, clientData)
- 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
- ClientData clientData (in)
- Arbitrary one-word value to pass to proc.
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:
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 by white space.
typedef int Tk_GetSelProc(
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 did not 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
format, get, selection retrieval