Signatur
Beschreibung
UI\Controls\Combo ist ein grafisches Steuerelement (Control) aus der PHP-UI-Erweiterung (ui), das dem Benutzer eine Dropdown-Liste mit vordefinierten Optionen präsentiert. Der Benutzer kann genau eine Option aus der Liste auswählen. Dies entspricht dem Verhalten des HTML-Elements <select> ohne das Attribut multiple.
Das Control wird innerhalb eines Fensters (UI\Window) oder eines anderen Container-Controls eingebettet. Optionen werden mit der Methode append() zur Liste hinzugefügt. Über getSelected() und setSelected() lässt sich der aktuell gewählte Index lesen und setzen.
Mit der Methode onChange() kann ein Callback registriert werden, der automatisch ausgeführt wird, sobald der Benutzer eine andere Option auswählt. So lassen sich reaktive Benutzeroberflächen bauen, die auf Auswahländerungen sofort reagieren.
Die Klasse ist Teil der experimentellen ui-Erweiterung (libui-Binding für PHP) und eignet sich für plattformübergreifende Desktop-GUI-Anwendungen, die mit PHP entwickelt werden.
Beispiele
Einfache Dropdown-Liste mit Änderungs-Callback
<?php
use UI\Window;
use UI\Controls\Combo;
use UI\Controls\Box;
use UI\Controls\Label;
use UI\Point;
use UI\Size;
$window = new Window('Combo-Beispiel', new Size(300, 150), false);
$window->setMargin(true);
$box = new Box(Box::Vertical);
$box->setPadded(true);
$label = new Label('Bitte wählen:');
$box->append($label);
$combo = new Combo();
$combo->append('Option A');
$combo->append('Option B');
$combo->append('Option C');
$combo->setSelected(0); // Erste Option vorauswählen
$combo->onChange(function (Combo $combo) use ($label) {
$index = $combo->getSelected();
$label->setText('Ausgewählt: Index ' . $index);
});
$box->append($combo);
$window->add($box);
$window->show();
UI\run();
Programmatische Auswahl und Auslesen des gewählten Index
<?php
use UI\Controls\Combo;
$combo = new Combo();
$combo->append('Rot');
$combo->append('Grün');
$combo->append('Blau');
// Zweiten Eintrag ('Grün') vorauswählen
$combo->setSelected(1);
$selected = $combo->getSelected();
echo 'Aktuell ausgewählter Index: ' . $selected; // 1
// Wichtig · Fallstricke
Experimentell: Die ui-Erweiterung gilt als experimentell und ist nicht im Standard-PHP-Paket enthalten. Sie muss separat über PECL installiert werden (pecl install ui). Die API kann sich zwischen Versionen ändern.
Nicht zu verwechseln mit UI\Controls\EditableCombo, das zusätzlich eine freie Texteingabe erlaubt. UI\Controls\Combo beschränkt die Auswahl ausschließlich auf die vordefinierten Einträge.
Der Index bei getSelected() gibt -1 zurück, wenn keine Option ausgewählt ist. Dies sollte vor der Verarbeitung geprüft werden, um Fehler zu vermeiden.