alihan/textual
1
0
Fork 0
mirror of https://github.com/Textualize/textual.git synced 2025-10-17 02:38:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2102 from Textualize/verb-methods-return-self

Browse Source 
Return 'self' in some widget verb methods.
This commit is contained in:
Rodrigo Girão Serrão
2023-03-23 15:00:18 +00:00
committed by GitHub
parent 461db5dcd6 65e005cffe
commit 139896260b
11 changed files with 194 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
CHANGELOG.md
View File

@@ -33,6 +33,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
- Breaking change: changed default behaviour of `Vertical` (see `VerticalScroll`) https://github.com/Textualize/textual/issues/1957
- The default `overflow` style for `Horizontal` was changed to `hidden hidden` https://github.com/Textualize/textual/issues/1957
- `DirectoryTree` also accepts `pathlib.Path` objects as the path to list https://github.com/Textualize/textual/issues/1438
- Some widget methods now return `self` instead of `None` https://github.com/Textualize/textual/pull/2102:
- `Widget`: `refresh`, `focus`, `reset_focus`
- `Button.press`
- `DataTable`: `clear`, `refresh_coordinate`, `refresh_row`, `refresh_column`, `sort`
- `Placehoder.cycle_variant`
- `Switch.toggle`
- `Tabs.clear`
- `TextLog`: `write`, `clear`
- `TreeNode`: `expand`, `expand_all`, `collapse`, `collapse_all`, `toggle`, `toggle_all`
- `Tree`: `clear`, `reset`
### Removed

6
src/textual/dom.py
View File

@@ -42,7 +42,7 @@ if TYPE_CHECKING:
from .css.query import DOMQuery, QueryType
from .screen import Screen
from .widget import Widget
from typing_extensions import TypeAlias
from typing_extensions import Self, TypeAlias
from typing_extensions import Literal
@@ -950,5 +950,5 @@ class DOMNode(MessagePump):
has_pseudo_classes = self.pseudo_classes.issuperset(class_names)
return has_pseudo_classes
def refresh(self, *, repaint: bool = True, layout: bool = False) -> None:
pass
def refresh(self, *, repaint: bool = True, layout: bool = False) -> Self:
return self

28
src/textual/widget.py
View File

@@ -2560,7 +2560,7 @@ class Widget(DOMNode):
*regions: Region,
repaint: bool = True,
layout: bool = False,
) -> None:
) -> Self:
"""Initiate a refresh of the widget.
This method sets an internal flag to perform a refresh, which will be done on the
@@ -2576,8 +2576,11 @@ class Widget(DOMNode):
Args:
*regions: Additional screen regions to mark as dirty.
repaint: Repaint the widget (will call render() again). Defaults to True.
layout: Also layout widgets in the view. Defaults to False.
repaint: Repaint the widget (will call render() again).
layout: Also layout widgets in the view.
Returns:
The `Widget` instance.
"""
if layout and not self._layout_required:
self._layout_required = True
@@ -2595,6 +2598,7 @@ class Widget(DOMNode):
self._repaint_required = True
self.check_idle()
return self
def remove(self) -> AwaitRemove:
"""Remove the Widget from the DOM (effectively deleting it).
@@ -2676,12 +2680,14 @@ class Widget(DOMNode):
self._layout_required = False
screen.post_message(messages.Layout())
def focus(self, scroll_visible: bool = True) -> None:
def focus(self, scroll_visible: bool = True) -> Self:
"""Give focus to this widget.
Args:
scroll_visible: Scroll parent to make this widget
visible. Defaults to True.
scroll_visible: Scroll parent to make this widget visible.
Returns:
The `Widget` instance.
"""
def set_focus(widget: Widget):
@@ -2692,13 +2698,19 @@ class Widget(DOMNode):
pass
self.app.call_later(set_focus, self)
return self
def reset_focus(self) -> None:
"""Reset the focus (move it to the next available widget)."""
def reset_focus(self) -> Self:
"""Reset the focus (move it to the next available widget).
Returns:
The `Widget` instance.
"""
try:
self.screen._reset_focus(self)
except NoScreen:
pass
return self
def capture_mouse(self, capture: bool = True) -> None:
"""Capture (or release) the mouse.

13
src/textual/widgets/_button.py
View File

