picture — u_pbt_picture #

← Referencia de componentes · Índice de la guía

Presentación de imágenes: todos los formatos habituales, modos de encuadre, alineación, escala de grises automática y distintivo de contador.

▶ Verlo en vivo — Aplicación de demostración, mosaico Picture: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

// event open de la ventana
uo_image.is_source  = "img\logo.png"
uo_image.is_stretch = uo_image.STRETCH_UNIFORM   // adapta sin deformar
uo_image.is_align   = uo_image.ALIGN_CENTER
uo_image.is_tooltip = "Logotipo de la empresa"

De dónde procede la imagen: is_source #

is_source admite cuatro formas, todas ellas intercambiables:

Se puede anteponer un prefijo anim: a un GIF para señalar explícitamente una animación (los GIF se animan de todos modos).

Cuando el mismo nombre existe bajo varios tipos de recurso en una DLL, indique el tipo: img\packimages.dll:PNG/SAMPLE, SVG/SAMPLE, ICON/APP, RCDATA/BLOB. Véase Imágenes e iconos para los prefijos mono: y tint:, que recolorean un glifo según el tema.

Una dirección http:// se rechaza: la página del componente es segura, y el motor pasaría la imagen a https:// sin decir nada — en un servidor de intranet sin TLS fallaría entonces con un mensaje engañoso. El componente la rechaza por tanto de entrada: glifo de error y ue_error con REASON_INSECURE. Para una imagen de un servidor no cifrado, descárguela primero con n_pbt_restclient.of_download en una carpeta temporal y muestre después esa ruta. Volver a asignar la misma ruta relee el fichero: una imagen que su aplicación acaba de reescribir (foto, escaneo, recorte) aparece, como con el Picture nativo. Una imagen del disco no supera 32 MB.

Los formatos del Picture nativo que el motor no lee — TIFF (escaneos, faxes), WMF, EMF y RLE — se convierten al vuelo: una aplicación traída de PowerBuilder conserva sus imágenes. Los espacios alrededor de una ruta se ignoran: una columna CHAR leída por GetItemString llega rellenada con espacios, y Windows también los ignora; is_source se relee tal como lo escribió. Una imagen recoloreada (mono:, tint:) servida por otro sitio en https solo se dibuja si ese servidor autoriza las peticiones de otro origen (cabecera Access-Control-Allow-Origin); si no, ue_error lo indica (REASON_FAILED). Los ficheros del equipo, los recursos de DLL y los data: no se ven afectados.

Una imagen en memoria — una foto almacenada en la base de datos y leída con SelectBlob — se muestra con of_set_picture(blob), como SetPicture del Picture nativo: ni fichero temporal ni base64. El formato se reconoce por los bytes; siguen ue_loaded o ue_error, como para is_source.

Cómo se encuadra: is_stretch #

is_align decide la posición horizontal de la imagen cuando es más pequeña que el control: ALIGN_CENTER (predeterminado), ALIGN_START, ALIGN_END. El eje vertical tiene su propia propiedad, is_valign. La colocación se lee en pantalla: ALIGN_START se queda en el borde inicial sean cuales sean ii_rotation e ib_mirror. Un valor desconocido se relee center.

Constantes #

ALIGN_START y ALIGN_END son lógicos: siguen el sentido de escritura (Idioma y RTL). Los valores físicos left y right se siguen admitiendo como alias.

Propiedades #

Métodos #

Eventos #

Ejemplos #

Mostrar la foto de una ficha #

// event rowfocuschanged de dw_customer : mostrar la foto del cliente actual
// Local variables
string ls_customer_code

// El codigo del cliente de la nueva fila
if currentrow < 1 then return
ls_customer_code = this.GetItemString(currentrow, "customer_code")

// La foto rellena su marco ; los espacios de una columna CHAR se ignoran
uo_photo.is_source  = "photos\" + ls_customer_code + ".jpg"
uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL

// Una vez, en el event open de la ventana : la imagen que se muestra cuando falta una foto
uo_photo.is_error_source = "img\photo_missing.svg"

