Skip to content

Some clarification on smart refresh #5780

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Some clarification on smart refresh #5780

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/guide/reactivity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ You may want to add explicit type hints if the attribute type is a superset of t

## Smart refresh

The first superpower we will look at is "smart refresh". When you modify a reactive attribute, Textual will make note of the fact that it has changed and refresh automatically.
The first superpower we will look at is "smart refresh". When you modify a reactive attribute, Textual will make note of the fact that it has changed and refresh automatically. It does this by calling the `render()` method of the widget that contains the reactive. A typical render method will make use of the reactive's value although that is not strictly necessary.

!!! information

Expand Down Expand Up @@ -96,6 +96,10 @@ The `Name` widget has a reactive `who` attribute. When the app modifies that att

Textual will check if a value has really changed, so assigning the same value wont prompt an unnecessary refresh.

!!! information

[Compound widgets](widgets.md/#compound-widgets) do not contain a `render()` method, but rather a `compose()` method. Smart refresh will do nothing, but you can use a [watch method](#watch-methods) to run code to update child widgets if needed. Alternatively, you can use [recompose](#recompose) to remove all child widgets and call `compose()` again.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't quite accurate. Compound widgets do have render methods, and they are called. Although for most compound widgets, the child widgets cover the parent fully so you never see that.

I've updated the initial paragraph, but I feel this may be too much information at this point. I don't like to have two admonitions next to each other. I also prefer to keep things as linear as possible within a single page, so we aren't encouraging the reader to jump down before they have read the initial text.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't know that the render method of compound widgets was actually called. Makes sense, but in my head, writing widgets, it was always either a render() method or a compose() method. But the one does not exclude the other.

I agree that too much information is not good, and two admonitions are a bit ugly. If you don't want users to jump ahead, I feel that a remark should be made in the relevant sections. I had a bit of trouble with smart refresh as well, and understanding that I should use a watch method for updating child widgets. The word "child" is only first mentioned in the recompose section. But, for most uses, you don't want to use recompose since that is not efficient for simply updating child widgets.


### Disabling refresh

If you *don't* want an attribute to prompt a refresh or layout but you still want other reactive superpowers, you can use [var][textual.reactive.var] to create an attribute. You can import `var` from `textual.reactive`.
Expand Down