clue/zenity-react

Zenity is a small program that allows creating simple GTK+ dialogs from within command line scripts. This library provides an easy to use wrapper to spawn Zenity processes to build graphical desktop applications with PHP.

Zenity already ships with Ubuntu-based distributions and does not require any installation there - so this library should work out of the box. Otherwise you may have to install Zenity yourself.

Quickstart example

Once installed, you can use the following code to open a prompt asking the user for his name and presenting it in another info dialog.

$loop = Factory::create();
$launcher = new Launcher($loop);

$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 folder.

Usage

Launcher

As shown in the above example, a Launcher has to be instantiated once and is responsible for launching each Zenity dialog. It manages running the underlying zenity process and reports back its state and user interaction.

It uses the react/event-loop component to enable an async workflow where you can launch multiple dialogs while simultaneously doing more I/O work. This library exposes both a simple blocking API and a more advanced async API.

$loop = React\EventLoop\Factory::create();
$launcher = new Launcher($loop);

setBin()

For launching the process it assumes your zenity binary is located in your system $PATH. If it's not, you can explicitly set its path like this:

$launcher->setBin('/some/other/path/zenity');

waitFor()

The waitFor($dialog) method can be used to launch a given dialog and wait for the Zenity process to return its result. This simple blocking API allows you to get started quickly without exposing all nifty async details - and lacking some of its advanced features:

$result = $launcher->waitFor($dialog);

launch()

The launch($dialog) method can be used to asynchronously launch a given dialog and return a Promise that will be fulfilled when the Zenity process returns. This async API enables you to launch multiple dialogs simultaneously while simultaneously doing more I/O work.

$launcher->launch($dialog)->then(
    function ($result) {
        // info dialogs complete with a boolean true result
        // text dialogs complete with their respective text
    },
    function ($reason) {
        // dialog was cancelled or there was an error launching the process
    }
});

launchZen()

The launchZen($dialog) method can be used to asynchronously launch a given dialog and return an instance of the BaseZen class. This instance exposes methods to control the Zenity process while waiting for the results. Some dialog types also support modifying the information presented to the user.

$zen = $launcher->launchZen($dialog);
$loop->addTimer(3.0, function () use ($zen) {
    $zen->close();
});

$zen->promise()->then(function ($result) {
    // dialog completed
});

Mixing synchronous and asynchronous PHP

ReactPHP expects all PHP to be non-blocking. Therefore it's not easily possible to use launch or launchZen followed by regular blocking events in PHP. Currently there is a simple but dirty workaround. It's possible to manually tick the loop to have changes on zen-objects take effect.

$progress = new ProgressDialog('Step 1');
$progress->setPulsate(TRUE);
$progress->setAutoClose(TRUE);
$progress_zen = $launcher->launchZen($progress);

// This regular command is blocking and breaks the asynchronous workflow
$hostname = gethostname();

$progress_zen->setText('Step 2');
$loop->tick();

// SQL is also regular blocking PHP
$get_sync = $db_serv->prepare('SELECT last_sync FROM tbl_sync WHERE hostname=?');
$get_sync->execute(array($hostname));
$result_sync = $get_sync->fetch();

Builder

Additionally, the Builder implements an even simpler interface for commonly used dialogs. This is mostly for convenience, so you can get started easier. The methods should be fairly self-explanatory and map directly to the Zenity dialogs listed below.

$builder = new Builder();
$dialog = $builder->info('Hello world');

For anything more complex, you can also instantiate the below classes directly.

Dialog

The Dialog API is modelled closely after Zenity's command line API, so it should be familar if you're already using it from within any other command line script.

AbstractDialog

Abstract base class for all Zenity dialogs (see below for details on each concrete type).

CalendarDialog

ColorSelectionDialog

EntryDialog

$builder->entry($prompt = null, $prefill = null);

ErrorDialog

$builder->error($text, $title = null);

FileSelectionDialog

$builder->fileSelection($title = null, $multiple = false);
$builder->fileSave($title = null, $previous = null);
$builder->directorySelection($title = null, $multiple = false);

FormsDialog

InfoDialog

$builder->info($text, $title = null);

ListDialog

$builder->listCheck(array $list, $text = null, $selected = null);
$builder->listMenu(array $list, $text = null);
$builder->listRadio(array $list, $text = null, $selected = null);
$builder->table(array $rows, array $columns = null, $text = null);

Where $selected is the key of the item from $list you want to preselect.

NotificationDialog

$builder->notification($text);
$builder->notifier();

PasswordDialog

ProgressDialog

$builder->progress($text = null);
$builder->pulsate($text = null);

QuestionDialog

$builder->question($question, $title = null);

ScaleDialog

TextInfoDialog

$builder->text($filename, $title = null);
$builder->editable($filename, $title = null);
$builder->confirmLicense($filename, $confirmation, $title = null);

WarningDialog

$builder->warning($text, $title = null);

Install

The recommended way to install this library is through composer. New to composer?

{
    "require": {
        "clue/zenity-react": "~0.4.0"
    }
}

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:

# usually not required
$ sudo apt-get install zenity

Otherwise you may have to install Zenity yourself (use your favorite search engine, download the appropriate realease tarball or compile from soure). Zenity it not officially supported on other platforms, however several non-official releases exist.

This library assumes Zenity is installed in your PATH. If it is not, you can explicitly set its path like this:

$launcher = new Launcher($loop);
$launcher->setBin('/path/to/zenity');

License

MIT