Signatur
Beschreibung
UI\Draw\Pen ist das zentrale Zeichenwerkzeug der PHP-UI-Erweiterung (php-ui). Eine Instanz dieses Objekts wird automatisch als Parameter an den onDraw-Event-Handler einer UI\Area übergeben — sie kann nicht manuell instanziiert werden. Der Pen stellt Methoden bereit, um UI\Draw\Path-Objekte auf der Zeichenfläche zu rendern.
Mit dem Pen lassen sich drei grundlegende Zeichenoperationen auf einem UI\Draw\Path ausführen: Füllen (fill()) zeichnet den Pfad mit einer Füllfarbe, Zeichnen (stroke()) zeichnet die Kontur des Pfades anhand eines UI\Draw\Stroke-Objekts, und Transformieren (transform()) wendet eine affine Transformation auf alle folgenden Zeichenoperationen an.
Zusätzlich bietet der Pen die Methode clip(), um einen Pfad als Clipping-Region zu definieren, sodass alle nachfolgenden Zeichenoperationen auf diesen Bereich beschränkt bleiben. Mit save() und restore() kann der aktuelle Zustand des Pens (Transformationen, Clipping) gespeichert und wiederhergestellt werden, ähnlich wie beim HTML5-Canvas.
Der typische Einsatz erfolgt innerhalb eines anonymen Callbacks oder einer Methode, die als Draw-Handler registriert wurde. Alle Zeichenoperationen sind auf den Kontext eines einzelnen onDraw-Aufrufs beschränkt und sollten nicht außerhalb dieses Kontexts verwendet werden.
Beispiele
Rechteck füllen und Kontur zeichnen
<?php
use UI\Area;
use UI\Draw\Pen;
use UI\Draw\Path;
use UI\Draw\Color;
use UI\Draw\Stroke;
use UI\Draw\Line\Cap;
use UI\Draw\Line\Join;
use UI\Point;
use UI\Size;
use UI\Window;
$window = new Window('Pen Beispiel', new Size(400, 300), false);
$area = new class extends Area {
protected function onDraw(Pen $pen, Size $areaSize, Point $clipPoint, Size $clipSize): void
{
// Pfad erstellen und Rechteck hinzufügen
$path = new Path(Path::Winding);
$path->addRectangle(new Point(50, 50), new Size(200, 100));
$path->end();
// Pfad mit Blau füllen
$pen->fill($path, new Color(0x3399FF, 0.8));
// Kontur mit schwarzem Stroke zeichnen
$stroke = new Stroke(Cap::Flat, Join::Miter, 2, 10);
$pen->stroke($path, new Color(0x000000, 1.0), $stroke);
}
};
$window->add($area);
$window->show();
UI\run();Clipping-Region setzen und Zustand speichern/wiederherstellen
<?php
use UI\Area;
use UI\Draw\Pen;
use UI\Draw\Path;
use UI\Draw\Color;
use UI\Draw\Stroke;
use UI\Draw\Line\Cap;
use UI\Draw\Line\Join;
use UI\Point;
use UI\Size;
use UI\Window;
$window = new Window('Clipping Beispiel', new Size(400, 300), false);
$area = new class extends Area {
protected function onDraw(Pen $pen, Size $areaSize, Point $clipPoint, Size $clipSize): void
{
// Aktuellen Zustand sichern
$pen->save();
// Clipping-Region als Kreis definieren
$clipPath = new Path(Path::Winding);
$clipPath->newFigureWithArc(new Point(200, 150), 80, 0, 360, false);
$clipPath->end();
$pen->clip($clipPath);
// Hintergrund füllen — wird durch Clipping auf den Kreis begrenzt
$bgPath = new Path(Path::Winding);
$bgPath->addRectangle(new Point(0, 0), $areaSize);
$bgPath->end();
$pen->fill($bgPath, new Color(0xFF6600, 1.0));
// Zustand wiederherstellen (Clipping aufheben)
$pen->restore();
// Dieser Pfad wird NICHT geclipt
$stroke = new Stroke(Cap::Flat, Join::Miter, 1, 10);
$borderPath = new Path(Path::Winding);
$borderPath->addRectangle(new Point(10, 10), new Size(380, 280));
$borderPath->end();
$pen->stroke($borderPath, new Color(0x000000, 1.0), $stroke);
}
};
$window->add($area);
$window->show();
UI\run();// Wichtig · Fallstricke
Wichtig: UI\Draw\Pen kann nicht manuell mit new instanziiert werden. Die Instanz wird ausschließlich vom Framework als Parameter des onDraw-Callbacks erzeugt. Das Speichern der Referenz und die Verwendung außerhalb des Callbacks führt zu undefiniertem Verhalten.
Zustandsverwaltung: save() und restore() müssen immer paarweise aufgerufen werden. Nicht ausgeglichene Aufrufe können dazu führen, dass Clipping-Regionen und Transformationen unerwartet erhalten bleiben oder verlorengehen.
Die php-ui-Erweiterung befindet sich noch im experimentellen Stadium (PECL). Methoden und Signaturen können sich zwischen Versionen ändern.