[go: up one dir, main page]

Skip to content

Switch

A simple switch widget which stores a boolean value.

  • Focusable
  • Container

Example

The example below shows switches in various states.

SwitchApp Example switches ▔▔▔▔▔▔▔▔ off:      ▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔ on:       ▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔ focused:  ▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔ custom:   ▁▁▁▁▁▁▁▁

from textual.app import App, ComposeResult
from textual.containers import Horizontal
from textual.widgets import Static, Switch


class SwitchApp(App):
    def compose(self) -> ComposeResult:
        yield Static("[b]Example switches\n", classes="label")
        yield Horizontal(
            Static("off:     ", classes="label"),
            Switch(animate=False),
            classes="container",
        )
        yield Horizontal(
            Static("on:      ", classes="label"),
            Switch(value=True),
            classes="container",
        )

        focused_switch = Switch()
        focused_switch.focus()
        yield Horizontal(
            Static("focused: ", classes="label"), focused_switch, classes="container"
        )

        yield Horizontal(
            Static("custom:  ", classes="label"),
            Switch(id="custom-design"),
            classes="container",
        )


app = SwitchApp(css_path="switch.tcss")
if __name__ == "__main__":
    app.run()
Screen {
    align: center middle;
}

.container {
    height: auto;
    width: auto;
}

Switch {
    height: auto;
    width: auto;
}

.label {
    height: 3;
    content-align: center middle;
    width: auto;
}

#custom-design {
    background: darkslategrey;
}

#custom-design > .switch--slider {
    color: dodgerblue;
    background: darkslateblue;
}

Reactive Attributes

Name Type Default Description
value bool False The value of the switch.

Messages

Bindings

The switch widget defines the following bindings:

Key(s) Description
enter,space Toggle the switch state.

Component Classes

The switch widget provides the following component classes:

Class Description
switch--slider Targets the slider of the switch.

Additional Notes

  • To remove the spacing around a Switch, set border: none; and padding: 0;.

Bases: Widget

A switch widget that represents a boolean value.

Can be toggled by clicking on it or through its bindings.

The switch widget also contains component classes that enable more customization.

Parameters:

Name Type Description Default

value

bool

The initial value of the switch.

False

animate

bool

True if the switch should animate when toggled.

True

name

str | None

The name of the switch.

None

id

str | None

The ID of the switch in the DOM.

None

classes

str | None

The CSS classes of the switch.

None

disabled

bool

Whether the switch is disabled or not.

False

tooltip

RenderableType | None

Optional tooltip.

None

BINDINGS class-attribute

BINDINGS = [
    Binding(
        "enter,space", "toggle_switch", "Toggle", show=False
    )
]
Key(s) Description
enter,space Toggle the switch state.

COMPONENT_CLASSES class-attribute

COMPONENT_CLASSES = {'switch--slider'}
Class Description
switch--slider Targets the slider of the switch.

value class-attribute instance-attribute

value = reactive(False, init=False)

The value of the switch; True for on and False for off.

Changed

Changed(switch, value)

Bases: Message

Posted when the status of the switch changes.

Can be handled using on_switch_changed in a subclass of Switch or in a parent widget in the DOM.

Attributes:

Name Type Description
value bool

The value that the switch was changed to.

switch Switch

The Switch widget that was changed.

control property

control

Alias for self.switch.

action_toggle_switch

action_toggle_switch()

Toggle the state of the switch.

toggle

toggle()

Toggle the switch value.

As a result of the value changing, a Switch.Changed message will be posted.

Returns:

Type Description
Self

The Switch instance.