Bind

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.bind directly. This page describes the behavior that widgets expose.

Event binding and virtual event generation.

This mixin documents the Tkinter-style binding API (bind, unbind, bind_all, etc.) while reflecting bootstack v2’s enhanced event system.

Differences from stock Tkinter

Virtual events generated via event_generate("<<Name>>", data=...) may carry arbitrary Python objects as event payload.
Event handlers receive an event object with a consistent .data attribute:
- .data is the Python object you passed for virtual events.
- .data is None for non-virtual events.

Notes

Prefer bind over bind_all unless you truly need a global binding.
Return the string "break" from a handler to stop further processing.
Virtual event data is intended for application-local messaging.

bind

bind(
    sequence: Optional[str] = None,
    func: Optional[Callable[..., Any]] = None,
    add: Optional[Union[bool, str]] = None,
) -> Optional[str]

Bind an event sequence to a handler.

Parameters:

Name	Type	Description	Default
`sequence`	`Optional[str]`	Event pattern string (e.g. "", "", "<>"). If None, returns a string describing all bindings on this widget.	`None`
`func`	`Optional[Callable[..., Any]]`	Handler callable. The handler is called with a single argument: the event object. For bootstack enhanced events, `event.data` is always present (None for regular events, payload for virtual events).	`None`
`add`	`Optional[Union[bool, str]]`	If true/"+" then this binding is added in addition to existing bindings. If false/None then any existing binding for this sequence is replaced.	`None`

Returns:

Type	Description
`Optional[str]`	If `func` is provided, returns an internal Tk binding id that can be used
`Optional[str]`	with `unbind(sequence, funcid)`. If `func` is None, returns a Tcl binding
`Optional[str]`	script string (Tkinter behavior varies by version) or None.

Examples:

Bind a regular event:

widget.bind("<Button-1>", on_click)

Bind a virtual event that carries Python data:

widget.bind("<<Save>>", on_save)
widget.event_generate("<<Save>>", data={"path": "doc.txt"})

unbind

unbind(sequence: str, funcid: str | None = None) -> None

Remove a binding for an event sequence.

Parameters:

Name	Type	Description	Default
`sequence`	`str`	The event sequence that was previously bound.	required
`funcid`	`str \| None`	The binding id returned from `bind`. If omitted, removes all handlers for the given sequence on this widget.	`None`

bind_all

bind_all(
    sequence: Optional[str] = None,
    func: Optional[Callable[..., Any]] = None,
    add: Optional[Union[bool, str]] = None,
) -> Optional[str]

Bind an event sequence at the application level (all widgets).

Use sparingly. This affects every widget in the application.

Parameters:

Name	Type	Description	Default
`sequence`	`Optional[str]`	Event pattern string.	`None`
`func`	`Optional[Callable[..., Any]]`	Handler callable.	`None`
`add`	`Optional[Union[bool, str]]`	Whether to add alongside existing bindings.	`None`

Returns:

Type	Description
`Optional[str]`	A binding id when setting a binding, otherwise a binding script string
`Optional[str]`	(version-dependent) or None.

unbind_all

unbind_all(sequence: str) -> None

Remove an application-level binding for the given sequence.

Parameters:

Name	Type	Description	Default
`sequence`	`str`	The event sequence to unbind.	required

bind_class

bind_class(
    className: str,
    sequence: Optional[str] = None,
    func: Optional[Callable[..., Any]] = None,
    add: Optional[Union[bool, str]] = None,
) -> Optional[str]

Bind an event sequence to a Tk widget class.

This attaches a handler to all widgets of a given Tk class name (e.g. "TButton", "TEntry").

Parameters:

Name	Type	Description	Default
`className`	`str`	Tk class name.	required
`sequence`	`Optional[str]`	Event pattern string.	`None`
`func`	`Optional[Callable[..., Any]]`	Handler callable.	`None`
`add`	`Optional[Union[bool, str]]`	Whether to add alongside existing bindings.	`None`

Returns:

Type	Description
`Optional[str]`	A binding id when setting a binding, otherwise a binding script string
`Optional[str]`	(version-dependent) or None.

unbind_class

unbind_class(className: str, sequence: str) -> None

Remove a class-level binding.

Parameters:

Name	Type	Description	Default
`className`	`str`	Tk class name.	required
`sequence`	`str`	Event sequence to unbind for that class.	required

event_generate

event_generate(
    sequence: str, data: Any | None = None, **kw: Any
) -> None

Generate an event.

This can synthesize both physical events (like "") and virtual events (like "<>"). For virtual events, bootstack supports attaching a Python payload via the data parameter.

Parameters:

Name	Type	Description	Default
`sequence`	`str`	Event sequence to generate (commonly "<>" for virtual events).	required
`data`	`Any \| None`	Optional Python object payload for virtual events. When provided, handlers will receive an event object whose `.data` is this value. For non-virtual events, `data` is ignored and `.data` will be None.	`None`
`**kw`	`Any`	Additional Tk event fields (e.g. x=..., y=..., rootx=..., rooty=...).	`{}`