tk_getselection(3)
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 con
taining hexadecimal values separated 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