picture — u_pbt_picture #

← Component reference · Guide contents

Image display: every common format, framing modes, alignment, automatic graying and a counter badge.

▶ See it live — Demo application, Picture tile: the preview, the code behind it and this page, side by side.

At a glance #

Quick start #

// window open event
uo_image.is_source  = "img\logo.png"
uo_image.is_stretch = uo_image.STRETCH_UNIFORM   // fits without distorting
uo_image.is_align   = uo_image.ALIGN_CENTER
uo_image.is_tooltip = "Company logo"

Where the image comes from: is_source #

is_source accepts four forms, all interchangeable:

An anim: prefix can be placed in front of a GIF to explicitly flag an animation (GIFs animate anyway).

When the same name exists under several resource types in a DLL, state the type: img\packimages.dll:PNG/SAMPLE, SVG/SAMPLE, ICON/APP, RCDATA/BLOB. See Images and icons for the mono: and tint: prefixes, which recolor a glyph according to the theme.

An http:// address is refused: the component's page is secure, and the engine would silently switch the image to https:// — on an intranet server without TLS it would then fail with a misleading message. The component therefore refuses it up front: error glyph and ue_error with REASON_INSECURE. For an image on an unencrypted server, download it first with n_pbt_restclient.of_download into a temporary folder, then show that path. Setting the same path again reads the file again: an image your application has just rewritten (photo, scan, crop) shows up, as with the native Picture. An image on disk is limited to 32 MB.

The formats of the native Picture that the engine does not read — TIFF (scans, faxes), WMF, EMF and RLE — are converted on the fly: an application brought over from PowerBuilder keeps its pictures. Blanks around a path are ignored: a CHAR column read by GetItemString arrives padded with spaces, and Windows ignores them too; is_source reads back as you wrote it. A recoloured picture (mono:, tint:) served by another site over https is drawn only when that server allows cross-origin requests (the Access-Control-Allow-Origin header); otherwise ue_error says so (REASON_FAILED). Files of the workstation, DLL resources and data: are not concerned.

A picture in memory — a photo stored in the database and read by SelectBlob — is shown by of_set_picture(blob), like SetPicture of the native Picture: no temporary file, no base64. The format is recognised from the bytes; ue_loaded or ue_error follow, as for is_source.

How it is framed: is_stretch #

is_align decides the horizontal position of the image when it is smaller than the control: ALIGN_CENTER (default), ALIGN_START, ALIGN_END. The vertical axis has its own property, is_valign. The placement is read on screen: ALIGN_START stays on the leading edge whatever ii_rotation and ib_mirror. An unknown value reads back as center.

Constants #

ALIGN_START and ALIGN_END are logical: they follow the writing direction (Language and RTL). The physical values left and right are still accepted as aliases.

Properties #

Methods #

Events #

Examples #

Showing the photo on a record #

// rowfocuschanged event of dw_customer : show the photo of the current customer
// Local variables
string ls_customer_code

// The code of the customer on the new row
if currentrow < 1 then return
ls_customer_code = this.GetItemString(currentrow, "customer_code")

// The photo fills its frame ; the blanks padding a CHAR column are ignored
uo_photo.is_source  = "photos\" + ls_customer_code + ".jpg"
uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL

// Once, in the open event of the window : the picture shown when a photo is missing
uo_photo.is_error_source = "img\photo_missing.svg"

// ue_error event of uo_photo : (string as_message, string as_reason)
// The fallback picture already shows : here, only count the missing photos
if as_reason = uo_photo.REASON_NOT_FOUND then
    il_missing_photos = il_missing_photos + 1
end if

is_error_source is the right way to deal with a missing photo: there is no need to test whether the file exists before assigning it. Never reassign is_source from ue_error: if the replacement were missing in its turn, the failure would start the load again, endlessly.

Showing a photo stored in the database #

// Local variables
blob lb_photo

// The photo of the employee, stored in a column of the database
SELECTBLOB photo INTO :lb_photo FROM employee WHERE emp_id = 4152 USING SQLCA;

// Shown straight from memory : 0 = handed over, -5 = not a picture
if uo_photo.of_set_picture(/*image*/ lb_photo) <> 0 then
    uo_photo.is_source = ""
end if

A clickable image, button-style #

// The picture, its name for the keyboard and screen readers, and its tooltip
uo_avatar.is_source    = "photos\user.png"
uo_avatar.is_alt_text  = "My account"
uo_avatar.is_tooltip   = "My account"

// A button for the keyboard too : Tab reaches it, Enter or Space raise ue_clicked
uo_avatar.ib_clickable = true

// ue_clicked event of uo_avatar
of_open_my_account()

Counter and graying #

// Local variables
long ll_unread

// A notification badge on a mail icon
ll_unread = 7
uo_mail.is_source = "img\packimages.dll:SVG/MAIL"
uo_mail.ii_badge  = ll_unread       // 0 makes the badge disappear

// Red beyond a threshold, theme color otherwise (-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

// Feature unavailable : the image turns grayscale, with no second image to supply
uo_mail.ib_enabled = ib_mail_allowed

Graying is computed automatically: you do not have to supply a second "disabled" image.

Finding out the real size of the image #

// 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

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

// An image smaller than the frame : do not enlarge it needlessly. The size of the picture
// is in PIXELS, the one of the userobject in PowerBuilder units : compare them in one unit
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

A full-width banner #

// The banner image, filling its strip
uo_banner.is_source  = "img\banniere.jpg"
uo_banner.is_stretch = uo_banner.STRETCH_UNIFORMTOFILL   // fills the whole strip, without distorting
uo_banner.is_valign   = uo_banner.VALIGN_TOP               // keeps the top of the image visible

Best practices #

• STRETCH_UNIFORM is the safe mode: it never distorts. Save STRETCH_FILL for decorative backgrounds where distortion does not matter.
• For a photo in a fixed frame (staff directory, thumbnail), STRETCH_UNIFORMTOFILL gives a consistent result, with no unsightly margins.
• Bundle your icons in a resource DLL rather than shipping hundreds of files; the pack.dll:TYPE/NAME form removes any ambiguity.
• For a monochrome glyph that has to follow the light and dark themes, use the mono: prefix (Images and icons).
• Give an is_error_source to any image whose source depends on data, and keep ue_error for your log: never reassign is_source there.
• Set id_zoom after is_source: a new picture starts at the fitted view.
• Call of_reset() before reusing the component for a different kind of image: otherwise the previous framing mode, badge or grayed-out state stays in place.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents