[Console] Add Cursor class to control the cursor in the terminal #27444

pierredup · 2018-05-31T10:46:42Z

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	N/A
License	MIT
Doc PR	TBD

Add a new Cursor class to the Console component, that allows to manipulate the cursor in the terminal.

Options to move the cursor include: moveUp, moveDown, moveLeft, moveRight, show, hide, save and restore position, get current position etc.

Example usage:

$cursor = new Cursor($output);

$parts = [
    ['x' => 9, 'y' => 5, 'string' => '#'],
    ['x' => 9, 'y' => 7, 'string' => '#'],
    ['x' => 2, 'y' => 7, 'string' => '#####'],
    ['x' => 9, 'y' => 1, 'string' => '#######'],
    ['x' => 7, 'y' => 6, 'string' => '#'],
    ['x' => 9, 'y' => 2, 'string' => '#'],
    ['x' => 9, 'y' => 6, 'string' => '#'],
    ['x' => 9, 'y' => 3, 'string' => '#'],
    ['x' => 2, 'y' => 1, 'string' => '#####'],
    ['x' => 7, 'y' => 2, 'string' => '#'],
    ['x' => 9, 'y' => 4, 'string' => '#####'],
    ['x' => 1, 'y' => 2, 'string' => '#'],
    ['x' => 1, 'y' => 6, 'string' => '#'],
    ['x' => 2, 'y' => 4, 'string' => '#####'],
    ['x' => 1, 'y' => 3, 'string' => '#'],
    ['x' => 7, 'y' => 5, 'string' => '#'],
];

foreach ($parts as $part) {
    $cursor->moveToPosition($part['x'], $part['y']);
    $output->write($part['string']);

    usleep(200000);
}

$cursor->moveToPosition(1, 8);

Result:

javiereguiluz · 2018-05-31T14:07:48Z

For reference purposes, I've look for the APIs for this feature in other projects:

Go libraries and .Net libraries have just a few methods:

https://godoc.org/github.com/nsf/termbox-go

func HideCursor()
func SetCursor(x, y int)

https://godoc.org/github.com/gdamore/tcell

func HideCursor()
func ShowCursor(x int, y int)

.Net (https://msdn.microsoft.com/en-us/library/system.console_methods(v=vs.110).aspx)

SetCursorPosition(Int32, Int32)

And some properties:

CursorLeft
CursorTop
CursorVisible
...

On the other hand, JS libraries define a ton of methods:

https://github.com/cronvel/terminal-kit/blob/master/doc/low-level.md#ref.movingCursor

.saveCursor()
.restoreCursor()
.up(int n)
.down(int n)
.right(int n)
.left(int n)
.nextLine(int n)
.previousLine(int n)
.column(int x)
.scrollUp(int n)
.scrollDown(int n)
.scrollingRegion(top, bottom)
.resetScrollingRegion()
.moveTo(int x, int y)
.move(int x, int y)
.hideCursor()
.tabSet()
.tabClear()
.tabClearAll()
.forwardTab(int n)
.backwardTab(int n)

So we need to think if we want a simple (but enough) API or a complex (but useful) API.

ogizanagi · 2018-06-01T06:14:06Z

Also see the HOA Project Console Cursor API: https://github.com/hoaproject/Console#cursor

yceruto

Thanks for this feature! I left two minor comments.

src/Symfony/Component/Console/Cursor.php

src/Symfony/Component/Console/Tests/CursorTest.php

nicolas-grekas · 2018-06-19T12:02:56Z

@pierredup see test failures :) Also, any comment when comparing the proposed API with the linked ones? Do any of them provide any idea to borrow?

pierredup · 2019-02-11T07:39:59Z

I prefer having a few explicit methods (E.G moveUp, moveDown) instead of just a couple generic methods, so I would much rather go the route of the JS libraries (although not as many methods as they have).

chalasr

Can we update QuestionHelper to make it use this for autocompletion?
I'm fine with the current naming.

src/Symfony/Component/Console/Cursor.php

pierredup · 2019-12-10T13:49:56Z

Can we update QuestionHelper to make it use this for autocompletion?

@chalasr Done

chalasr

Can you add a CHANGELOG entry and rebase to see tests green?

src/Symfony/Component/Console/Helper/QuestionHelper.php

chalasr · 2019-12-10T17:03:14Z

src/Symfony/Component/Console/Cursor.php

+    public function clearScreen()
+    {
+        $this->output->write("\x1b[2J", false);
+    }


Does it really belong to the cursor?

fabpot

LGTM.

Can we also have methods to get the max x and max y of the console/cursor? I think we already have the code in Symfony, that would be good to have it here as well.

Maybe we can simplify the progress bar code as well.

src/Symfony/Component/Console/Helper/QuestionHelper.php

pierredup · 2020-03-26T09:15:36Z

I've rebased from master, and updated the Progress bar to use the Cursor class as well.

Can we also have methods to get the max x and max y of the console

This is currently available in the Terminal class for this component, so I'm not sure if it should be in the Cursor class as well

chalasr · 2020-03-27T10:09:54Z

Agree about keeping the terminal size logic in the Terminal class.
@pierredup Some related tests are failing, can you have a look?

src/Symfony/Component/Console/Cursor.php

chalasr

LGTM :) Missing CHANGELOG entry

fabpot · 2020-04-12T07:40:09Z

Thanks @pierredup for working on this feature, this is much appreciated.

@pierredup

