Skip to content

Selection

This capability documents one focused aspect of the widget interface (Tk/Tcl-style behavior + bootstack extensions).

Note: You typically won’t use bootstack.core.capabilities.selection directly. This page describes the behavior that widgets expose.

X selection helpers (selection).

Tk’s selection command provides access to the X selection mechanism (ICCCM), most commonly the PRIMARY selection, and also supports CLIPBOARD and other named selections.

Portability notes
  • On X11, PRIMARY is a system-wide selection shared across processes.
  • On Windows, PRIMARY is provided by Tk (not the OS) and is shared only within related interpreters, not across processes.
  • For clipboard-style usage, Tk also provides the clipboard_* methods, which are often a better cross-platform fit.
Intended usage

class Widget(SelectionMixin, ttk.Widget): ... class App(SelectionMixin, tkinter.Tk): ...

selection_clear 

selection_clear(**kw: Any) -> None

Clear a selection so that no window owns it.

This corresponds to selection clear and clears the specified selection on the target display (if it exists).

Parameters:

Name Type Description Default
**kw Any

Selection options forwarded to Tkinter. Common options include: - selection: The selection name (e.g. "PRIMARY", "CLIPBOARD"). Defaults to "PRIMARY". - displayof: A widget/window whose display should be targeted. Defaults to "." (the application’s main display).

 {}

selection_get 

selection_get(**kw: Any) -> str

Return the current contents of a selection.

This corresponds to selection get and retrieves a selection from the target display. The default selection is "PRIMARY" and the default type is "STRING".

Parameters:

Name Type Description Default
**kw Any

Selection options forwarded to Tkinter. Common options include: - selection: The selection name (e.g. "PRIMARY", "CLIPBOARD"). Defaults to "PRIMARY". - type: The desired “target” type for conversion (e.g. "STRING", "UTF8_STRING", "TARGETS", "FILE_NAME"). Defaults to "STRING". - displayof: A widget/window whose display should be targeted. Defaults to ".".

 {}

Returns:

Type Description
str

The selection contents as a string.
Notes
  • If the owner returns a non-string representation (e.g. ATOM or INTEGER), Tk converts it to a space-separated string representation.
  • Tk will not retrieve UTF-8 formatted data unless you request type="UTF8_STRING".

selection_handle 

selection_handle(command: str | None, **kw: Any) -> None

Register or remove a handler for selection retrieval requests.

This corresponds to selection handle. When this widget owns a selection, Tk will execute command when another client attempts to retrieve the selection in the requested type.

Parameters:

Name Type Description Default
command str | None

A Tcl command (string) to execute to supply selection data. If an empty string or None, removes any existing handler for the given selection/type combination.

 required
**kw Any

Handler options forwarded to Tkinter. Common options include: - selection: Selection name (defaults to "PRIMARY"). - type: Requested type (defaults to "STRING"). - format: Representation format used to transmit the selection (defaults to "STRING"). Usually only needed for compatibility with non-Tk requesters.

 {}
Notes
  • When handling type "STRING", Tk will also handle "UTF8_STRING" automatically.
  • The command is invoked with two additional arguments appended: offset and maxChars. The command should return up to maxChars characters starting at offset. Large selections are retrieved in multiple chunks.

selection_own 

selection_own(**kw: Any) -> str

Query the current selection owner within this application.

This corresponds to the query form of selection own, returning the pathname of the window in this application that owns the selection on the target display, or an empty string if none.

Parameters:

Name Type Description Default
**kw Any

Query options forwarded to Tkinter. Common options include: - selection: Selection name (defaults to "PRIMARY"). - displayof: A widget/window whose display should be targeted. Defaults to ".".

 {}

Returns:

Type Description
str

The pathname of the owner window in this application, or an empty
str

string if no window in this application owns the selection.

selection_own_set 

selection_own_set(
    owner: Any,
    command: Callable[[], Any] | None = None,
    *,
    selection: str = "PRIMARY",
) -> None

Make owner the selection owner (convenience helper).

Tk’s selection own setter form is easy to confuse with the query form. This helper makes the intent explicit while still using Tk’s semantics.

Parameters:

Name Type Description Default
owner Any

The widget/window that should own the selection.

 required
command Callable[[], Any] | None

Optional callback invoked when this widget loses ownership of the selection (i.e., another window claims it).

 None
selection str

The selection name to claim (defaults to "PRIMARY").

 'PRIMARY'