diff --git a/docs/api/checkbox.md b/docs/api/checkbox.md new file mode 100644 index 000000000..6c9c434f2 --- /dev/null +++ b/docs/api/checkbox.md @@ -0,0 +1 @@ +::: textual.widgets.Checkbox diff --git a/docs/api/radiobutton.md b/docs/api/radiobutton.md new file mode 100644 index 000000000..f3270a474 --- /dev/null +++ b/docs/api/radiobutton.md @@ -0,0 +1 @@ +::: textual.widgets.RadioButton diff --git a/docs/api/radioset.md b/docs/api/radioset.md new file mode 100644 index 000000000..a661aadef --- /dev/null +++ b/docs/api/radioset.md @@ -0,0 +1 @@ +::: textual.widgets.RadioSet diff --git a/docs/api/toggle_button.md b/docs/api/toggle_button.md new file mode 100644 index 000000000..74a01db59 --- /dev/null +++ b/docs/api/toggle_button.md @@ -0,0 +1 @@ +::: textual.widgets._toggle_button.ToggleButton diff --git a/mkdocs-nav.yml b/mkdocs-nav.yml index db6880e93..6f0c39502 100644 --- a/mkdocs-nav.yml +++ b/mkdocs-nav.yml @@ -141,6 +141,7 @@ nav: - "api/app.md" - "api/binding.md" - "api/button.md" + - "api/checkbox.md" - "api/color.md" - "api/containers.md" - "api/coordinate.md" @@ -163,6 +164,8 @@ nav: - "api/pilot.md" - "api/placeholder.md" - "api/query.md" + - "api/radiobutton.md" + - "api/radioset.md" - "api/reactive.md" - "api/screen.md" - "api/scroll_view.md" @@ -170,6 +173,7 @@ nav: - "api/strip.md" - "api/switch.md" - "api/text_log.md" + - "api/toggle_button.md" - "api/timer.md" - "api/tree_node.md" - "api/tree.md" diff --git a/src/textual/widgets/_checkbox.py b/src/textual/widgets/_checkbox.py index 1cbc173f0..2f9b19a6a 100644 --- a/src/textual/widgets/_checkbox.py +++ b/src/textual/widgets/_checkbox.py @@ -7,7 +7,10 @@ class Checkbox(ToggleButton): """A check box widget that represents a boolean value.""" class Changed(ToggleButton.Changed): - """Posted when the value of the checkbox changes.""" + """Posted when the value of the checkbox changes. + + This message can be handled using an `on_checkbox_changed` method. + """ # https://github.com/Textualize/textual/issues/1814 namespace = "checkbox" diff --git a/src/textual/widgets/_radio_button.py b/src/textual/widgets/_radio_button.py index 00ba1a95a..3b6a4eaaa 100644 --- a/src/textual/widgets/_radio_button.py +++ b/src/textual/widgets/_radio_button.py @@ -6,14 +6,18 @@ from ._toggle_button import ToggleButton class RadioButton(ToggleButton): """A radio button widget that represents a boolean value. - TODO: Mention that this is best used in a RadioSet (yet to be added). + Note: + A `RadioButton` is best used within a [RadioSet][textual.widgets.RadioSet]. """ BUTTON_INNER = "⏺" """The character used to for the inside of the button.""" class Changed(ToggleButton.Changed): - """Posted when the value of the radio button changes.""" + """Posted when the value of the radio button changes. + + This message can be handled using an `on_radio_button_changed` method. + """ # https://github.com/Textualize/textual/issues/1814 namespace = "radio_button" diff --git a/src/textual/widgets/_toggle_button.py b/src/textual/widgets/_toggle_button.py index 2ac0bb8a0..bed47b340 100644 --- a/src/textual/widgets/_toggle_button.py +++ b/src/textual/widgets/_toggle_button.py @@ -19,7 +19,13 @@ from ._static import Static class ToggleButton(Static, can_focus=True): - """Base toggle button widget.""" + """Base toggle button widget. + + Warning: + `ToggleButton` should be considered to be an internal class; it + exists to serve as the common core of [Checkbox][textual.widgets.Checkbox] and + [RadioButton][textual.widgets.RadioButton]. + """ BINDINGS: ClassVar[list[BindingType]] = [ Binding("enter,space", "toggle", "Toggle", show=False), @@ -27,7 +33,7 @@ class ToggleButton(Static, can_focus=True): """ | Key(s) | Description | | :- | :- | - | enter,space | Toggle the value. | + | enter, space | Toggle the value. | """ COMPONENT_CLASSES: ClassVar[set[str]] = { @@ -197,11 +203,14 @@ class ToggleButton(Static, can_focus=True): self.value = not self.value def action_toggle(self) -> None: - """Toggle the value of the widget.""" + """Toggle the value of the widget when called as an action. + + This would normally be used for a keyboard binding. + """ self.toggle() def on_click(self) -> None: - """Toggle the value of the widget.""" + """Toggle the value of the widget when clicked with the mouse.""" self.toggle() class Changed(Message, bubble=True): @@ -221,6 +230,11 @@ class ToggleButton(Static, can_focus=True): """The value of the toggle button after the change.""" def watch_value(self) -> None: - """React to the value being changed.""" + """React to the value being changed. + + When triggered, the CSS class `-on` is applied to the widget if + `value` has become `True`, or it is removed if it has become + `False`. Subsequently a related `Changed` event will be posted. + """ self.set_class(self.value, "-on") self.post_message_no_wait(self.Changed(self, self.value))