Tabs¶
Added in version 0.15.0
Displays a number of tab headers which may be activated with a click or navigated with cursor keys.
- Focusable
- Container
Construct a Tabs
widget with strings or Text objects as positional arguments, which will set the labels in the tabs. Here's an example with three tabs:
def compose(self) -> ComposeResult:
yield Tabs("First tab", "Second tab", Text.from_markup("[u]Third[/u] tab"))
This will create Tab widgets internally, with auto-incrementing id
attributes ("tab-1"
, "tab-2"
etc).
You can also supply Tab
objects directly in the constructor, which will allow you to explicitly set an id
. Here's an example:
def compose(self) -> ComposeResult:
yield Tabs(
Tab("First tab", id="one"),
Tab("Second tab", id="two"),
)
When the user switches to a tab by clicking or pressing keys, then Tabs
will send a Tabs.TabActivated message which contains the tab
that was activated.
You can then use event.tab.id
attribute to perform any related actions.
Clearing tabs¶
Clear tabs by calling the clear method. Clearing the tabs will send a Tabs.TabActivated message with the tab
attribute set to None
.
Adding tabs¶
Tabs may be added dynamically with the add_tab method, which accepts strings, Text, or Tab objects.
Example¶
The following example adds a Tabs
widget above a text label. Press A to add a tab, C to clear the tabs.
from textual.app import App, ComposeResult
from textual.widgets import Footer, Label, Tabs
NAMES = [
"Paul Atreidies",
"Duke Leto Atreides",
"Lady Jessica",
"Gurney Halleck",
"Baron Vladimir Harkonnen",
"Glossu Rabban",
"Chani",
"Silgar",
]
class TabsApp(App):
"""Demonstrates the Tabs widget."""
CSS = """
Tabs {
dock: top;
}
Screen {
align: center middle;
}
Label {
margin:1 1;
width: 100%;
height: 100%;
background: $panel;
border: tall $primary;
content-align: center middle;
}
"""
BINDINGS = [
("a", "add", "Add tab"),
("r", "remove", "Remove active tab"),
("c", "clear", "Clear tabs"),
]
def compose(self) -> ComposeResult:
yield Tabs(NAMES[0])
yield Label()
yield Footer()
def on_mount(self) -> None:
"""Focus the tabs when the app starts."""
self.query_one(Tabs).focus()
def on_tabs_tab_activated(self, event: Tabs.TabActivated) -> None:
"""Handle TabActivated message sent by Tabs."""
label = self.query_one(Label)
if event.tab is None:
# When the tabs are cleared, event.tab will be None
label.visible = False
else:
label.visible = True
label.update(event.tab.label)
def action_add(self) -> None:
"""Add a new tab."""
tabs = self.query_one(Tabs)
# Cycle the names
NAMES[:] = [*NAMES[1:], NAMES[0]]
tabs.add_tab(NAMES[0])
def action_remove(self) -> None:
"""Remove active tab."""
tabs = self.query_one(Tabs)
active_tab = tabs.active_tab
if active_tab is not None:
tabs.remove_tab(active_tab.id)
def action_clear(self) -> None:
"""Clear the tabs."""
self.query_one(Tabs).clear()
if __name__ == "__main__":
app = TabsApp()
app.run()
Reactive Attributes¶
Name | Type | Default | Description |
---|---|---|---|
active |
str |
"" |
The ID of the active tab. Set this attribute to a tab ID to change the active tab. |
Messages¶
Bindings¶
The Tabs widget defines the following bindings:
Key(s) | Description |
---|---|
left | Move to the previous tab. |
right | Move to the next tab. |
Component Classes¶
This widget has no component classes.
textual.widgets.Tabs
class
¶
Bases: Widget
A row of tabs.
Parameters
Parameter | Default | Description |
---|---|---|
*tabs
Tab | TextType
|
()
|
Positional argument should be explicit Tab objects, or a str or Text. |
active
str | None
|
None
|
ID of the tab which should be active on start. |
name
str | None
|
None
|
Optional name for the input widget. |
id
str | None
|
None
|
Optional ID for the widget. |
classes
str | None
|
None
|
Optional initial classes for the widget. |
disabled
bool
|
False
|
Whether the input is disabled or not. |
BINDINGS
class-attribute
¶
BINDINGS: list[BindingType] = [
Binding(
"left", "previous_tab", "Previous tab", show=False
),
Binding("right", "next_tab", "Next tab", show=False),
]
Key(s) | Description |
---|---|
left | Move to the previous tab. |
right | Move to the next tab. |
active
instance-attribute
class-attribute
¶
The ID of the active tab, or empty string if none are active.
active_tab
property
¶
The currently active tab, or None if there are no active tabs.
Cleared
class
¶
Bases: Message
Sent when there are no active tabs.
This can occur when Tabs are cleared, or if all tabs are hidden.
Parameters
Parameter | Default | Description |
---|---|---|
tabs
Tabs
|
required | The tabs widget. |
control
property
¶
The tabs widget which was cleared.
This is an alias for Cleared.tabs
which
is used by the on
decorator.
TabActivated
class
¶
Bases: TabMessage
Sent when a new tab is activated.
TabDisabled
class
¶
Bases: TabMessage
Sent when a tab is disabled.
TabEnabled
class
¶
Bases: TabMessage
Sent when a tab is enabled.
TabHidden
class
¶
Bases: TabMessage
Sent when a tab is hidden.
TabMessage
class
¶
Bases: Message
Parent class for all messages that have to do with a specific tab.
Parameters
Parameter | Default | Description |
---|---|---|
tabs
Tabs
|
required | The Tabs widget. |
tab
Tab
|
required | The tab that is the object of this message. |
ALLOW_SELECTOR_MATCH
instance-attribute
class-attribute
¶
Additional message attributes that can be used with the on
decorator.
TabShown
class
¶
Bases: TabMessage
Sent when a tab is shown.
add_tab
method
¶
Add a new tab to the end of the tab list.
Parameters
Parameter | Default | Description |
---|---|---|
tab
Tab | str | Text
|
required | A new tab object, or a label (str or Text). |
before
Tab | str | None
|
None
|
Optional tab or tab ID to add the tab before. |
after
Tab | str | None
|
None
|
Optional tab or tab ID to add the tab after. |
Returns
Type | Description |
---|---|
AwaitComplete
|
An optionally awaitable object that waits for the tab to be mounted and internal state to be fully updated to reflect the new tab. |
Raises
Type | Description |
---|---|
Tabs.TabError
|
If there is a problem with the addition request. |
Note
Only one of before
or after
can be provided. If both are
provided a Tabs.TabError
will be raised.
clear
method
¶
Clear all the tabs.
Returns
Type | Description |
---|---|
AwaitComplete
|
An awaitable object that waits for the tabs to be removed. |
disable
method
¶
enable
method
¶
hide
method
¶
remove_tab
method
¶
Remove a tab.
Parameters
Parameter | Default | Description |
---|---|---|
tab_or_id
Tab | str | None
|
required | The Tab to remove or its id. |
Returns
Type | Description |
---|---|
AwaitComplete
|
An optionally awaitable object that waits for the tab to be removed. |
show
method
¶
validate_active
method
¶
Check id assigned to active attribute is a valid tab.
watch_active
method
¶
Handle a change to the active tab.
textual.widgets.Tab
class
¶
Bases: Static
A Widget to manage a single tab within a Tabs widget.
Parameters
Parameter | Default | Description |
---|---|---|
label
TextType
|
required | The label to use in the tab. |
id
str | None
|
None
|
Optional ID for the widget. |
classes
str | None
|
None
|
Space separated list of class names. |
disabled
bool
|
False
|
Whether the tab is disabled or not. |
Clicked
class
¶
Bases: TabMessage
A tab was clicked.
Disabled
class
¶
Bases: TabMessage
A tab was disabled.
Enabled
class
¶
Bases: TabMessage
A tab was enabled.