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.

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 #

// ue_row_changed event of the datawindow : show the photo of the current customer
uo_photo.is_source  = "photos\" + ls_customer_code + ".jpg"
uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL   // fills the frame, the overflow is cropped
uo_photo.is_align   = uo_photo.ALIGN_CENTER

// ue_error event of 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"     // fallback image
end if

Handling ue_error is the right way to deal with a missing photo: there is no need to test whether the file exists before assigning it.

A clickable image, button-style #

// The picture, and the tooltip shown when the mouse rests on it
uo_avatar.is_source    = "photos\user.png"
uo_avatar.is_tooltip   = "My account"

// ue_clicked event of uo_avatar
of_open_my_account()

Counter and graying #

// A notification badge on a mail icon
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 #

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

// 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
if al_width < uo_preview.width and al_height < uo_preview.height 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).
• Script ue_error on any image whose source depends on data: it is your only safety net when a file is missing.
• 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