# 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, bmp, gif, ico, svg, webp
Webadresse | `https://…/logo.png` | Von einem Server geladenes Bild (`http` oder `https`)
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.

## 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`.

## 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`
`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
`ROTATION_NONE` · `ROTATION_90` · `ROTATION_180` · `ROTATION_270` | `0` `90` `180` `270` | `ii_rotation`

`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`
`ib_enabled` | boolean | `true` | Bei `false` wird das Bild in Graustufen angezeigt
`ii_badge` | integer | `0` | Zähler-Plakette in der oberen rechten Ecke (`0` = keine)
`il_badge_color` | long | `0` | Hintergrund der Plakette, als PowerBuilder-RGB (`0` = die Farbe aus dem Design). 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, über der Drehung angewendet
`ib_zoomable` | boolean | `false` | Opt-in: Der Benutzer darf heranzoomen (Mausrad), sich bewegen (Ziehen) und zur Einpassung zurückkehren (Doppelklick). Für einen Plan, einen Scan, ein Foto — wo vier feste Einpassmodi nicht genügen
`id_zoom` | double | `1.0` | Zoomfaktor: `1.0` = das ganze Bild passt, bis `8.0`. Zurückgelesen liefert er den aktuellen Faktor, das Rad eingeschlossen (`ue_zoom_changed` meldet jede Stufe). Erfordert `ib_zoomable`
`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
`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_theme_style` | string | `fluent` | Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Helle oder dunkle Variante (Konstanten `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Akzentfarbe dieser Komponente (`-1` = Akzent 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
`of_set_redraw (boolean)` | Fasst eine Folge von Änderungen zu einer einzigen Darstellung zusammen
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exportiert die Darstellung als Bild

## Events #

Event | Ausgelöst wenn
--- | ---
`ue_clicked ( )` | Linksklick auf das Bild
`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)` | Das Bild konnte nicht geladen werden (fehlende Datei, nicht erreichbare Adresse, abgelehntes Format)
`ue_rclicked ( )` | Rechtsklick auf das Bild
`ue_double_clicked ( )` | Doppelklick auf das Bild. Die vorausgehenden Einfachklicks werden ebenfalls ausgelöst, in derselben Reihenfolge. 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, per Mausrad wie per `id_zoom`. `1.0` heißt, dass das ganze Bild wieder passt
`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_code_client + ".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)
    uo_photo.is_source = "img\photo_absente.svg"     // Ersatzbild

`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 #

    uo_avatar.is_source    = "photos\utilisateur.png"
    uo_avatar.is_tooltip   = "Mein Konto"

    // Event ue_clicked von uo_avatar
    of_ouvrir_mon_compte()

### Zähler und Graustufendarstellung #

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

    // Rote Plakette oberhalb einer Schwelle, sonst die Farbe des Designs (0)
    if ll_non_lus > 20 then
        uo_messagerie.il_badge_color = RGB(200, 30, 30)
    else
        uo_messagerie.il_badge_color = 0
    end if

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

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

### Die tatsächlichen Maße des Bildes erfahren #

    uo_apercu.is_source = ls_fichier_choisi

    // Event ue_loaded von uo_apercu : (long al_width, long al_height)
    uo_statut.of_item("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_apercu.width and al_height < uo_apercu.height then
        uo_apercu.is_stretch = uo_apercu.STRETCH_NONE
    end if

### Ein Banner über die gesamte Breite #

    uo_banniere.is_source  = "img\banniere.jpg"
    uo_banniere.is_stretch = uo_banniere.STRETCH_UNIFORMTOFILL   // fuellt die ganze Bahn, ohne zu verzerren
    uo_banniere.is_valign   = uo_banniere.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.

← Komponentenreferenz · Inhalt des Handbuchs