Skip to content
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

doc: add note to tty.WriteStream event 'resize' on Windows #13576

Closed
wants to merge 9 commits into from
Closed

doc: add note to tty.WriteStream event 'resize' on Windows #13576

Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
6da59fe
doc: note 'resize' event unreliability on Windows
Dean-Coakley Jun 9, 2017
a45bd1d
doc: correct 'resize' event note
Dean-Coakley Jun 9, 2017
84db75d
doc: add more detail on note
Dean-Coakley Jun 15, 2017
63fa375
doc: correct char limit
Dean-Coakley Jun 15, 2017
86dfd24
doc: add more detail on note
Dean-Coakley Jul 7, 2017
192a56f
doc: fix details on note
Dean-Coakley Jul 7, 2017
784055f
doc: fix err on resume note
Dean-Coakley Jul 7, 2017
05ce78a
doc: remove backslash
Dean-Coakley Jul 7, 2017
5944bf0
doc: merge note paragraphs
Dean-Coakley Jul 9, 2017
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
4 changes: 4 additions & 0 deletions doc/api/tty.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,10 @@ process.stdout.on('resize', () => {
});
```

*Note:* Terminal window resize events are unreliable on Windows. The event
handler is only executed for changes in the width of the window and the
Copy link
Contributor

Choose a reason for hiding this comment

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

If the console buffer height is changed, the event will also triggered. The buffer is not shrinked when downsizing widow, so it can look like changing height is ignored. If however one sets buffer height to something small in the options and then increase window height the event will be triggered.

Copy link
Member

Choose a reason for hiding this comment

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

@bzoz that seems like a lot of information, could you suggest the exact wording you want?

Copy link
Contributor

Choose a reason for hiding this comment

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

On Windows the console size is the virtual buffer size, not the size of the console window itself. If you shrink window height, the buffer size will remain the same, so no event will be fired. If you enlarge window enough that it will be higher than the buffer, Windows will update the buffer size and event will be signaled.

On Windows the event reliably detected only if the console is read (e.g. process.stdin.resume(); or process.stdin.on('data',...)) in raw mode.

If the console is not read, or is read in line mode, this event can still be signaled. This will happen if a terminal sequence that moves the cursor is used. Calling process.stdin._refreshSize() will also trigger the event if the console size has been changed.

Copy link
Contributor

Choose a reason for hiding this comment

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

One more clarification: although the event is signaled only when the buffer height is changed and not the window size, Node.js reports the console window height, not the height of the buffer itself.

Copy link
Member

Choose a reason for hiding this comment

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

@bzoz so you think the **Note:** should look like this?

Note: On Windows the console size is the virtual buffer size, not the size of the console window itself. If you shrink window height, the buffer size will remain the same, so no event will be fired. If you enlarge window enough that it will be higher than the buffer, Windows will update the buffer size and event will be signaled.

On Windows the event reliably detected only if the console is read (e.g. process.stdin.resume(); or process.stdin.on('data',...)) in raw mode.

If the console is not read, or is read in line mode, this event can still be signaled. This will happen if a terminal sequence that moves the cursor is used. Calling process.stdin._refreshSize() will also trigger the event if the console size has been changed.

Although the event is signaled only when the buffer height is changed and not the window size, Node.js reports the console window height, not the height of the buffer itself.

That seems like a massive amount of info.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yep, I think there is too much detail in this note. It would also make ._refreshSize() somewhat documented function. I propose this:

Note: On Windows resize events will be emitted only if stdin is unpaused (by a call to resume() or by adding data listener) and in raw mode. It can be also triggered if terminal control sequence that moves the cursor is written to the screen.

Note: On Windows when changing console height the resize event will be signaled only if console screen buffer height was also changed. For example shrinking the console window height will not cause the resize event to be emitted. Increasing the console window height will only be registered when new console window height is greater than current console buffer size.

console must be in raw mode.

### writeStream.columns
<!-- YAML
added: v0.7.7
Expand Down