ps_show_boxed — Funktion · PHP-Referenz

Signatur

ps_show_boxed(resource $psdoc, string $text, float $left, float $bottom, float $width, float $height, string $hmode, string $feature = ''): int

Beschreibung

ps_show_boxed ist Teil der PS-Erweiterung (pslib) für PHP und ermöglicht die Ausgabe von Fließtext innerhalb eines festgelegten rechteckigen Bereichs in einem PostScript-Dokument. Der Text wird dabei automatisch umgebrochen, sobald er die vorgegebene Breite überschreitet.

Der Parameter hmode steuert die horizontale Ausrichtung des Textes innerhalb des Rahmens. Mögliche Werte sind 'justify' (Blocksatz), 'fulljustify' (voller Blocksatz inkl. letzter Zeile), 'right' (rechtsbündig), 'center' (zentriert) und 'left' (linksbündig).

Die Funktion ist besonders nützlich, wenn größere Textmengen in definierten Layoutbereichen eines PostScript-Dokuments platziert werden sollen, z. B. für mehrspaltige Layouts, Beschriftungsfelder oder automatisch generierte Berichte.

Zu beachten ist, dass vor dem Aufruf eine Schriftart und -größe mittels ps_setfont gesetzt sein muss, damit der Text korrekt gerendert wird. Der Rückgabewert gibt die Anzahl der Zeichen an, die nicht in den Rahmen gepasst haben – also 0 bei vollständiger Ausgabe.

Parameter

Name	Typ	Beschreibung
$psdoc Pflicht	resource	Die Ressource des PostScript-Dokuments, wie sie von `ps_new()` zurückgegeben wird.
$text Pflicht	string	Der auszugebende Text. Zeilenumbrüche und Wortumbrüche werden anhand der Rahmenbreite automatisch berechnet.
$left Pflicht	float	Die X-Koordinate (in Punkten) der linken unteren Ecke des Textbereichs.
$bottom Pflicht	float	Die Y-Koordinate (in Punkten) der linken unteren Ecke des Textbereichs.
$width Pflicht	float	Die Breite des Textbereichs in Punkten.
$height Pflicht	float	Die Höhe des Textbereichs in Punkten.
$hmode Pflicht	string	Horizontale Ausrichtung des Textes. Mögliche Werte: `'left'`, `'right'`, `'center'`, `'justify'`, `'fulljustify'`.
$feature	string	Optionaler Zusatzparameter für erweiterte Funktionen. Wird in den meisten Fällen als leerer String übergeben.

Rückgabewert

Typ

int

Beschreibung

Gibt die Anzahl der Zeichen zurück, die nicht in den angegebenen Rahmen gepasst haben. Bei vollständiger Ausgabe des Textes wird 0 zurückgegeben. Ein Wert größer als 0 bedeutet, dass der Text abgeschnitten wurde.

Beispiele

Einfacher Text in einem Rahmen mit Blocksatz

<?php
$ps = ps_new();

if (!ps_open_file($ps, 'ausgabe.ps')) {
    die('Datei konnte nicht geöffnet werden.');
}

ps_begin_page($ps, 596, 842);

$fontHandle = ps_findfont($ps, 'Helvetica', '', 0);
ps_setfont($ps, $fontHandle, 12.0);

$text = 'Dies ist ein längerer Beispieltext, der automatisch in den '
      . 'angegebenen rechteckigen Bereich umgebrochen wird. '
      . 'ps_show_boxed übernimmt den Zeilenumbruch automatisch.';

$uebrig = ps_show_boxed($ps, $text, 50, 600, 400, 200, 'justify');

if ($uebrig > 0) {
    echo "$uebrig Zeichen konnten nicht dargestellt werden.";
} else {
    echo 'Text vollständig ausgegeben.';
}

ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
?>

Text vollständig ausgegeben.

Zentrierter Text mit Überlaufprüfung

<?php
$ps = ps_new();
ps_open_file($ps, 'zentriert.ps');

ps_begin_page($ps, 596, 842);

$font = ps_findfont($ps, 'Times-Roman', '', 0);
ps_setfont($ps, $font, 14.0);

$langtext = str_repeat('Sehr langer Text für ein kleines Feld. ', 20);

// Kleiner Rahmen: Überlauf wahrscheinlich
$rest = ps_show_boxed($ps, $langtext, 100, 500, 150, 80, 'center');

echo "Nicht dargestellte Zeichen: $rest";

ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
?>

Nicht dargestellte Zeichen: 412

// Wichtig · Fallstricke

Voraussetzung: Die PHP-Erweiterung ps (pslib) muss installiert und aktiviert sein. Sie ist nicht standardmäßig in PHP enthalten und muss separat kompiliert bzw. installiert werden.

Vor dem Aufruf von ps_show_boxed muss zwingend eine Schriftart mit ps_setfont() gesetzt werden, sonst schlägt die Ausgabe fehl.

Koordinaten in PostScript-Dokumenten werden in Punkten (1 Punkt = 1/72 Zoll) angegeben. Der Ursprung (0, 0) liegt in der unteren linken Ecke der Seite – anders als in vielen anderen Grafiksystemen.

Die Funktion berücksichtigt keine HTML-Auszeichnungen – der übergebene Text wird als reiner Klartext behandelt.

Siehe auch

ps_show ps_setfont ps_findfont ps_begin_page ps_new