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

Return 'self' in some widget verb methods.

Browse Source 
I compiled a list of all widget methods that return 'None' and for which it _could_ make sense to make this change.
(I filtered out some methods, like watch and action methods.)

I tried choosing a subset of those methods, trying to only pick methods for which there weren't two things that could be returned (e.g., 'Widget.move_child' _could_ return either the widget or the child that was moved) and I also tried to only pick methods that have little or no parameters (e.g., 'Widget.animate' has many parameters and is typically called with quite a few.

These are all the 'Widget' methods for which this could make sense:
- 'move_child' (either return 'self' or the actual 'child' that was moved…)
- 'animate'
- 'scroll_to' / 'scroll_relate' / 'scroll_home' / 'scroll_end' / 'scroll_left' / 'scroll_right' / 'scroll_down' / 'scroll_up' / 'scroll_page_up' / 'scroll_page_down' / 'scroll_page_left' / 'scroll_page_right' / 'scroll_visible'
- 'refresh'
- 'focus' / 'reset_focus'
- 'capture_mouse' / 'release_mouse'

Additionally, I looked at each widget, and found these methods:
- 'Tree'
    - 'TreeNode'
        - 'expand' / 'expand_all' / 'collapse' / 'collapse_all' / 'toggle' / 'toggle_all'
        - 'set_label'
    - 'clear' / 'reset'
    - 'select_node' (either return 'self' or the actual 'node' that was selected)
    - 'scroll_to_line' / 'scroll_to_node'
    - 'refresh_line'
- 'ToggleButton'
    - 'toggle' (and 'action_toggle'?)
- 'TextLog'
    - 'write'
    - 'clear'
- 'Tabs'
    - 'add_tab' / 'remove_tab'
    - 'clear'
- 'Switch'
    - 'toggle' (and 'action_toggle'?)
- 'Static'
    - 'update'
- 'Pretty'
    - 'update'
- 'Placeholder'
    - 'cycle_variant'
- '_markdown.py'
    - 'MarkdownBlock'
        - 'set_content'
    - 'MarkdownTableOfContents'
        - 'set_table_of_contents'
- 'Input'
    - 'insert_text_at_cursor'
- 'DirectoryTree'
    - 'load_directory'
- 'DataTable'
    - 'update_cell' / 'update_cell_at'
    - 'clear'
    - 'refresh_coordinate' / 'refresh_row' / 'refresh_column'
    - 'sort'
- 'Button'
    - 'press'

Related issues: #1908
Related discussions: #1817
This commit is contained in:
Rodrigo Girão Serrão
2023-03-22 08:17:00 +00:00
parent 29692736d0
commit 16bdcf8f1d
10 changed files with 79 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

9
src/textual/widget.py
View File

@@ -2542,7 +2542,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
@@ -2577,6 +2577,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).
@@ -2658,7 +2659,7 @@ 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:
@@ -2674,13 +2675,15 @@ class Widget(DOMNode):
pass
self.app.call_later(set_focus, self)
return self
def reset_focus(self) -> None:
def reset_focus(self) -> Self:
"""Reset the focus (move it to the next available widget)."""
try:
self.screen._reset_focus(self)
except NoScreen:
pass
return self
def capture_mouse(self, capture: bool = True) -> None:
"""Capture (or release) the mouse.

8
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,15 @@ class Button(Static, can_focus=True):
event.stop()
self.press()
def press(self) -> None:
def press(self) -> Self:
"""Respond to a button press."""
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."""

