Signatur
Beschreibung
UI\Controls\Progress ist ein grafisches Steuerelement der PHP-UI-Erweiterung (ui/libui), das einen klassischen Fortschrittsbalken repräsentiert. Der angezeigte Prozentwert liegt dabei immer im Bereich von 0 (leer) bis 100 (vollständig gefüllt).
Die Klasse wird typischerweise in Desktop-Anwendungen eingesetzt, die mit der UI-Erweiterung gebaut werden, etwa um Dateiübertragungen, Berechnungen oder andere zeitintensive Prozesse visuell zu begleiten. Sie erbt von UI\Control und kann wie jedes andere Steuerelement in Layouts eingefügt werden.
Der Fortschrittsbalken kann über die Methoden setValue() und getValue() gesteuert und ausgelesen werden. Ein Wert von -1 versetzt den Balken in einen unbestimmten Modus (indeterminate mode), bei dem eine animierte, nicht quantifizierte Aktivität angezeigt wird – nützlich, wenn der Gesamtfortschritt unbekannt ist.
- Wert 0–100: bestimmter Fortschritt in Prozent
- Wert -1: unbestimmter Modus (animierter Balken ohne Prozentanzeige)
Beispiele
Einfacher Fortschrittsbalken in einem UI-Fenster
<?php
use UI\Window;
use UI\Controls\Progress;
use UI\Controls\Box;
use UI\Point;
use UI\Size;
$window = new Window('Fortschritt', new Size(300, 80), false);
$box = new Box(Box::Vertical);
$box->setPadded(true);
$progress = new Progress();
$progress->setValue(65); // 65 % Fortschritt anzeigen
$box->append($progress, true);
$window->setChild($box);
$window->show();
UI\run();Unbestimmter Modus (indeterminate) und dynamische Aktualisierung
<?php
use UI\Window;
use UI\Controls\Progress;
use UI\Controls\Box;
use UI\Controls\Button;
use UI\Size;
$window = new Window('Ladevorgang', new Size(320, 120), false);
$box = new Box(Box::Vertical);
$box->setPadded(true);
$progress = new Progress();
$progress->setValue(-1); // Unbestimmter Modus: Animation ohne Prozentwert
$button = new Button('Auf 50 % setzen');
$button->on(Button::Click, function () use ($progress) {
$progress->setValue(50);
});
$box->append($progress, false);
$box->append($button, false);
$window->setChild($box);
$window->show();
UI\run();
// Aktuellen Wert auslesen
$current = $progress->getValue();
echo 'Aktueller Wert: ' . $current; // z. B. 50// Wichtig · Fallstricke
Hinweis zur Erweiterung: UI\Controls\Progress ist Teil der experimentellen UI-PECL-Erweiterung (basierend auf libui) und nicht standardmäßig in PHP enthalten. Die Erweiterung muss separat installiert werden. Da sie als experimentell gilt, können sich API und Verhalten zwischen Versionen ändern.
Der erlaubte Wertebereich für setValue() ist -1 bis 100. Werte außerhalb dieses Bereichs führen zu undefiniertem Verhalten oder werden ignoriert. Stellen Sie sicher, dass Eingabewerte immer geprüft werden, bevor sie übergeben werden.
Ein Wert von -1 aktiviert den indeterminate mode (unbestimmter Modus), der auf manchen Plattformen als animierter, pulsirender Balken dargestellt wird – dies ist plattformabhängig.