Improve documentation and examples

clue · Feb 6, 2024 · 28ca26e · 28ca26e
1 parent e377ce1
commit 28ca26e
Show file tree

Hide file tree

Showing 9 changed files with 59 additions and 66 deletions.
diff --git 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
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
 $launcher = new Clue\React\Zenity\Launcher();
 
 $entry = new EntryDialog();
@@ -69,10 +73,12 @@ $entry->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,29 +300,29 @@ $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.
 
 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.
 On Debian- and Ubuntu-based distributions you can make sure it's installed like this:
 
 ```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
@@ -1,28 +1,23 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Dialog\InfoDialog;
-use Clue\React\Zenity\Dialog\QuestionDialog;
-use Clue\React\Zenity\Dialog\ErrorDialog;
-use Clue\React\Zenity\Dialog\EntryDialog;
-use Clue\React\Zenity\Dialog\WarningDialog;
-
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
+$launcher = new Clue\React\Zenity\Launcher();
 
-$q = new EntryDialog('What\'s your name?');
+$q = new Clue\React\Zenity\Dialog\EntryDialog('What\'s your name?');
 $q->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
@@ -1,25 +1,24 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Dialog\FileSelectionDialog;
-use Clue\React\Zenity\Builder;
-use Clue\React\Zenity\Dialog\InfoDialog;
-
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
-$builder = new Builder();
+$launcher = new Clue\React\Zenity\Launcher();
+$builder = new Clue\React\Zenity\Builder();
 
 $launcher->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
@@ -1,13 +1,11 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Builder;
 use React\EventLoop\Loop;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
-$builder = new Builder();
+$launcher = new Clue\React\Zenity\Launcher();
+$builder = new Clue\React\Zenity\Builder();
 
 $progress = $launcher->launchZen($builder->pulsate('Pseudo-processing...'));
 
@@ -39,10 +37,14 @@
     $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) {
     $timer->cancel();
 
     $launcher->launch($builder->error('Canceled'));
+}, function (Exception $e) {
+    echo 'Error: ' . $e->getMessage() . PHP_EOL;
 });
diff --git a/examples/04-progress-random.php b/examples/04-progress-random.php
@@ -1,13 +1,11 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Builder;
 use React\EventLoop\Loop;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
-$builder = new Builder();
+$launcher = new Clue\React\Zenity\Launcher();
+$builder = new Clue\React\Zenity\Builder();
 
 $progress = $launcher->launchZen($builder->progress('Pseudo-processing...'));
 

diff --git a/examples/05-form.php b/examples/05-form.php
@@ -1,13 +1,10 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Dialog\FormsDialog;
-
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
+$launcher = new Clue\React\Zenity\Launcher();
 
-$form = new FormsDialog();
+$form = new Clue\React\Zenity\Dialog\FormsDialog();
 $form->setWindowIcon('info');
 $form->setText('Enter user information');
 
@@ -22,4 +19,6 @@
     var_dump('result', $result);
 }, function() {
     var_dump('form canceled');
+}, function (Exception $e) {
+    echo 'Error: ' . $e->getMessage() . PHP_EOL;
 });
diff --git a/examples/06-menu.php b/examples/06-menu.php
@@ -1,13 +1,9 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Builder;
-use Clue\React\Zenity\Dialog\InfoDialog;
-
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
-$builder = new Builder();
+$launcher = new Clue\React\Zenity\Launcher();
+$builder = new Clue\React\Zenity\Builder();
 
 $main = function() use (&$main, $builder, $launcher) {
     $menu = $builder->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
@@ -1,13 +1,11 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Builder;
 use React\EventLoop\Loop;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
-$builder = new Builder();
+$launcher = new Clue\React\Zenity\Launcher();
+$builder = new Clue\React\Zenity\Builder();
 
 $notification = $builder->notifier();
 $zen = $launcher->launchZen($notification);

diff --git a/examples/20-blocking.php b/examples/20-blocking.php
@@ -1,15 +1,11 @@
 <?php
 
-use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Builder;
-use Clue\React\Zenity\Dialog\EntryDialog;
-
 require __DIR__ . '/../vendor/autoload.php';
 
-$launcher = new Launcher();
-$builder = new Builder();
+$launcher = new Clue\React\Zenity\Launcher();
+$builder = new Clue\React\Zenity\Builder();
 
-$name = $launcher->waitFor(new EntryDialog('Search package'));
+$name = $launcher->waitFor(new Clue\React\Zenity\Dialog\EntryDialog('Search package'));
 if ($name === false) {
     exit;
 }