34
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,7 +1156,7 @@ 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:
@@ -1175,7 +1175,7 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
self.hover_coordinate = Coordinate(0, 0)
self._label_column = Column(self._label_column_key, Text(), auto_width=True)
self._labelled_row_exists = False
self.refresh()
return self.refresh()
def add_column(
self, label: TextType, *, width: int | None = None, key: str | None = None
@@ -1333,49 +1333,49 @@ 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.
"""
if not self.is_valid_coordinate(coordinate):
return
return self
region = self._get_cell_region(coordinate)
self._refresh_region(region)
return self._refresh_region(region)
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.
"""
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._refresh_region(region)
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.
"""
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._refresh_region(region)
def _refresh_region(self, region: Region) -> None:
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."""
if not self.window_region.overlaps(region):
return
return self
region = region.translate(-self.scroll_offset)
self.refresh(region)
return self.refresh(region)
def is_valid_row_index(self, row_index: int) -> bool:
"""Return a boolean indicating whether the row_index is within table bounds.
@@ -1839,7 +1839,7 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
self,
*columns: ColumnKey | str,
reverse: bool = False,
) -> None:
) -> Self:
"""Sort the rows in the DataTable by one or more column keys.
Args:
@@ -1861,7 +1861,7 @@ class DataTable(ScrollView, Generic[CellType], can_focus=True):
{key: new_index for new_index, (key, _) in enumerate(ordered_rows)}
)
self._update_count += 1
self.refresh()
return self.refresh()
def _scroll_cursor_into_view(self, animate: bool = False) -> None:
"""When the cursor is at a boundary of the DataTable and moves out

5
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,10 @@ class Placeholder(Widget):
"""
return self._renderables[self.variant]
def cycle_variant(self) -> None:
def cycle_variant(self) -> Self:
"""Get the next variant in the cycle."""
self.variant = next(self._variants_cycle)
return self
def watch_variant(
self, old_variant: PlaceholderVariant, variant: PlaceholderVariant

8
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,11 @@ 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.
"""
self.value = not self.value
return self

8
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,14 @@ class Tabs(Widget, can_focus=True):
self.call_after_refresh(refresh_active)
def clear(self) -> None:
def clear(self) -> Self:
"""Clear all the tabs."""
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.

15
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:
@@ -136,7 +139,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 +157,16 @@ 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:
return self
def clear(self) -> Self:
"""Clear the text log."""
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.refresh()
def render_line(self, y: int) -> Strip:
scroll_x, scroll_y = self.scroll_offset

8
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,10 @@ class ToggleButton(Static, can_focus=True):
def get_content_height(self, container: Size, viewport: Size, width: int) -> int:
return 1
def toggle(self) -> None:
def toggle(self) -> Self:
"""Toggle the value of the widget."""
self.value = not self.value
return self
def action_toggle(self) -> None:
"""Toggle the value of the widget when called as an action.

29
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]."""
@@ -89,7 +89,7 @@ class TreeNode(Generic[TreeDataType]):
*,
expanded: bool = True,
allow_expand: bool = True,
) -> None:
):
"""Initialise the node.
Args:
@@ -201,15 +201,17 @@ class TreeNode(Generic[TreeDataType]):
for child in self.children:
child._expand(expand_all)
def expand(self) -> None:
def expand(self) -> Self:
"""Expand the node (show its children)."""
self._expand(False)
self._tree._invalidate()
return self
def expand_all(self) -> None:
def expand_all(self) -> Self:
"""Expand the node (show its children) and all those below it."""
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 +225,33 @@ class TreeNode(Generic[TreeDataType]):
for child in self.children:
child._collapse(collapse_all)
def collapse(self) -> None:
def collapse(self) -> Self:
"""Collapse the node (hide its children)."""
self._collapse(False)
self._tree._invalidate()
return self
def collapse_all(self) -> None:
def collapse_all(self) -> Self:
"""Collapse the node (hide its children) and all those below it."""
self._collapse(True)
self._tree._invalidate()
return self
def toggle(self) -> None:
def toggle(self) -> Self:
"""Toggle the node's expanded state."""
if self._expanded:
self.collapse()
else:
self.expand()
return self
def toggle_all(self) -> None:
def toggle_all(self) -> Self:
"""Toggle the node's expanded state and make all those below it match."""
if self._expanded:
self.collapse_all()
else:
self.expand_all()
return self
@property
def label(self) -> TextType:
@@ -597,7 +603,7 @@ 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:
def clear(self) -> Self:
"""Clear all nodes under root."""
self._line_cache.clear()
self._tree_lines_cached = None
@@ -613,9 +619,9 @@ class Tree(Generic[TreeDataType], ScrollView, can_focus=True):
expanded=True,
)
self._updates += 1
self.refresh()
return self.refresh()
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:
@@ -625,6 +631,7 @@ class Tree(Generic[TreeDataType], ScrollView, can_focus=True):
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.