picture — `u_pbt_picture` #

← Komponentenreferenz · Inhalt des Handbuchs

Bildanzeige: alle gängigen Formate, Zuschnittmodi, Ausrichtung, automatische Graustufendarstellung und Zähler-Plakette.

▶ Live ansehen — Demoanwendung, Kachel Picture: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Userobject	`u_pbt_picture`
Item-Klasse	— (Komponente ohne Items)
Wofür	Ein PowerBuilder-`picture` ersetzen: moderne Formate (SVG, WebP, animiertes GIF), beherrschter Zuschnitt, anklickbares Bild, automatische Graustufendarstellung
Opt-in-Optionen	`ib_track_mouse`

Schnellstart #

// open-Event des Fensters
uo_image.is_source  = "img\logo.png"
uo_image.is_stretch = uo_image.STRETCH_UNIFORM   // passt an, ohne zu verzerren
uo_image.is_align   = uo_image.ALIGN_CENTER
uo_image.is_tooltip = "Logo der Firma"

Woher das Bild kommt: `is_source` #

is_source akzeptiert vier Formen, die alle austauschbar sind:

Form	Beispiel	Verwendung
Lokale Datei	`img\logo.png`	png, jpg, jfif, bmp, gif, ico, svg, webp, avif
Webadresse	`https://…/logo.png`	Von einem Server geladenes Bild (nur `https`: eine `http://`-Adresse wird abgelehnt, siehe unten)
Eingebettete Daten	`data:image/png;base64,…`	Bereits im Speicher vorliegendes Bild, ohne Zwischendatei
DLL-Ressource	`img\packimages.dll:SAMPLE`	In einer Ressourcen-DLL verpacktes Bild

Einem GIF kann das Präfix anim: vorangestellt werden, um eine Animation ausdrücklich zu kennzeichnen (GIFs werden ohnehin animiert).

Wenn derselbe Name in einer DLL unter mehreren Ressourcentypen vorkommt, geben Sie den Typ an: img\packimages.dll:PNG/SAMPLE, SVG/SAMPLE, ICON/APP, RCDATA/BLOB. Siehe Bilder und Symbole für die Präfixe mono: und tint:, die ein Glyph passend zum Design umfärben.

Eine http://-Adresse wird abgelehnt: Die Seite der Komponente ist gesichert, und die Engine würde das Bild stillschweigend auf https:// umstellen — auf einem Intranet-Server ohne TLS schlüge es dann mit einer irreführenden Meldung fehl. Die Komponente lehnt sie deshalb von vornherein ab: Fehlerzeichen und ue_error mit REASON_INSECURE. Für ein Bild auf einem unverschlüsselten Server laden Sie es zuerst mit n_pbt_restclient.of_download in einen temporären Ordner herunter und zeigen dann diesen Pfad an. Denselben Pfad erneut zuzuweisen liest die Datei neu: Ein Bild, das Ihre Anwendung gerade neu geschrieben hat (Foto, Scan, Zuschnitt), erscheint, wie beim nativen Picture. Ein Bild auf dem Datenträger ist auf 32 MB begrenzt.

Wie es zugeschnitten wird: `is_stretch` #

Konstante	Wirkung
`STRETCH_UNIFORM`	Standard. Das Bild wird ohne Verzerrung skaliert und bleibt vollständig sichtbar; es können Ränder entstehen
`STRETCH_UNIFORMTOFILL`	Ohne Verzerrung skaliert, aber der Rahmen wird vollständig gefüllt; Überstände werden beschnitten
`STRETCH_FILL`	Das Bild wird gedehnt, bis es genau den Rahmen ausfüllt — es kann verzerrt werden
`STRETCH_NONE`	Ursprungsgröße, ohne Skalierung

is_align bestimmt die waagerechte Lage des Bildes, wenn es kleiner als das Steuerelement ist: ALIGN_CENTER (Standard), ALIGN_START, ALIGN_END. Die senkrechte Achse hat ihre eigene Eigenschaft, is_valign. Die Platzierung gilt auf dem Bildschirm: ALIGN_START bleibt am Anfangsrand, unabhängig von ii_rotation und ib_mirror. Ein unbekannter Wert wird als center zurückgelesen.

Konstanten #

