8000 [Console] Document console cursor · symfony/symfony-docs@232c519 · GitHub
[go: up one dir, main page]
Skip to content

Commit 232c519

Browse files
noniagriconomiewouterj
noniagriconomie
authored and
wouterj
committed
[Console] Document console cursor
1 parent 7cc8d2a commit 232c519

File tree

6 files changed

+105
-1
lines changed

6 files changed

+105
-1
lines changed

‎_images/components/console/cursor.gif

63.4 KB
Loading

‎components/console/helpers/cursor.rst

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
.. index::
2+
single: Console Helpers; Cursor Helper
3+
4+
Cursor Helper
5+
=============
6+
7+
.. versionadded:: 5.1
8+
9+
The :class:`Symfony\\Component\\Console\\Cursor`
10+
class was introduced in Symfony 5.1.
11+
12+
The :class:`Symfony\\Component\\Console\\Cursor` allows you to change the
13+
cursor position in a console command. This allows you to write on any position
14+
of the output:
15+
16+
.. image:: /_images/components/console/cursor.gif
17+
:align: center
18+
19+
20+
.. code-block:: php
21+
22+
// src/Commande/MyCommand.php
23+
use Symfony\Component\Console\Command\Command;
24+
use Symfony\Component\Console\Cursor;
25+
use Symfony\Component\Console\Input\InputInterface;
26+
use Symfony\Component\Console\Output\OutputInterface;
27+
28+
class MyCommand extends Command
29+
{
30+
// ...
31+
32+
public function execute(InputInterface $input, OutputInterface $output)
33+
{
34+
// ...
35+
36+
$cursor = new Cursor($output);
37+
38+
// moves the cursor to a specific column and row position
39+
$cursor->moveToPosition(7, 11);
40+
41+
// and write text on this position using the output
42+
$output->write('My text');
43+
44+
// ...
45+
}
46+
}
47+
48+
Using the cursor
49+
----------------
50+
51+
Moving the cursor
52+
.................
53+
54+
There are fews methods to control moving the command cursor::
55+
56+
// moves the cursor 1 line up from its current position
57+
$cursor->moveUp();
58+
59+
// moves the cursor 3 lines up from its current position
60+
$cursor->moveUp(3);
61+
62+
// same for down
63+
$cursor->moveDown();
64+
65+
// moves the cursor 1 column right from its current position
66+
$cursor->moveRight();
67+
68+
// moves the cursor 3 columns right from its current position
69+
$cursor->moveRight(3);
70+
71+
// same for left
72+
$cursor->moveLeft();
73+
74+
// move the cursor to a specific position from its current position
75+
$cursor->moveToPosition(7, 11);
76+
77+
You can get the current command's cursor position by using::
78+
79+
$position = $cursor->getCurrentPosition();
80+
// $position[0] // columns (aka x coordinate)
81+
// $position[1] // rows (aka y coordinate)
82+
83+
Clearing output
84+
...............
85+
86+
The cursor can also clear some output on the screen::
87+
88+
// clears all the output from the current line
89+
$cursor->clearLine();
90+
91+
// clears all the output from the current line after the current position
92+
$cursor->clearLineAfter();
93+
94+
// clears all the output from the cursors' current position to the end of the screen
95+
$cursor->clearOutput();
96+
97+
// clears the entire screen
98+
$cursor->clearScreen();
99+
100+
You also can leverage the :method:`Symfony\\Component\\Console\\Cursor::show`
101+
and :method:`Symfony\\Component\\Console\\Cursor::hide` methods on the cursor.

‎components/console/helpers/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ The Console Helpers
1313
questionhelper
1414
table
1515
debug_formatter
16+
cursor
1617

1718
The Console component comes with some useful helpers. These helpers contain
1819
functions to ease some common tasks.

‎components/console/helpers/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@
44
* :doc:`/components/console/helpers/questionhelper`
55
* :doc:`/components/console/helpers/table`
66
* :doc:`/components/console/helpers/debug_formatter`
7+
* :doc:`/components/console/helpers/cursor`

‎components/console/helpers/progressbar.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -349,7 +349,7 @@ placeholder before displaying the progress bar::
349349
// 0/100 -- Start
350350

351351
$progressBar->setMessage('Task is in progress...');
352-
$progressBar->advance();
352+
$progressBar->advance();
353353
// 1/100 -- Task is in progress...
354354

355355
Messages can be combined with custom placeholders too. In this example, the

‎console.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -446,5 +446,6 @@ tools capable of helping you with different tasks:
446446
* :doc:`/components/console/helpers/table`: displays tabular data as a table
447447
* :doc:`/components/console/helpers/debug_formatter`: provides functions to
448448
output debug information when running an external program
449+
* :doc:`/components/console/helpers/cursor`: allows to manipulate the cursor in the terminal
449450

450451
.. _`exit status`: https://en.wikipedia.org/wiki/Exit_status

0 commit comments

Comments
 (0)
0