@@ -1,11 +1,10 @@
from __future__ import annotations
from functools import partial
from typing import cast
import rich.repr
from rich.text import Text, TextType
from typing_extensions import Literal
from typing_extensions import Literal, Self
from .. import events
from ..css._error_tools import friendly_list
@@ -233,14 +232,18 @@ class Button(Static, can_focus=True):
event.stop()
self.press()
def press(self) -> None:
"""Respond to a button press."""
def press(self) -> Self:
"""Respond to a button press.
Returns:
The button instance."""
if self.disabled or not self.display:
return
return self
# Manage the "active" effect:
self._start_active_affect()
# ...and let other components know that we've just been clicked:
self.post_message(Button.Pressed(self))
return self
def _start_active_affect(self) -> None:
"""Start a small animation to show the button was clicked."""

57
src/textual/widgets/_data_table.py
View File

@@ -13,7 +13,7 @@ from rich.protocol import is_renderable
from rich.segment import Segment
from rich.style import Style
from rich.text import Text, TextType
from typing_extensions import Literal, TypeAlias
from typing_extensions import Literal, Self, TypeAlias
from .. import events
from .._cache import LRUCache
@@ -1156,11 +1156,14 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
full_column_region = Region(x, 0, width, height)
return full_column_region
def clear(self, columns: bool = False) -> None:
def clear(self, columns: bool = False) -> Self:
"""Clear the table.
Args:
columns: Also clear the columns. Defaults to False.
columns: Also clear the columns.
Returns:
The `DataTable` instance.
"""
self._clear_caches()
self._y_offsets.clear()
@@ -1176,6 +1179,7 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
self._label_column = Column(self._label_column_key, Text(), auto_width=True)
self._labelled_row_exists = False
self.refresh()
return self
def add_column(
self, label: TextType, *, width: int | None = None, key: str | None = None
@@ -1333,49 +1337,66 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
self._updated_cells.clear()
self._update_column_widths(updated_columns)
def refresh_coordinate(self, coordinate: Coordinate) -> None:
def refresh_coordinate(self, coordinate: Coordinate) -> Self:
"""Refresh the cell at a coordinate.
Args:
coordinate: The coordinate to refresh.
Returns:
The `DataTable` instance.
"""
if not self.is_valid_coordinate(coordinate):
return
return self
region = self._get_cell_region(coordinate)
self._refresh_region(region)
return self
def refresh_row(self, row_index: int) -> None:
def refresh_row(self, row_index: int) -> Self:
"""Refresh the row at the given index.
Args:
row_index: The index of the row to refresh.
Returns:
The `DataTable` instance.
"""
if not self.is_valid_row_index(row_index):
return
return self
region = self._get_row_region(row_index)
self._refresh_region(region)
return self
def refresh_column(self, column_index: int) -> None:
def refresh_column(self, column_index: int) -> Self:
"""Refresh the column at the given index.
Args:
column_index: The index of the column to refresh.
Returns:
The `DataTable` instance.
"""
if not self.is_valid_column_index(column_index):
return
return self
region = self._get_column_region(column_index)
self._refresh_region(region)
return self
def _refresh_region(self, region: Region) -> None:
"""Refresh a region of the DataTable, if it's visible within
the window. This method will translate the region to account
for scrolling."""
def _refresh_region(self, region: Region) -> Self:
"""Refresh a region of the DataTable, if it's visible within the window.
This method will translate the region to account for scrolling.
Returns:
The `DataTable` instance.
"""
if not self.window_region.overlaps(region):
return
return self
region = region.translate(-self.scroll_offset)
self.refresh(region)
return self
def is_valid_row_index(self, row_index: int) -> bool:
"""Return a boolean indicating whether the row_index is within table bounds.
@@ -1839,12 +1860,15 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
self,
*columns: ColumnKey | str,
reverse: bool = False,
) -> None:
"""Sort the rows in the DataTable by one or more column keys.
) -> Self:
"""Sort the rows in the `DataTable` by one or more column keys.
Args:
columns: One or more columns to sort by the values in.
reverse: If True, the sort order will be reversed.
Returns:
The `DataTable` instance.
"""
def sort_by_column_keys(
@@ -1862,6 +1886,7 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
)
self._update_count += 1
self.refresh()
return self
def _scroll_cursor_into_view(self, animate: bool = False) -> None:
"""When the cursor is at a boundary of the DataTable and moves out

11
src/textual/widgets/_placeholder.py
View File

@@ -5,7 +5,7 @@ from __future__ import annotations
from itertools import cycle
from rich.console import RenderableType
from typing_extensions import Literal
from typing_extensions import Literal, Self
from .. import events
from ..css._error_tools import friendly_list
@@ -132,9 +132,14 @@ class Placeholder(Widget):
"""
return self._renderables[self.variant]
def cycle_variant(self) -> None:
"""Get the next variant in the cycle."""
def cycle_variant(self) -> Self:
"""Get the next variant in the cycle.
Returns:
The `Placeholder` instance.
"""
self.variant = next(self._variants_cycle)
return self
def watch_variant(
self, old_variant: PlaceholderVariant, variant: PlaceholderVariant

11
src/textual/widgets/_switch.py
View File

@@ -1,6 +1,6 @@
from __future__ import annotations
from typing import ClassVar
from typing import TYPE_CHECKING, ClassVar
from rich.console import RenderableType
@@ -11,6 +11,9 @@ from ..reactive import reactive
from ..scrollbar import ScrollBarRender
from ..widget import Widget
if TYPE_CHECKING:
from typing_extensions import Self
class Switch(Widget, can_focus=True):
"""A switch widget that represents a boolean value.
@@ -158,10 +161,14 @@ class Switch(Widget, can_focus=True):
"""Toggle the state of the switch."""
self.toggle()
def toggle(self) -> None:
def toggle(self) -> Self:
"""Toggle the switch value.
As a result of the value changing, a `Switch.Changed` message will
be posted.
Returns:
The `Switch` instance.
"""
self.value = not self.value
return self

14
src/textual/widgets/_tabs.py
View File

@@ -1,6 +1,6 @@
from __future__ import annotations
from typing import ClassVar
from typing import TYPE_CHECKING, ClassVar
import rich.repr
from rich.style import Style
@@ -18,6 +18,9 @@ from ..renderables.underline_bar import UnderlineBar
from ..widget import Widget
from ..widgets import Static
if TYPE_CHECKING:
from typing_extensions import Self
class Underline(Widget):
"""The animated underline beneath tabs."""
@@ -316,13 +319,18 @@ class Tabs(Widget, can_focus=True):
self.call_after_refresh(refresh_active)
def clear(self) -> None:
"""Clear all the tabs."""
def clear(self) -> Self:
"""Clear all the tabs.
Returns:
The `Tabs` instance.
"""
underline = self.query_one(Underline)
underline.highlight_start = 0
underline.highlight_end = 0
self.query("#tabs-list > Tab").remove()
self.post_message(self.Cleared(self))
return self
def remove_tab(self, tab_or_id: Tab | str | None) -> None:
"""Remove a tab.

23
src/textual/widgets/_text_log.py
View File

@@ -2,7 +2,7 @@
from __future__ import annotations
from typing import Optional, cast
from typing import TYPE_CHECKING, Optional, cast
from rich.console import RenderableType
from rich.highlighter import ReprHighlighter
@@ -18,6 +18,9 @@ from ..reactive import var
from ..scroll_view import ScrollView
from ..strip import Strip
if TYPE_CHECKING:
from typing_extensions import Self
class TextLog(ScrollView, can_focus=True):
"""A widget for logging text."""
@@ -89,7 +92,7 @@ class TextLog(ScrollView, can_focus=True):
width: int | None = None,
expand: bool = False,
shrink: bool = True,
) -> None:
) -> Self:
"""Write text or a rich renderable.
Args:
@@ -97,6 +100,9 @@ class TextLog(ScrollView, can_focus=True):
width: Width to render or ``None`` to use optimal width.
expand: Enable expand to widget width, or ``False`` to use `width`.
shrink: Enable shrinking of content to fit width.
Returns:
The `TextLog` instance.
"""
renderable: RenderableType
@@ -136,7 +142,7 @@ class TextLog(ScrollView, can_focus=True):
)
lines = list(Segment.split_lines(segments))
if not lines:
return
return self
self.max_width = max(
self.max_width,
@@ -154,14 +160,21 @@ class TextLog(ScrollView, can_focus=True):
self.virtual_size = Size(self.max_width, len(self.lines))
self.scroll_end(animate=False)
def clear(self) -> None:
"""Clear the text log."""
return self
def clear(self) -> Self:
"""Clear the text log.
Returns:
The `TextLog` instance.
"""
self.lines.clear()
self._line_cache.clear()
self._start_line = 0
self.max_width = 0
self.virtual_size = Size(self.max_width, len(self.lines))
self.refresh()
return self
def render_line(self, y: int) -> Strip:
scroll_x, scroll_y = self.scroll_offset

14
src/textual/widgets/_toggle_button.py
View File

@@ -5,7 +5,7 @@ In particular it provides `Checkbox`, `RadioButton` and `RadioSet`.
from __future__ import annotations
from typing import ClassVar
from typing import TYPE_CHECKING, ClassVar
from rich.style import Style
from rich.text import Text, TextType
@@ -17,6 +17,9 @@ from ..message import Message
from ..reactive import reactive
from ._static import Static
if TYPE_CHECKING:
from typing_extensions import Self
class ToggleButton(Static, can_focus=True):
"""Base toggle button widget.
@@ -201,9 +204,14 @@ class ToggleButton(Static, can_focus=True):
def get_content_height(self, container: Size, viewport: Size, width: int) -> int:
return 1
def toggle(self) -> None:
"""Toggle the value of the widget."""
def toggle(self) -> Self:
"""Toggle the value of the widget.
Returns:
The `ToggleButton` instance.
"""
self.value = not self.value
return self
def action_toggle(self) -> None:
"""Toggle the value of the widget when called as an action.

71
src/textual/widgets/_tree.py
View File

@@ -22,7 +22,7 @@ from ..scroll_view import ScrollView
from ..strip import Strip
if TYPE_CHECKING:
from typing_extensions import TypeAlias
from typing_extensions import Self, TypeAlias
NodeID = NewType("NodeID", int)
"""The type of an ID applied to a [TreeNode][textual.widgets._tree.TreeNode]."""
@@ -201,15 +201,25 @@ class TreeNode(Generic[TreeDataType]):
for child in self.children:
child._expand(expand_all)
def expand(self) -> None:
"""Expand the node (show its children)."""
def expand(self) -> Self:
"""Expand the node (show its children).
Returns:
The `TreeNode` instance.
"""
self._expand(False)
self._tree._invalidate()
return self
def expand_all(self) -> None:
"""Expand the node (show its children) and all those below it."""
def expand_all(self) -> Self:
"""Expand the node (show its children) and all those below it.
Returns:
The `TreeNode` instance.
"""
self._expand(True)
self._tree._invalidate()
return self
def _collapse(self, collapse_all: bool) -> None:
"""Mark the node as collapsed (its children are hidden).
@@ -223,29 +233,49 @@ class TreeNode(Generic[TreeDataType]):
for child in self.children:
child._collapse(collapse_all)
def collapse(self) -> None:
"""Collapse the node (hide its children)."""
def collapse(self) -> Self:
"""Collapse the node (hide its children).
Returns:
The `TreeNode` instance.
"""
self._collapse(False)
self._tree._invalidate()
return self
def collapse_all(self) -> None:
"""Collapse the node (hide its children) and all those below it."""
def collapse_all(self) -> Self:
"""Collapse the node (hide its children) and all those below it.
Returns:
The `TreeNode` instance.
"""
self._collapse(True)
self._tree._invalidate()
return self
def toggle(self) -> None:
"""Toggle the node's expanded state."""
def toggle(self) -> Self:
"""Toggle the node's expanded state.
Returns:
The `TreeNode` instance.
"""
if self._expanded:
self.collapse()
else:
self.expand()
return self
def toggle_all(self) -> None:
"""Toggle the node's expanded state and make all those below it match."""
def toggle_all(self) -> Self:
"""Toggle the node's expanded state and make all those below it match.
Returns:
The `TreeNode` instance.
"""
if self._expanded:
self.collapse_all()
else:
self.expand_all()
return self
@property
def label(self) -> TextType:
@@ -597,8 +627,12 @@ class Tree(Generic[TreeDataType], ScrollView, can_focus=True):
label = self.render_label(node, NULL_STYLE, NULL_STYLE)
return label.cell_len
def clear(self) -> None:
"""Clear all nodes under root."""
def clear(self) -> Self:
"""Clear all nodes under root.
Returns:
The `Tree` instance.
"""
self._line_cache.clear()
self._tree_lines_cached = None
self._current_id = 0
@@ -614,17 +648,22 @@ class Tree(Generic[TreeDataType], ScrollView, can_focus=True):
)
self._updates += 1
self.refresh()
return self
def reset(self, label: TextType, data: TreeDataType | None = None) -> None:
def reset(self, label: TextType, data: TreeDataType | None = None) -> Self:
"""Clear the tree and reset the root node.
Args:
label: The label for the root node.
data: Optional data for the root node.
Returns:
The `Tree` instance.
"""
self.clear()
self.root.label = label
self.root.data = data
return self
def select_node(self, node: TreeNode[TreeDataType] | None) -> None:
"""Move the cursor to the given node, or reset cursor.