Tk_GetSelection manual page - Tk Library Procedures

Tcl 8.7/Tk8.7a5 Documentation > Tk C API > GetSelect

Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl C API | Tk C API

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.

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 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 did not respond promptly). Tk_GetSelection normally returns TCL_OK; if an error occurs, it returns TCL_ERROR and leaves an error message in interpreter interp's 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 the interpreter result and return TCL_ERROR; this will abort the selection retrieval.

KEYWORDS