From f7023cf38f58bcc8e262207370dba3dba63bd4cc Mon Sep 17 00:00:00 2001 From: Yada Clintjens Date: Tue, 30 Jan 2024 12:09:25 +0100 Subject: [PATCH] Improve documentation and examples --- README.md | 26 +++++++++++++++++--------- examples/01-dialog.php | 23 +++++++++-------------- examples/02-file.php | 17 ++++++++--------- examples/03-progress-pulsate.php | 8 ++++---- examples/04-progress-random.php | 6 ++---- examples/05-form.php | 7 ++----- examples/06-menu.php | 18 ++++++++---------- examples/10-notification.php | 6 ++---- examples/20-blocking.php | 10 +++------- 9 files changed, 55 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 3b95209..2624197 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # clue/reactphp-zenity -[![CI status](https://github.com/clue/reactphp-zenity/workflows/CI/badge.svg)](https://github.com/clue/reactphp-zenity/actions) +[![CI status](https://github.com/clue/reactphp-zenity/actions/workflows/ci.yml/badge.svg)](https://github.com/clue/reactphp-zenity/actions) [![installs on Packagist](https://img.shields.io/packagist/dt/clue/zenity-react?color=blue&label=installs%20on%20Packagist)](https://packagist.org/packages/clue/zenity-react) Zenity allows you to build graphical desktop (GUI) applications in PHP, built on top of [ReactPHP](https://reactphp.org/). @@ -61,6 +61,10 @@ Once [installed](#install), you can use the following code to open a prompt asking the user for his name and presenting it in another info dialog. ```php +setEntryText(getenv('USER')); // prefill with current user $launcher->launch($entry)->then(function ($name) use ($launcher) { $launcher->launch(new InfoDialog('Welcome to zenity-react, ' . $name .'!')); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); ``` -Looking for more examples? Take a look at the [examples](examples) folder. +Looking for more examples? Take a look at the [examples](examples/) folder. ## Usage @@ -152,6 +158,8 @@ Loop::addTimer(3.0, function () use ($zen) { $zen->promise()->then(function ($result) { // dialog completed +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); ``` @@ -292,13 +300,13 @@ $builder->warning($text, $title = null); ## Install -The recommended way to install this library is [through Composer](https://getcomposer.org). +The recommended way to install this library is [through Composer](https://getcomposer.org/). [New to Composer?](https://getcomposer.org/doc/00-intro.md) This will install the latest supported version: ```bash -$ composer require clue/zenity-react:^0.4.4 +composer require clue/zenity-react:^0.4.4 ``` See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. @@ -306,7 +314,7 @@ See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM. -It's *highly recommended to use PHP 7+* for this project. +It's *highly recommended to use the latest supported PHP version* for this project. Obviously, this library requires the Zenity binary itself. Zenity already ships with Ubuntu-based distributions and should not require any installation there. @@ -314,7 +322,7 @@ On Debian- and Ubuntu-based distributions you can make sure it's installed like ```bash # usually not required -$ sudo apt-get install zenity +sudo apt-get install zenity ``` Otherwise you may have to install Zenity yourself (use your favorite search engine, download the appropriate release tarball or compile from source). @@ -332,16 +340,16 @@ $launcher->setBin('/path/to/zenity'); ## Tests To run the test suite, you first need to clone this repo and then install all -dependencies [through Composer](https://getcomposer.org): +dependencies [through Composer](https://getcomposer.org/): ```bash -$ composer install +composer install ``` To run the test suite, go to the project root and run: ```bash -$ php vendor/bin/phpunit +vendor/bin/phpunit ``` ## License diff --git a/examples/01-dialog.php b/examples/01-dialog.php index 8d1bd69..ed6aa82 100644 --- a/examples/01-dialog.php +++ b/examples/01-dialog.php @@ -1,28 +1,23 @@ setEntryText(getenv('USER')); $q->setTitle('Enter your name'); $launcher->launch($q)->then(function ($name) use ($launcher) { - $launcher->launch(new InfoDialog('Welcome to the introduction of zenity, ' . $name))->then(function () use ($launcher) { - $launcher->launch(new QuestionDialog('Do you want to quit?'))->then(function () use ($launcher) { - $launcher->launch(new ErrorDialog('Oh noes!')); + $launcher->launch(new Clue\React\Zenity\Dialog\InfoDialog('Welcome to the introduction of zenity, ' . $name))->then(function () use ($launcher) { + $launcher->launch(new Clue\React\Zenity\Dialog\QuestionDialog('Do you want to quit?'))->then(function () use ($launcher) { + $launcher->launch(new Clue\React\Zenity\Dialog\ErrorDialog('Oh noes!')); }, function() use ($launcher) { - $launcher->launch(new WarningDialog('You should have selected yes!')); + $launcher->launch(new Clue\React\Zenity\Dialog\WarningDialog('You should have selected yes!')); }); + }, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); }, function () use ($launcher) { - $launcher->launch(new WarningDialog('No name given')); + $launcher->launch(new Clue\React\Zenity\Dialog\WarningDialog('No name given')); }); diff --git a/examples/02-file.php b/examples/02-file.php index 23d2f4d..6cb0520 100644 --- a/examples/02-file.php +++ b/examples/02-file.php @@ -1,25 +1,24 @@ launch($builder->fileSelection())->then(function (SplFileInfo $file) use ($launcher) { var_dump($file); - $launcher->launch(new InfoDialog('Selected "' . $file->getFilename() . '". Re-opening dialog with same selection'))->then(function () use ($file, $launcher) { - $selection = new FileSelectionDialog(); + $launcher->launch(new Clue\React\Zenity\Dialog\InfoDialog('Selected "' . $file->getFilename() . '". Re-opening dialog with same selection'))->then(function () use ($file, $launcher) { + $selection = new Clue\React\Zenity\Dialog\FileSelectionDialog(); $selection->setFilename($file); $selection->setTitle('Pretend we\'re overwriting the file'); $selection->setConfirmOverwrite(true); $selection->setSave(true); $launcher->launch($selection); + }, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); diff --git a/examples/03-progress-pulsate.php b/examples/03-progress-pulsate.php index 9096f22..0293bc3 100644 --- a/examples/03-progress-pulsate.php +++ b/examples/03-progress-pulsate.php @@ -1,13 +1,11 @@ launchZen($builder->pulsate('Pseudo-processing...')); @@ -39,6 +37,8 @@ $timer->cancel(); $launcher->launch($builder->info('Done')); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); $progress->promise()->then(null, function() use ($timer, $builder, $launcher) { diff --git a/examples/04-progress-random.php b/examples/04-progress-random.php index c48fa2b..d6a9d4e 100644 --- a/examples/04-progress-random.php +++ b/examples/04-progress-random.php @@ -1,13 +1,11 @@ launchZen($builder->progress('Pseudo-processing...')); diff --git a/examples/05-form.php b/examples/05-form.php index 058cea5..03b0926 100644 --- a/examples/05-form.php +++ b/examples/05-form.php @@ -1,13 +1,10 @@ setWindowIcon('info'); $form->setText('Enter user information'); diff --git a/examples/06-menu.php b/examples/06-menu.php index 430692a..609760a 100644 --- a/examples/06-menu.php +++ b/examples/06-menu.php @@ -1,13 +1,9 @@ listMenu(array('Introduction', 'Tests', 'License', 'Bugs / Issues'), 'Main menu'); @@ -18,15 +14,15 @@ if ($selected === '0') { // U+2212 MINUS SIGN for alignment $launcher->launch($builder->listRadio(array('+2', '+1', '±0', '−1', '−2'), 'Introduction Level', 2))->then(function ($level) use ($main, $launcher) { - $launcher->launch(new InfoDialog('Level ' . var_export($level, true)))->then($main, $main); + $launcher->launch(new Clue\React\Zenity\Dialog\InfoDialog('Level ' . var_export($level, true)))->then($main, $main); }, $main); } elseif ($selected === '1') { $launcher->launch($builder->listCheck(array('Unit', 'Functional', 'Acceptance (slow)'), 'Selected test suits to run', array(0, 1)))->then(function ($tests) use ($main, $launcher) { - $launcher->launch(new InfoDialog('Tests: ' . var_export($tests, true)))->then($main, $main); + $launcher->launch(new Clue\React\Zenity\Dialog\InfoDialog('Tests: ' . var_export($tests, true)))->then($main, $main); }, $main); } elseif ($selected === '2') { $launcher->launch($builder->confirmLicense(__DIR__ . '/../README.md', 'I have read the README.md file'))->then(function ($checked) use ($main, $launcher) { - $launcher->launch(new InfoDialog('Clicked ' . var_export($checked, true)))->then($main, $main); + $launcher->launch(new Clue\React\Zenity\Dialog\InfoDialog('Clicked ' . var_export($checked, true)))->then($main, $main); }, $main); } elseif ($selected === '3') { $launcher->launch($builder->table( @@ -44,8 +40,10 @@ $pulser->then($main, $main); }, $main); } else { - $launcher->launch(new InfoDialog('Selected ' . var_export($selected, true)))->then($main, $main); + $launcher->launch(new Clue\React\Zenity\Dialog\InfoDialog('Selected ' . var_export($selected, true)))->then($main, $main); } + }, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); }; diff --git a/examples/10-notification.php b/examples/10-notification.php index 1ea288c..e3483b1 100644 --- a/examples/10-notification.php +++ b/examples/10-notification.php @@ -1,13 +1,11 @@ notifier(); $zen = $launcher->launchZen($notification); diff --git a/examples/20-blocking.php b/examples/20-blocking.php index d4a3b83..9161b87 100644 --- a/examples/20-blocking.php +++ b/examples/20-blocking.php @@ -1,15 +1,11 @@ waitFor(new EntryDialog('Search package')); +$name = $launcher->waitFor(new Clue\React\Zenity\Dialog\EntryDialog('Search package')); if ($name === false) { exit; }