// event ue_error de uo_photo : (string as_message, string as_reason)
// La imagen de sustitucion ya se muestra : aqui, solo contar las fotos que faltan
if as_reason = uo_photo.REASON_NOT_FOUND then
    il_missing_photos = il_missing_photos + 1
end if

is_error_source es la forma correcta de gestionar una foto que falta: no hace falta comprobar la existencia del fichero antes de asignarlo. No vuelva a asignar nunca is_source desde ue_error: si a su vez faltara la imagen de sustitución, el fallo relanzaría la carga sin fin.

Mostrar una foto almacenada en la base de datos #

// Local variables
blob lb_photo

// La foto del empleado, almacenada en una columna de la base de datos
SELECTBLOB photo INTO :lb_photo FROM employee WHERE emp_id = 4152 USING SQLCA;

// Mostrada directamente desde la memoria : 0 = entregada, -5 = no es una imagen
if uo_photo.of_set_picture(/*image*/ lb_photo) <> 0 then
    uo_photo.is_source = ""
end if

Una imagen en la que se puede hacer clic, a modo de botón #

// La imagen, su nombre para el teclado y los lectores de pantalla, y su descripcion emergente
uo_avatar.is_source    = "photos\user.png"
uo_avatar.is_alt_text  = "Mi cuenta"
uo_avatar.is_tooltip   = "Mi cuenta"

// Un boton tambien para el teclado : Tab lo alcanza, Intro o Espacio lanzan ue_clicked
uo_avatar.ib_clickable = true

// event ue_clicked de uo_avatar
of_open_my_account()

Contador y escala de grises #

// Local variables
long ll_unread

// Un distintivo de notificaciones sobre un icono de correo
ll_unread = 7
uo_mail.is_source = "img\packimages.dll:SVG/MAIL"
uo_mail.ii_badge  = ll_unread       // 0 hace desaparecer el distintivo

// Distintivo rojo a partir de un umbral, color del tema en caso contrario (-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

// Funcion no disponible : la imagen pasa a escala de grises, sin necesidad de otra imagen
uo_mail.ib_enabled = ib_mail_allowed

La escala de grises se calcula automáticamente: usted no tiene que proporcionar una segunda imagen «desactivada».

Conocer las dimensiones reales de la imagen #

// 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 de uo_preview : (long al_width, long al_height)
uo_status.of_panel(/*key*/ "main").is_text = String(al_width) + " x " + String(al_height) + " px"

// Una imagen mas pequena que el marco : no ampliarla inutilmente. El tamano de la imagen
// esta en PIXELES, el del userobject en unidades PowerBuilder : compararlos en la misma unidad
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

Un banner a todo lo ancho #

// La imagen del banner, que llena su franja
uo_banner.is_source  = "img\banniere.jpg"
uo_banner.is_stretch = uo_banner.STRETCH_UNIFORMTOFILL   // rellena toda la banda, sin deformar
uo_banner.is_valign   = uo_banner.VALIGN_TOP               // mantiene visible la parte alta de la imagen

Buenas prácticas #

• STRETCH_UNIFORM es el modo seguro: nunca deforma. Reserve STRETCH_FILL a los fondos decorativos, en los que la deformación no tiene consecuencias.
• Para una foto en un marco fijo (orla de fotos, miniatura), STRETCH_UNIFORMTOFILL da un resultado uniforme, sin márgenes antiestéticos.
• Agrupe sus iconos en una DLL de recursos en lugar de entregar cientos de ficheros; la forma pack.dll:TIPO/NOMBRE elimina toda ambigüedad.
• Para un glifo monocromo que deba seguir el tema claro y oscuro, utilice el prefijo mono: (Imágenes e iconos).
• Dé un is_error_source a toda imagen cuya fuente dependa de los datos, y reserve ue_error para su registro: no vuelva a asignar nunca is_source allí.
• Fije id_zoom después de is_source: una nueva imagen vuelve a empezar en el encuadre.
• Llame a of_reset() antes de reutilizar el componente para una imagen de naturaleza diferente: sin ello, el modo de encuadre, el distintivo o el estado en escala de grises anteriores se mantienen.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía