Merge pull request #25 from clue-labs/text-dialog

Add abstract base for all textual dialogs + simple ctor

README.md

@@ -15,16 +15,18 @@ 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
-
 $loop = Factory::create();
-
 $launcher = new Launcher($loop);
-$builder = new Builder($launcher);
 
-$builder->entry('What\'s your name?', getenv('USER'))->then(function ($name) use ($builder) {
-    $builder->info('Welcome to zenity-react, ' . $name .'!')->run();
+$entry = new EntryDialog();
+$entry->setText('What\'s your name?');
+$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 .'!'));
 });
 
+$loop->run();
 ```
 
 Looking for more examples? Take a look at the [examples](examples) folder.
@@ -37,8 +39,8 @@ familar if you're already using it from within any other command line script.
 ### Launcher
 
 As shown in the above example, a `Launcher` has to be instantiated once and
-will be passed as a dependency to each `Zenity` dialog. It manages running
-the underlying `zenity` process and its dependencies.
+is response for launching each zenity dialog. It manages running
+the underlying `zenity` process and reports back its state and user interaction.
 
 Therefor it assumes your `zenity` binary is located in your system `$PATH`.
 If it's not, you can explicitly set its path via

examples/blocking.php

@@ -3,6 +3,7 @@
 use React\EventLoop\Factory;
 use Clue\React\Zenity\Launcher;
 use Clue\React\Zenity\Builder;
+use Clue\React\Zenity\Dialog\EntryDialog;
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -11,7 +12,7 @@
 $launcher = new Launcher($loop);
 $builder = new Builder();
 
-$name = $launcher->waitFor($builder->entry('Search package'));
+$name = $launcher->waitFor(new EntryDialog('Search package'));
 if ($name === false) {
     exit;
 }

examples/dialog.php

@@ -2,25 +2,32 @@
 
 use React\EventLoop\Factory;
 use Clue\React\Zenity\Launcher;
-use Clue\React\Zenity\Builder;
+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';
 
 $loop = Factory::create();
 
 $launcher = new Launcher($loop);
-$builder = new Builder();
 
-$launcher->launch($builder->entry('What\'s your name?', getenv('USER'))->setTitle('Enter your name'))->then(function ($name) use ($builder, $launcher) {
-    $launcher->launch($builder->info('Welcome to the introduction of zenity, ' . $name))->then(function () use ($builder, $launcher) {
-        $launcher->launch($builder->question('Do you want to quit?'))->then(function () use ($builder, $launcher) {
-            $launcher->launch($builder->error('Oh noes!'));
-        }, function() use ($builder, $launcher) {
-            $launcher->launch($builder->warning('You should have selected yes!'));
+$q = new 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!'));
+        }, function() use ($launcher) {
+            $launcher->launch(new WarningDialog('You should have selected yes!'));
         });
     });
-}, function () use ($builder, $launcher) {
-    $launcher->launch($builder->warning('No name given'));
+}, function () use ($launcher) {
+    $launcher->launch(new WarningDialog('No name given'));
 });
 
 $loop->run();

examples/file.php

@@ -4,6 +4,7 @@
 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';
 
@@ -12,10 +13,10 @@
 $launcher = new Launcher($loop);
 $builder = new Builder();
 
-$launcher->launch($builder->fileSelection())->then(function (SplFileInfo $file) use ($builder, $launcher) {
+$launcher->launch($builder->fileSelection())->then(function (SplFileInfo $file) use ($launcher) {
     var_dump($file);
 
-    $launcher->launch($builder->info('Selected "' . $file->getFilename() . '". Re-opening dialog with same selection'))->then(function () use ($file, $launcher) {
+    $launcher->launch(new InfoDialog('Selected "' . $file->getFilename() . '". Re-opening dialog with same selection'))->then(function () use ($file, $launcher) {
         $selection = new FileSelectionDialog();
         $selection->setFilename($file);
         $selection->setTitle('Pretend we\'re overwriting the file');

examples/menu.php

@@ -3,6 +3,7 @@
 use React\EventLoop\Factory;
 use Clue\React\Zenity\Launcher;
 use Clue\React\Zenity\Builder;
+use Clue\React\Zenity\Dialog\InfoDialog;
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -19,16 +20,16 @@
    $launcher->launch($menu)->then(function ($selected) use ($builder, $main, $launcher) {
         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, $builder, $launcher) {
-                $launcher->launch($builder->info('Level ' . var_export($level, true)))->then($main, $main);
+            $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);
             }, $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, $builder, $launcher) {
-                $launcher->launch($builder->info('Tests: ' . var_export($tests, true)))->then($main, $main);
+            $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);
             }, $main);
         } elseif ($selected === '2') {
-            $launcher->launch($builder->confirmLicense(__DIR__ . '/../README.md', 'I have read the README.md file'))->then(function ($checked) use ($main, $builder, $launcher) {
-                $launcher->launch($builder->info('Clicked ' . var_export($checked, true)))->then($main, $main);
+            $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);
             }, $main);
         } elseif ($selected === '3') {
             $launcher->launch($builder->table(
@@ -46,7 +47,7 @@
                 $pulser->then($main, $main);
             }, $main);
         } else {
-            $launcher->launch($builder->info('Selected ' . var_export($selected, true)))->then($main, $main);
+            $launcher->launch(new InfoDialog('Selected ' . var_export($selected, true)))->then($main, $main);
         }
     });
 };

examples/progress.php

@@ -3,6 +3,7 @@
 use React\EventLoop\Factory;
 use Clue\React\Zenity\Launcher;
 use Clue\React\Zenity\Builder;
+use Clue\React\Zenity\Dialog\InfoDialog;
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -35,7 +36,7 @@
     $pulsate->complete();
 });
 
-$launcher->launch($builder->info('Quit "Processing"?'))->then(function () use ($pulsate) {
+$launcher->launch(new InfoDialog('Quit "Processing"?'))->then(function () use ($pulsate) {
     $pulsate->close();
 });
 

src/Dialog/AbstractMessageDialog.php

@@ -8,23 +8,13 @@
  * Abstract base for message dialogs: Error, Info, Question, Warning
  *
  * For each type, use the --text option to specify the text that is displayed in the dialog.
+ * The text is the main information presented to the user.
+ *
+ * Also inherits all properties and options from common AbstractMessageDialog
+ * and AbstractDialog base classes.
  *
  * @link https://help.gnome.org/users/zenity/stable/message.html
  */
-abstract class AbstractMessageDialog extends AbstractDialog
+abstract class AbstractMessageDialog extends AbstractTextDialog
 {
-    protected $text;
-
-    /**
-     * Specifies the text that is displayed in the dialog.
-     *
-     * @param string $text
-     * @return self chainable
-     */
-    public function setText($text)
-    {
-        $this->text = $text;
-
-        return $this;
-    }
 }

src/Dialog/AbstractTextDialog.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Clue\React\Zenity\Dialog;
+
+use Clue\React\Zenity\Dialog\AbstractDialog;
+
+/**
+ * Abstract base class for all dialogs that support passing a text.
+ *
+ * For each type, use the --text option to specify the text that is displayed in the dialog.
+ * The text is commonly printed as the main (or first) information in the dialog.
+ *
+ * Also inherits all properties and options from common AbstractDialog base.
+ *
+ * @see AbstractDialog
+ */
+abstract class AbstractTextDialog extends AbstractDialog
+{
+    protected $text;
+
+    /**
+     * Construct new text dialog
+     *
+     * Passing a $text is optional. Most dialog types define a default text
+     * as a fallback. Some dialog types leave out the text if non is passed.
+     *
+     * @param string|null $text (optional) main text displayed in the dialog.
+     */
+    public function __construct($text = null)
+    {
+        $this->text = $text;
+    }
+
+    /**
+     * Specifies the text that is displayed in the dialog.
+     *
+     * @param string $text
+     * @return self chainable
+     */
+    public function setText($text)
+    {
+        $this->text = $text;
+
+        return $this;
+    }
+}

src/Dialog/CalendarDialog.php

@@ -2,25 +2,17 @@
 
 namespace Clue\React\Zenity\Dialog;
 
-use Clue\React\Zenity\Dialog\AbstractDialog;
+use Clue\React\Zenity\Dialog\AbstractTextDialog;
 
-class CalendarDialog extends AbstractDialog
+class CalendarDialog extends AbstractTextDialog
 {
-    protected $text;
     protected $year;
     protected $month;
     protected $day;
 
     // no setter:
     protected $dateFormat = '%Y-%m-%d';
 
-    public function setText($text)
-    {
-        $this->text = $text;
-
-        return $this;
-    }
-
     public function setYear($year)
     {
         $this->year = $year;

src/Dialog/EntryDialog.php

@@ -2,21 +2,13 @@
 
 namespace Clue\React\Zenity\Dialog;
 
-use Clue\React\Zenity\Dialog\AbstractDialog;
+use Clue\React\Zenity\Dialog\AbstractTextDialog;
 
-class EntryDialog extends AbstractDialog
+class EntryDialog extends AbstractTextDialog
 {
-    protected $text;
     protected $entryText;
     protected $hideText = false;
 
-    public function setText($text)
-    {
-        $this->text = $text;
-
-        return $this;
-    }
-
     public function setEntryText($text)
     {
         $this->entryText = $text;

src/Dialog/FormsDialog.php

@@ -2,25 +2,17 @@
 
 namespace Clue\React\Zenity\Dialog;
 
-use Clue\React\Zenity\Dialog\AbstractDialog;
+use Clue\React\Zenity\Dialog\AbstractTextDialog;
 
-class FormsDialog extends AbstractDialog
+
+class FormsDialog extends AbstractTextDialog
 {
     protected $fields = array();
 
-    protected $text;
-
     // no setter:
     protected $formsDateFormat = '%Y-%m-%d';
     protected $separator = '|||';
 
-    public function setText($text)
-    {
-        $this->text = $text;
-
-        return $this;
-    }
-
     public function addEntry($name)
     {
         $this->fields[] = '--add-entry=' . $name;

src/Dialog/ListDialog.php

@@ -2,11 +2,10 @@
 
 namespace Clue\React\Zenity\Dialog;
 
-use Clue\React\Zenity\Dialog\AbstractDialog;
+use Clue\React\Zenity\Dialog\AbstractTextDialog;
 
-class ListDialog extends AbstractDialog
+class ListDialog extends AbstractTextDialog
 {
-    protected $text;
     protected $checklist = false;
     protected $radiolist = false;
     protected $imagelist = false;
@@ -32,13 +31,6 @@ public function addColumn($column, $hide = false)
         return $this;
     }
 
-    public function setText($text)
-    {
-        $this->text = $text;
-
-        return $this;
-    }
-
     public function setChecklist($check)
     {
         $this->checklist = !!$check;

src/Dialog/NotificationDialog.php

@@ -2,20 +2,12 @@
 
 namespace Clue\React\Zenity\Dialog;
 
-use Clue\React\Zenity\Dialog\AbstractDialog;
+use Clue\React\Zenity\Dialog\AbstractTextDialog;
 
-class NotificationDialog extends AbstractDialog
+class NotificationDialog extends AbstractTextDialog
 {
-    protected $text;
     protected $listen = false;
 
-    public function setText($text)
-    {
-        $this->text = $text;
-
-        return $this;
-    }
-
     public function setListen($listen)
     {
         $this->listen = !!$listen;