---
name: "Tk_GetSelection"
section: "3tk"
platform: "linux"
package: "tk8.6-doc"
version: "8.6.16-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Tk_GetSelection/3tk"
---

# Tk\_GetSelection(3tk)

retrieve the contents of a selection

```

```

## 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 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

format, get, selection retrieval