diff --git a/_images/components/console/cursor.gif b/_images/components/console/cursor.gif new file mode 100644 index 00000000000..a4fd844eb80 Binary files /dev/null and b/_images/components/console/cursor.gif differ diff --git a/components/console/helpers/cursor.rst b/components/console/helpers/cursor.rst new file mode 100644 index 00000000000..63497faed0d --- /dev/null +++ b/components/console/helpers/cursor.rst @@ -0,0 +1,101 @@ +.. index:: + single: Console Helpers; Cursor Helper + +Cursor Helper +============= + +.. versionadded:: 5.1 + + The :class:`Symfony\\Component\\Console\\Cursor` + class was introduced in Symfony 5.1. + +The :class:`Symfony\\Component\\Console\\Cursor` allows you to change the +cursor position in a console command. This allows you to write on any position +of the output: + +.. image:: /_images/components/console/cursor.gif + :align: center + + +.. code-block:: php + + // src/Commande/MyCommand.php + use Symfony\Component\Console\Command\Command; + use Symfony\Component\Console\Cursor; + use Symfony\Component\Console\Input\InputInterface; + use Symfony\Component\Console\Output\OutputInterface; + + class MyCommand extends Command + { + // ... + + public function execute(InputInterface $input, OutputInterface $output) + { + // ... + + $cursor = new Cursor($output); + + // moves the cursor to a specific column and row position + $cursor->moveToPosition(7, 11); + + // and write text on this position using the output + $output->write('My text'); + + // ... + } + } + +Using the cursor +---------------- + +Moving the cursor +................. + +There are fews methods to control moving the command cursor:: + + // moves the cursor 1 line up from its current position + $cursor->moveUp(); + + // moves the cursor 3 lines up from its current position + $cursor->moveUp(3); + + // same for down + $cursor->moveDown(); + + // moves the cursor 1 column right from its current position + $cursor->moveRight(); + + // moves the cursor 3 columns right from its current position + $cursor->moveRight(3); + + // same for left + $cursor->moveLeft(); + + // move the cursor to a specific position from its current position + $cursor->moveToPosition(7, 11); + +You can get the current command's cursor position by using:: + + $position = $cursor->getCurrentPosition(); + // $position[0] // columns (aka x coordinate) + // $position[1] // rows (aka y coordinate) + +Clearing output +............... + +The cursor can also clear some output on the screen:: + + // clears all the output from the current line + $cursor->clearLine(); + + // clears all the output from the current line after the current position + $cursor->clearLineAfter(); + + // clears all the output from the cursors' current position to the end of the screen + $cursor->clearOutput(); + + // clears the entire screen + $cursor->clearScreen(); + +You also can leverage the :method:`Symfony\\Component\\Console\\Cursor::show` +and :method:`Symfony\\Component\\Console\\Cursor::hide` methods on the cursor. diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst index 5f328d47472..09546769655 100644 --- a/components/console/helpers/index.rst +++ b/components/console/helpers/index.rst @@ -13,6 +13,7 @@ The Console Helpers questionhelper table debug_formatter + cursor The Console component comes with some useful helpers. These helpers contain functions to ease some common tasks. diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc index 68e1e722a87..8f9ce0ca0f3 100644 --- a/components/console/helpers/map.rst.inc +++ b/components/console/helpers/map.rst.inc @@ -4,3 +4,4 @@ * :doc:`/components/console/helpers/questionhelper` * :doc:`/components/console/helpers/table` * :doc:`/components/console/helpers/debug_formatter` +* :doc:`/components/console/helpers/cursor` diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index ebdcaba1d64..4f1dd8fe3a5 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -349,7 +349,7 @@ placeholder before displaying the progress bar:: // 0/100 -- Start $progressBar->setMessage('Task is in progress...'); - $progressBar->advance(); + $progressBar->advance(); // 1/100 -- Task is in progress... Messages can be combined with custom placeholders too. In this example, the diff --git a/console.rst b/console.rst index aa23bddbffd..b4add295fd4 100644 --- a/console.rst +++ b/console.rst @@ -446,5 +446,6 @@ tools capable of helping you with different tasks: * :doc:`/components/console/helpers/table`: displays tabular data as a table * :doc:`/components/console/helpers/debug_formatter`: provides functions to output debug information when running an external program +* :doc:`/components/console/helpers/cursor`: allows to manipulate the cursor in the terminal .. _`exit status`: https://en.wikipedia.org/wiki/Exit_status