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 #

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:

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.

Die Formate des nativen Picture, die die Engine nicht liest — TIFF (Scans, Faxe), WMF, EMF und RLE — werden im Flug umgewandelt: Eine aus PowerBuilder übernommene Anwendung behält ihre Bilder. Leerzeichen um einen Pfad werden ignoriert: Eine mit GetItemString gelesene CHAR-Spalte kommt mit Leerzeichen aufgefüllt an, und Windows ignoriert sie ebenfalls; is_source liest sich so zurück, wie Sie es geschrieben haben. Ein umgefärbtes Bild (mono:, tint:), das von einer anderen Website über https geliefert wird, wird nur gezeichnet, wenn dieser Server Anfragen anderer Herkunft erlaubt (Header Access-Control-Allow-Origin); sonst meldet es ue_error (REASON_FAILED). Dateien des Arbeitsplatzes, DLL-Ressourcen und data: sind nicht betroffen.

Ein Bild im Speicher — ein in der Datenbank gespeichertes und mit SelectBlob gelesenes Foto — wird mit of_set_picture(blob) angezeigt, wie SetPicture des nativen Picture: keine temporäre Datei, kein Base64. Das Format wird an den Bytes erkannt; ue_loaded oder ue_error folgen, wie bei is_source.

Wie es zugeschnitten wird: is_stretch #

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 #

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 #

Methoden #

Events #

Beispiele #

Das Foto eines Datensatzes anzeigen #

// Event rowfocuschanged von dw_customer : das Foto des aktuellen Kunden anzeigen
// Local variables
string ls_customer_code

// Der Code des Kunden der neuen Zeile
if currentrow < 1 then return
ls_customer_code = this.GetItemString(currentrow, "customer_code")

// Das Foto fuellt seinen Rahmen ; die Leerzeichen einer CHAR-Spalte werden ignoriert
uo_photo.is_source  = "photos\" + ls_customer_code + ".jpg"
uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL

// Einmal, im Event open des Fensters : das Bild, das angezeigt wird, wenn ein Foto fehlt
uo_photo.is_error_source = "img\photo_missing.svg"

// Event ue_error von uo_photo : (string as_message, string as_reason)
// Das Ersatzbild wird bereits angezeigt : hier nur die fehlenden Fotos zaehlen
if as_reason = uo_photo.REASON_NOT_FOUND then
    il_missing_photos = il_missing_photos + 1
end if

is_error_source 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. Weisen Sie is_source nie aus ue_error heraus neu zu: Fehlte auch das Ersatzbild, würde der Fehlschlag das Laden endlos neu starten.

Ein in der Datenbank gespeichertes Foto anzeigen #

// Local variables
blob lb_photo

// Das Foto des Mitarbeiters, in einer Spalte der Datenbank gespeichert
SELECTBLOB photo INTO :lb_photo FROM employee WHERE emp_id = 4152 USING SQLCA;

// Direkt aus dem Speicher angezeigt : 0 = uebergeben, -5 = kein Bild
if uo_photo.of_set_picture(/*image*/ lb_photo) <> 0 then
    uo_photo.is_source = ""
end if

Ein anklickbares Bild, wie eine Schaltfläche #

// Das Bild, sein Name fuer Tastatur und Bildschirmleser, und sein Tooltip
uo_avatar.is_source    = "photos\user.png"
uo_avatar.is_alt_text  = "Mein Konto"
uo_avatar.is_tooltip   = "Mein Konto"

// Auch fuer die Tastatur eine Schaltflaeche : Tab erreicht sie, Eingabe oder Leertaste loesen ue_clicked aus
uo_avatar.ib_clickable = true

// Event ue_clicked von uo_avatar
of_open_my_account()

Zähler und Graustufendarstellung #

// Local variables
long ll_unread

// Eine Benachrichtigungs-Plakette auf einem E-Mail-Symbol
ll_unread = 7
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 #

// Local variables
string ls_chosen_file, ls_name

// Show the file the user has chosen
if GetFileOpenName("Picture", ls_chosen_file, ls_name, "jpg", "Pictures (*.jpg;*.png),*.jpg;*.png", /*initdir*/ "", OFN_EXPLORER + OFN_NOCHANGEDIR) = 1 then
    uo_preview.is_source = ls_chosen_file
end if

// 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. Die Bildgroesse ist
// in PIXELN, die des Userobjects in PowerBuilder-Einheiten : in derselben Einheit vergleichen
if al_width < UnitsToPixels(uo_preview.width, XUnitsToPixels!) and al_height < UnitsToPixels(uo_preview.height, YUnitsToPixels!) then
    uo_preview.is_stretch = uo_preview.STRETCH_NONE
end if

Ein Banner über die gesamte Breite #

// 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).
• Geben Sie jedem Bild, dessen Quelle von den Daten abhängt, ein is_error_source, und behalten Sie ue_error Ihrem Protokoll vor: Weisen Sie dort nie is_source neu zu.
• Setzen Sie id_zoom nach is_source: Ein neues Bild beginnt in der Einpassung.
• 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.

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.

← Komponentenreferenz · Inhalt des Handbuchs