This PR was squashed before being merged into the 5.1-dev branch. Discussion ---------- [Console] cursor tweaks | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | Deprecations? | no  | Tickets | Refs #27444 | License | MIT | Doc PR | n/a While playing with the new cursor class, I realized that I would like to make some changes. Mainly having a fluent interface: `$cursor->moveUp(10)->clearOutput()` for instance. I have also separater the `clearLine()` method in two method to avoid the bool arg. /cc @pierredup Commits ------- 5a7b314 Make the Cursor class final b0e7eb6 Make Cursor fluent 55fef91 Split a method d00b5b5 Remove default value

This PR was submitted for the 5.4 branch but it was squashed and merged into the 5.2 branch instead. Discussion ---------- [Console] Document console cursor fixes #13529 feature symfony/symfony#27444 ping `@wouterj` I've seen your slack recently and wanted to give it a try as I will use the feature very soon :) feel free to comment, specialy if I need to document all the cursor features or not text and image taken from the feature PR description inspired by https://symfony.com/doc/current/components/console/helpers/progressbar.html Commits ------- 232c519 [Console] Document console cursor

carsonbot added Status: Needs Review Console Feature labels May 31, 2018

pierredup force-pushed the cursor-helper branch from 44ef0c5 to 344100d Compare May 31, 2018 10:48

yceruto reviewed Jun 1, 2018

View reviewed changes

src/Symfony/Component/Console/Cursor.php Outdated Show resolved Hide resolved

src/Symfony/Component/Console/Tests/CursorTest.php Outdated Show resolved Hide resolved

nicolas-grekas added this to the next milestone Jun 1, 2018

pierredup force-pushed the cursor-helper branch from 344100d to 78752d6 Compare June 3, 2018 13:26

pierredup force-pushed the cursor-helper branch 2 times, most recently from 7501b0f to 2ad0290 Compare February 11, 2019 07:24

chalasr reviewed Dec 2, 2019

View reviewed changes

src/Symfony/Component/Console/Cursor.php Outdated Show resolved Hide resolved

pierredup force-pushed the cursor-helper branch from 2ad0290 to 6ff2395 Compare December 10, 2019 13:43

chalasr reviewed Dec 10, 2019

View reviewed changes

fabpot requested changes Feb 3, 2020

View reviewed changes

src/Symfony/Component/Console/Helper/QuestionHelper.php Outdated Show resolved Hide resolved

src/Symfony/Component/Console/Helper/QuestionHelper.php Outdated Show resolved Hide resolved

src/Symfony/Component/Console/Helper/QuestionHelper.php Outdated Show resolved Hide resolved

carsonbot added Status: Needs Work and removed Status: Needs Review labels Feb 3, 2020

pierredup force-pushed the cursor-helper branch from 2015276 to b7b8b4f Compare March 26, 2020 07:50

chalasr reviewed Mar 27, 2020

View reviewed changes

src/Symfony/Component/Console/Cursor.php Outdated Show resolved Hide resolved

chalasr approved these changes Mar 27, 2020

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Work labels Mar 27, 2020

chalasr added the Ready label Mar 27, 2020

fabpot approved these changes Apr 12, 2020

View reviewed changes

[Console] Add Cursor class to control the cursor in the terminal

80d59d5

fabpot force-pushed the cursor-helper branch from f924a02 to 80d59d5 Compare April 12, 2020 07:39

fabpot mentioned this pull request Apr 12, 2020

[Console] Add Cursor class to control the cursor in the terminal symfony/symfony-docs#13529

Closed

fabpot merged commit d69b8bb into symfony:master Apr 12, 2020

fabpot mentioned this pull request Apr 12, 2020

[Console] cursor tweaks #36433

Merged

nicolas-grekas modified the milestones: next, 5.1 May 4, 2020

fabpot mentioned this pull request May 5, 2020

Release v5.1.0-BETA1 #36713

Merged

noniagriconomie mentioned this pull request Apr 21, 2021

[Console] Document console cursor symfony/symfony-docs#15270

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Console] Add Cursor class to control the cursor in the terminal #27444

[Console] Add Cursor class to control the cursor in the terminal #27444

pierredup commented May 31, 2018

javiereguiluz commented May 31, 2018

ogizanagi commented Jun 1, 2018 •

edited

Loading

yceruto left a comment •

edited

Loading

nicolas-grekas commented Jun 19, 2018

pierredup commented Feb 11, 2019

chalasr left a comment

pierredup commented Dec 10, 2019

chalasr left a comment

chalasr Dec 10, 2019

fabpot left a comment

pierredup commented Mar 26, 2020

chalasr commented Mar 27, 2020

chalasr left a comment

fabpot commented Apr 12, 2020

[Console] Add Cursor class to control the cursor in the terminal #27444

[Console] Add Cursor class to control the cursor in the terminal #27444

Conversation

pierredup commented May 31, 2018

javiereguiluz commented May 31, 2018

ogizanagi commented Jun 1, 2018 • edited Loading

yceruto left a comment • edited Loading

Choose a reason for hiding this comment

nicolas-grekas commented Jun 19, 2018

pierredup commented Feb 11, 2019

chalasr left a comment

Choose a reason for hiding this comment

pierredup commented Dec 10, 2019

chalasr left a comment

Choose a reason for hiding this comment

chalasr Dec 10, 2019

Choose a reason for hiding this comment

fabpot left a comment

Choose a reason for hiding this comment

pierredup commented Mar 26, 2020

chalasr commented Mar 27, 2020

chalasr left a comment

Choose a reason for hiding this comment

fabpot commented Apr 12, 2020

ogizanagi commented Jun 1, 2018 •

edited

Loading

yceruto left a comment •

edited

Loading