ps_add_note — Funktion · PHP-Referenz

Signatur

ps_add_note(resource $psdoc, float $llx, float $lly, float $urx, float $ury, string $contents, string $title, string $icon, int $open): bool

Beschreibung

ps_add_note() ist Teil der ps-Erweiterung (pslib) und erlaubt es, einer Seite eines PostScript-Dokuments eine kommentarartige Notiz (Annotation) hinzuzufügen. Diese Notizen sind vergleichbar mit Haftnotizen in PDF-Dokumenten und können beim Betrachten interaktiv geöffnet oder geschlossen werden.

Die Position der Notiz wird über zwei Koordinatenpaare definiert: llx/lly für die untere linke Ecke und urx/ury für die obere rechte Ecke des Notiz-Rechtecks auf der Seite. Die Koordinaten beziehen sich auf das PostScript-Koordinatensystem, bei dem der Ursprung (0,0) in der linken unteren Ecke liegt.

Der Parameter icon bestimmt das visuelle Symbol der Notiz. Mögliche Werte sind unter anderem "Note", "Comment", "Help", "NewParagraph", "Paragraph", "Insert" und "Key". Mit dem Parameter open lässt sich steuern, ob die Notiz standardmäßig geöffnet angezeigt wird.

Diese Funktion ist besonders nützlich, wenn PostScript-Dokumente mit redaktionellen Anmerkungen, Überarbeitungshinweisen oder erklärenden Kommentaren versehen werden sollen, die im Viewer interaktiv zugänglich sind.

Parameter

Name	Typ	Beschreibung
$psdoc Pflicht	resource	Die Ressource des PostScript-Dokuments, wie sie von `ps_new()` zurückgegeben wird.
$llx Pflicht	float	X-Koordinate der unteren linken Ecke des Notiz-Rechtecks in PostScript-Einheiten (Punkte).
$lly Pflicht	float	Y-Koordinate der unteren linken Ecke des Notiz-Rechtecks in PostScript-Einheiten (Punkte).
$urx Pflicht	float	X-Koordinate der oberen rechten Ecke des Notiz-Rechtecks in PostScript-Einheiten (Punkte).
$ury Pflicht	float	Y-Koordinate der oberen rechten Ecke des Notiz-Rechtecks in PostScript-Einheiten (Punkte).
$contents Pflicht	string	Der eigentliche Text der Notiz, der dem Betrachter angezeigt wird, wenn die Annotation geöffnet wird.
$title Pflicht	string	Der Titel der Notiz-Annotation, der in der Titelzeile des Notiz-Fensters erscheint.
$icon Pflicht	string	Name des Icons, das die Notiz repräsentiert. Gültige Werte sind z. B. `"Note"`, `"Comment"`, `"Help"`, `"NewParagraph"`, `"Paragraph"`, `"Insert"` und `"Key"`.
$open Pflicht	int	Gibt an, ob die Notiz standardmäßig geöffnet (`1`) oder geschlossen (`0`) dargestellt wird.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, oder false, wenn ein Fehler aufgetreten ist, beispielsweise wenn keine Seite geöffnet ist oder die Ressource ungültig ist.

Beispiele

Einfache Notiz auf einer PostScript-Seite hinzufügen

<?php
// PostScript-Dokument erstellen
$ps = ps_new();

if (!$ps) {
    die('Konnte PostScript-Ressource nicht erstellen.');
}

ps_open_file($ps, 'dokument_mit_notiz.ps');
ps_set_info($ps, 'Creator', 'PHP ps_add_note Beispiel');
ps_set_info($ps, 'Title', 'Notiz-Demonstration');

// Neue Seite beginnen (A4: 595 x 842 Punkte)
ps_begin_page($ps, 595, 842);

// Text auf der Seite ausgeben
$font = ps_findfont($ps, 'Helvetica', '', 0);
ps_setfont($ps, $font, 14);
ps_show_xy($ps, 'Dieser Absatz hat eine Anmerkung.', 50, 700);

// Notiz neben dem Text hinzufügen
ps_add_note(
    $ps,
    500, 690,  // untere linke Ecke
    520, 710,  // obere rechte Ecke
    'Bitte diesen Abschnitt noch einmal prüfen und ggf. kürzen.',
    'Redaktionshinweis',
    'Note',
    0  // geschlossen
);

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

echo 'PostScript-Dokument mit Notiz wurde erstellt.';
?>

PostScript-Dokument mit Notiz wurde erstellt.

Notiz standardmäßig geöffnet und mit Help-Icon

<?php
$ps = ps_new();
ps_open_file($ps, 'hinweis.ps');
ps_set_info($ps, 'Title', 'Hilfe-Notiz Beispiel');

ps_begin_page($ps, 595, 842);

$font = ps_findfont($ps, 'Times-Roman', '', 0);
ps_setfont($ps, $font, 12);
ps_show_xy($ps, 'Wichtiger Hinweis auf dieser Seite:', 50, 750);

// Notiz mit Help-Icon, standardmäßig geöffnet
ps_add_note(
    $ps,
    50, 700,
    80, 730,
    'Dieses Formular muss vollständig ausgefüllt und unterschrieben werden.',
    'Ausfüllhilfe',
    'Help',
    1  // geöffnet
);

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

echo 'Dokument mit geöffneter Hilfe-Notiz erstellt.';
?>

Dokument mit geöffneter Hilfe-Notiz erstellt.

// Wichtig · Fallstricke

Erweiterung erforderlich: ps_add_note() setzt die Installation der pslib-Bibliothek und die PHP-Erweiterung ps voraus. Diese Erweiterung ist in den meisten Standard-PHP-Installationen nicht enthalten und muss separat kompiliert bzw. installiert werden.

Koordinatensystem: Das PostScript-Koordinatensystem hat seinen Ursprung in der unteren linken Ecke der Seite. Die Einheit ist der typografische Punkt (1 Punkt = 1/72 Zoll). Bei A4 entspricht das 595 × 842 Punkte.

Seitenkontext: Die Funktion muss innerhalb eines mit ps_begin_page() eröffneten und noch nicht mit ps_end_page() beendeten Seitenkontexts aufgerufen werden, da die Notiz zur aktuellen Seite gehört.

Siehe auch

ps_new ps_begin_page ps_end_page ps_close ps_delete ps_add_bookmark