Konstante	Wert	Für
`STRETCH_NONE` · `STRETCH_FILL` · `STRETCH_UNIFORM` · `STRETCH_UNIFORMTOFILL`	`"none"` `"fill"` `"uniform"` `"uniformtofill"`	`is_stretch`
`ALIGN_CENTER` · `ALIGN_START` · `ALIGN_END`	`"center"` `"start"` `"end"`	`is_align`
`VALIGN_TOP` · `VALIGN_CENTER` · `VALIGN_BOTTOM`	`"top"` `"center"` `"bottom"`	`is_valign`
`ROTATION_NONE` · `ROTATION_90` · `ROTATION_180` · `ROTATION_270`	`0` `90` `180` `270`	`ii_rotation`
`REASON_NOT_FOUND` · `REASON_TOO_LARGE` · `REASON_INSECURE` · `REASON_UNSUPPORTED` · `REASON_FAILED`	`"notfound"` `"toolarge"` `"insecure"` `"unsupported"` `"failed"`	`ue_error` (`as_reason`)

ALIGN_START und ALIGN_END sind logisch: Sie folgen der Schreibrichtung (Sprache und RTL). Die physischen Werte left und right werden weiterhin als Aliasnamen akzeptiert.

Eigenschaften #

Eigenschaft	Typ	Standard	Zweck
`is_source`	string	`""`	Das anzuzeigende Bild (siehe die vier Formen oben)
`is_stretch`	string	`"uniform"`	Zuschnittmodus: `STRETCH_NONE`, `STRETCH_FILL`, `STRETCH_UNIFORM`, `STRETCH_UNIFORMTOFILL`
`is_align`	string	`"center"`	Horizontale Platzierung, wenn das Bild kleiner als das Steuerelement ist: `ALIGN_CENTER`, `ALIGN_START`, `ALIGN_END`. Die vertikale Achse ist `is_valign`
`is_valign`	string	`VALIGN_CENTER`	Senkrechte Platzierung, wenn das Bild kleiner als das Steuerelement ist: `VALIGN_TOP`, `VALIGN_CENTER`, `VALIGN_BOTTOM`. Die beiden Achsen sind unabhängig — `is_align` gibt die Spalte, diese die Zeile — und genau das macht eine Ecke erreichbar
`ib_enabled`	boolean	`true`	Bei `false` wird das Bild in Graustufen angezeigt und reagiert auf nichts mehr: Klicks, Mausrad, Tastatur und abgelegte Dateien
`ii_badge`	integer	`0`	Zähler-Plakette in der oberen Ecke am Zeilenende: rechts bei Leserichtung links nach rechts, links bei rechts nach links (`0` = keine)
`il_badge_color`	long	`-1`	Hintergrund der Plakette, als PowerBuilder-RGB (`-1` = nicht gesetzt: die Farbe aus dem Design; `0` ist Schwarz, wie bei jeder anderen Farbe). Die Textfarbe wird automatisch gewählt, damit der Zähler lesbar bleibt
`ii_badge_size`	integer	`0`	Höhe der Plakette in Pixeln (`0` = die Größe aus dem Design). Die Schriftgröße folgt von selbst: der Zähler bleibt bei jeder Größe zentriert
`ib_track_mouse`	boolean	`false`	Opt-in: aktiviert `ue_mouse_enter` / `ue_mouse_leave`
`is_placeholder`	string	`""`	Platzhalterbild, angezeigt solange `is_source` leer ist (ein Rahmen « Foto hinzufügen », eine Silhouette). Gedämpft dargestellt: ein Platzhalter ist nicht der Inhalt und wird nie als geladenes Bild gemeldet. Akzeptiert das Präfix `mono:`, das ein einfarbiges Zeichen mit dem Design einfärbt
`is_error_source`	string	`""`	Ersatzbild, wenn die Quelle beim Laden fehlschlägt. Lassen Sie es leer, und die Komponente zeigt ihr eigenes Fehlerzeichen — nie ein leeres Feld, das dem Benutzer nichts sagt, während `ue_error` nur zu Ihrem Code gelangt. Akzeptiert das Präfix `mono:`
`ii_rotation`	integer	`0`	Vierteldrehungen, für Scans und Fotos, die liegend ankommen: `ROTATION_NONE`, `ROTATION_90`, `ROTATION_180`, `ROTATION_270` (jeder andere Wert gilt als 0). Eine Vierteldrehung tauscht auch die Einpassachsen, damit das Bild seine Proportionen behält, statt gequetscht zu werden
`ib_mirror`	boolean	`false`	Waagerechte Spiegelung auf dem Bildschirm: das Bild wird von links nach rechts gespiegelt, unabhängig von `ii_rotation`
`ib_zoomable`	boolean	`false`	Opt-in: Der Benutzer darf heranzoomen (Mausrad, zum Mauszeiger hin, oder Tasten `+` und `-`), sich bewegen (Ziehen, oder Pfeiltasten — bei Leserichtung rechts nach links umgekehrt) und zur Einpassung zurückkehren (Doppelklick, oder `0`); die Taste `1` zeigt das Bild in seiner TATSÄCHLICHEN Größe, ein Bildpixel pro Bildschirmpixel. Größer als sein Rahmen, deckt das Bild ihn immer ab: Ziehen legt nie einen leeren Streifen frei; kleiner, bleibt es dort, wo `is_align` und `is_valign` es platzieren. Nur die linke Maustaste verschiebt es. Für einen Plan, einen Scan, ein Foto — wo vier feste Einpassmodi nicht genügen
`id_zoom`	double	`1.0`	Zoomfaktor: `1.0` = die von `is_stretch` gewählte Einpassung, bis `id_max_zoom` (standardmäßig `8.0`). Zurückgelesen liefert er den aktuellen Faktor, Rad und Tastatur eingeschlossen (`ue_zoom_changed` meldet jede Änderung: eine Geste des Benutzers oder diese von Ihrem Code gesetzte Eigenschaft). Erfordert `ib_zoomable`, zuvor gesetzt: ohne es bleibt der Faktor `1.0`
`id_max_zoom`	double	`8.0`	Die OBERGRENZE des Zooms, in der Einheit von `id_zoom` (`1.0` = die Einpassung): Mausrad, Tasten und `id_zoom` halten dort an. Jeder Wert ab `1.0`; darunter gilt wieder der Standard. Die TATSÄCHLICHE Größe bleibt immer erreichbar — die Taste `1` führt dorthin, und ein großer, klein angezeigter Scan bleibt Pixel für Pixel lesbar. Unter den aktuellen Zoom gesenkt, geht der Zoom darauf zurück und `ue_zoom_changed` meldet es
`ib_allow_drop`	boolean	`false`	Opt-in: nimmt aus dem Windows-Explorer abgelegte Dateien an. Der Rahmen zeigt die Bereitschaft, und die vollständigen Pfade kommen über `ue_drop_files` — sie in `is_source` zu laden bleibt Ihrer Anwendung überlassen. Ein deaktiviertes Bild (`ib_enabled = false`) lehnt jedes Ablegen ab, und `ib_allow_drop` liest sich weiter wie gesetzt
`ib_auto_height`	boolean	`false`	Opt-in: Das Userobject nimmt die Höhe an, die die Proportionen des Bildes bei seiner aktuellen Breite wahrt. Für ein Bild ist diese Höhe ableitbar: Sie müssen sie nicht selbst aus den von `ue_loaded` gemeldeten Maßen berechnen
`is_alt_text`	string	`""`	Alternativtext: was ein Bildschirmleser über das Bild sagt. Für ein rein dekoratives Bild leer lassen
`is_theme_style`	string	`""`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`); leer = der der Anwendung, bei jeder Änderung übernommen
`is_theme_mode`	string	`""`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`); leer = die der Anwendung, bei jeder Änderung übernommen
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent der Anwendung, sonst der des Designs)
`is_tooltip`	string	`""`	Einfacher Tooltip beim Überfahren der Komponente
`is_super_tooltip_title`	string	`""`	Titel des erweiterten Tooltips (hat Vorrang vor `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Text des erweiterten Tooltips (Rich-Markup zulässig)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Tooltips

Methoden #

Methode	Zweck
`of_reset ( )`	Setzt alle Eigenschaften auf ihren Standard zurück und entfernt das Bild. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_set_redraw (boolean)`	Fasst eine Folge von Änderungen zu einer einzigen Darstellung zusammen. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exportiert die Darstellung als Bild. Liefert `0` nach dem Schreiben des Bildes, `-4` wenn das Schreiben fehlschlägt, `-2` wenn die Komponente nicht erzeugt ist

Events #

Event	Ausgelöst wenn
`ue_clicked ( )`	Linksklick auf das Bild. Das Verschieben des gezoomten Bildes ist kein Klick, und ein Doppelklick löst nur einen aus, wie das native `Picture`
`ue_loaded (long al_width, long al_height)`	Das Bild ist geladen; die Parameter tragen seine ursprünglichen Maße in Pixeln
`ue_error (string as_message, string as_reason)`	Das Bild konnte nicht geladen werden. `as_message` nennt die Quelle (`image load failed : <source>`), `as_reason` sagt warum: `REASON_NOT_FOUND` (fehlende Datei), `REASON_TOO_LARGE` (über 32 MB), `REASON_INSECURE` (eine `http://`-Adresse, abgelehnt), `REASON_UNSUPPORTED` (ein Format, das die Komponente nicht anzeigt), `REASON_FAILED` (alles andere: eine Datei, die sich nicht dekodieren lässt, ein Server, der nicht antwortet)
`ue_rclicked ( )`	Rechtsklick auf das Bild
`ue_double_clicked ( )`	Doppelklick auf das Bild. Ein einziges `ue_clicked` geht ihm voraus, nie zwei — wie beim nativen `Picture`. Ist `ib_zoomable` aktiv, führt der Doppelklick außerdem zur Einpassung zurück: das Ereignis wird in beiden Fällen ausgelöst, seine Bedeutung bestimmen Sie
`ue_zoom_changed (double ad_zoom)`	Der Zoomfaktor hat sich geändert: Mausrad, Doppelklick, die Tasten `+`, `-` und `0`, oder `id_zoom`, von Ihrem Code gesetzt — nichts, wenn der Faktor gleich bleibt. `1.0` heißt: zurück zur Einpassung von `is_stretch`
`ue_auto_height (long al_height)`	Die Komponente hat sich auf eine neue Höhe festgelegt; das Userobject ist beim Auslösen bereits angepasst. Erfordert `ib_auto_height`
`ue_drop_files (string as_files[])`	Aus dem Explorer abgelegte Dateien: vollständige Pfade, ein Eintrag je Datei. Erfordert `ib_allow_drop`
`ue_drag_enter ( )`	Ein Dateiziehen hat die Komponente erreicht (`ib_allow_drop`)
`ue_drag_leave ( )`	Das Dateiziehen hat die Komponente verlassen
`ue_mouse_enter ( )`	Die Maus tritt ein — erfordert `ib_track_mouse = true`
`ue_mouse_leave ( )`	Die Maus verlässt den Bereich — erfordert `ib_track_mouse = true`
`ue_ready ( )`	Die Komponente ist fertig geladen; alles zuvor Gesendete wurde nachgespielt
`ue_runtime_missing ( )`	Die WebView2-Runtime fehlt: die Komponente bleibt leer
`ue_bg_color (long al_color)`	Die Komponente hat ihre Design-Hintergrundfarbe berechnet; das Userobject hat sie bereits übernommen (`backcolor`)

Beispiele #

Das Foto eines Datensatzes anzeigen #

// Event ue_row_changed der DataWindow : das Foto des aktuellen Kunden anzeigen
uo_photo.is_source  = "photos\" + ls_customer_code + ".jpg"
uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL   // fuellt den Rahmen, der Ueberstand wird beschnitten
uo_photo.is_align   = uo_photo.ALIGN_CENTER

// Event ue_error von uo_photo : (string as_message, string as_reason)
if as_reason = uo_photo.REASON_NOT_FOUND then
    uo_photo.is_source = "img\photo_missing.svg"     // Ersatzbild
end if

ue_error zu behandeln ist der richtige Weg, um mit einem fehlenden Foto umzugehen: Es ist unnötig, vor der Zuweisung zu prüfen, ob die Datei vorhanden ist.

Ein anklickbares Bild, wie eine Schaltfläche #

// Das Bild und der Tooltip, der erscheint, wenn die Maus darauf ruht
uo_avatar.is_source    = "photos\user.png"
uo_avatar.is_tooltip   = "Mein Konto"

// Event ue_clicked von uo_avatar
of_open_my_account()

Zähler und Graustufendarstellung #

// Eine Benachrichtigungs-Plakette auf einem E-Mail-Symbol
uo_mail.is_source = "img\packimages.dll:SVG/MAIL"
uo_mail.ii_badge  = ll_unread       // 0 laesst die Plakette verschwinden

// Rote Plakette oberhalb einer Schwelle, sonst die Farbe des Designs (-1)
if ll_unread > 20 then
    uo_mail.il_badge_color = RGB(/*red*/ 200, /*green*/ 30, /*blue*/ 30)
else
    uo_mail.il_badge_color = -1
end if

// Funktion nicht verfuegbar : das Bild wechselt in Graustufen, ohne zweites Bild
uo_mail.ib_enabled = ib_mail_allowed

Die Graustufendarstellung wird automatisch berechnet: Sie müssen kein zweites, „deaktiviertes“ Bild bereitstellen.

Die tatsächlichen Maße des Bildes erfahren #

// Show the file the user has chosen
uo_preview.is_source = ls_chosen_file

// Event ue_loaded von uo_preview : (long al_width, long al_height)
uo_status.of_panel(/*key*/ "main").is_text = String(al_width) + " x " + String(al_height) + " px"

// Ein Bild, das kleiner als der Rahmen ist : nicht unnoetig vergroessern
if al_width < uo_preview.width and al_height < uo_preview.height then
    uo_preview.is_stretch = uo_preview.STRETCH_NONE
end if

// Das Bannerbild, das seinen Streifen fuellt
uo_banner.is_source  = "img\banniere.jpg"
uo_banner.is_stretch = uo_banner.STRETCH_UNIFORMTOFILL   // fuellt die ganze Bahn, ohne zu verzerren
uo_banner.is_valign   = uo_banner.VALIGN_TOP               // haelt den oberen Teil des Bildes sichtbar

Best Practices #

STRETCH_UNIFORM ist der sichere Modus: Er verzerrt niemals. Behalten Sie STRETCH_FILL dekorativen Hintergründen vor, bei denen eine Verzerrung folgenlos bleibt.
Für ein Foto in einem festen Rahmen (Mitarbeitergalerie, Miniaturansicht) liefert STRETCH_UNIFORMTOFILL ein gleichmäßiges Ergebnis, ohne unschöne Ränder.
Bündeln Sie Ihre Symbole in einer Ressourcen-DLL, statt Hunderte von Dateien auszuliefern; die Form pack.dll:TYP/NAME beseitigt jede Mehrdeutigkeit.
Für ein einfarbiges Glyph, das dem hellen und dem dunklen Design folgen soll, verwenden Sie das Präfix mono: (Bilder und Symbole).
Schreiben Sie ein Skript für ue_error bei jedem Bild, dessen Quelle von den Daten abhängt: Es ist Ihr einziges Sicherheitsnetz, wenn eine Datei fehlt.
Rufen Sie of_reset() auf, bevor Sie die Komponente für ein Bild anderer Art wiederverwenden: Andernfalls bleiben der vorherige Zuschnittmodus, die Plakette oder der ausgegraute Zustand bestehen.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Mitglieder	Rolle	Beschrieben in
`of_reset`	Die Komponente zurücksetzen	3.6 Eine Komponente zurücksetzen: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Tastenkürzel der Komponente	3.5 Tastenkombinationen
`of_is_created` · `of_is_ready` · `of_get_last_error`	Ob sie entstanden ist, ob sie bereit ist, was fehlschlug	3.7 Diagnose
`of_save_as_png` · `of_save_as_jpg`	Die Darstellung als Bild exportieren	3.8 Die Darstellung als Bild exportieren
`of_set_redraw`	Änderungen zu einem einzigen Neuzeichnen bündeln	3.10 Best Practices
`of_preload_icons`	Symbole ohne Verzögerung	Sofortige Anzeige: `of_icon`
`of_set_translation`	Eine Beschriftung der Komponente übersetzen	5.2 Eine Beschriftung anpassen: `of_set_translation`
`of_focus_webview`	Der Komponente den Fokus geben	6.4 Tastatur und Fokus
`of_print` · `of_print_to_pdf`	Drucken oder ein PDF schreiben	6.9 Drucken
`of_set_property` · `of_get_property` · `of_component_name`	Eine Eigenschaft über ihren Namen steuern	3.1 Die Eigenschaften-Engine

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.