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

Userobject | `u_pbt_picture`
Clase de items | — (componente sin items)
Sirve para | Sustituir un `picture` de PowerBuilder: formatos modernos (SVG, WebP, GIF animado), encuadre controlado, imagen en la que se puede hacer clic, escala de grises automática
Opciones opt-in | `ib_track_mouse`

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

Forma | Ejemplo | Uso
--- | --- | ---
Fichero local | `img\logo.png` | png, jpg, bmp, gif, ico, svg, webp
Dirección web | `https://…/logo.png` | Imagen cargada desde un servidor (`http` o `https`)
Datos incorporados | `data:image/png;base64,…` | Imagen que ya está en memoria, sin fichero intermedio
Recurso de DLL | `img\packimages.dll:SAMPLE` | Imagen empaquetada en una DLL de recursos

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.

## Cómo se encuadra: `is_stretch` #

Constante | Efecto
--- | ---
`STRETCH_UNIFORM` | Predeterminado. La imagen se escala sin deformación y queda totalmente visible; pueden aparecer márgenes
`STRETCH_UNIFORMTOFILL` | Escalado sin deformación, pero el marco se rellena por completo; lo que sobresale se recorta
`STRETCH_FILL` | La imagen se estira para ocupar exactamente el marco — puede quedar deformada
`STRETCH_NONE` | Tamaño original, sin escalado

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

## Constantes #

Constante | Valor | Para
--- | --- | ---
`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` | Colocación vertical cuando la imagen es más pequeña que el control: `VALIGN_TOP`, `VALIGN_CENTER`, `VALIGN_BOTTOM`. Los dos ejes son independientes — `is_align` da la columna, este la fila — y eso es lo que hace alcanzable una esquina
`ROTATION_NONE` · `ROTATION_90` · `ROTATION_180` · `ROTATION_270` | `0` `90` `180` `270` | `ii_rotation`

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

Propiedad | Tipo | Predeterminado | Función
--- | --- | --- | ---
`is_source` | string | `""` | La imagen que se debe mostrar (véanse las cuatro formas anteriores)
`is_stretch` | string | `"uniform"` | Modo de encuadre: `STRETCH_NONE`, `STRETCH_FILL`, `STRETCH_UNIFORM`, `STRETCH_UNIFORMTOFILL`
`is_align` | string | `"center"` | Colocación horizontal cuando la imagen es más pequeña que el control: `ALIGN_CENTER`, `ALIGN_START`, `ALIGN_END`. El eje vertical es `is_valign`
`ib_enabled` | boolean | `true` | A `false`, la imagen se muestra en escala de grises
`ii_badge` | integer | `0` | Distintivo de contador en el ángulo superior derecho (`0` = ninguno)
`il_badge_color` | long | `0` | Fondo del distintivo, en RGB de PowerBuilder (`0` = el color que viene del tema). El color del texto se elige automáticamente para que el contador siga siendo legible
`ii_badge_size` | integer | `0` | Altura del distintivo en píxeles (`0` = el tamaño que viene del tema). El tamaño de la fuente se ajusta solo: el contador sigue centrado sea cual sea la dimensión
`ib_track_mouse` | boolean | `false` | Opt-in: activa `ue_mouse_enter` / `ue_mouse_leave`
`is_placeholder` | string | `""` | Imagen de espera, mostrada mientras `is_source` está vacía (un marco « añadir una foto », una silueta). Presentada atenuada: un sustituto no es el contenido y nunca se anuncia como imagen cargada. Acepta el prefijo `mono:`, que recolorea un glifo monocromo con el tema
`is_error_source` | string | `""` | Imagen de reserva cuando la fuente falla al cargarse. Déjela vacía y el componente muestra su propio glifo de error — nunca una caja vacía, que no dice nada al usuario mientras `ue_error` solo va a su código. Acepta el prefijo `mono:`
`ii_rotation` | integer | `0` | Cuartos de vuelta, para los escaneos y fotos que llegan tumbados: `ROTATION_NONE`, `ROTATION_90`, `ROTATION_180`, `ROTATION_270` (cualquier otro valor vale 0). Un cuarto de vuelta intercambia también los ejes de encaje, de modo que la imagen conserva sus proporciones en lugar de aplastarse
`ib_mirror` | boolean | `false` | Espejo horizontal, aplicado sobre la rotación
`ib_zoomable` | boolean | `false` | Opt-in: el usuario puede acercarse (rueda), desplazarse (arrastrar) y volver al encuadre (doble clic). Para un plano, un escaneo, una foto — donde cuatro modos de encaje fijos no bastan
`id_zoom` | double | `1.0` | Factor de zoom: `1.0` = la imagen entera cabe, hasta `8.0`. Al releerlo se obtiene el factor actual, rueda incluida (`ue_zoom_changed` avisa en cada paso). Necesita `ib_zoomable`
`ib_allow_drop` | boolean | `false` | Opt-in: acepta archivos soltados desde el Explorador de Windows. El marco muestra que está armado, y las rutas completas llegan por `ue_drop_files` — cargarlas en `is_source` corresponde a su aplicación
`ib_auto_height` | boolean | `false` | Opt-in: el userobject toma la altura que respeta las proporciones de la imagen a su anchura actual. Para una imagen esa altura se deduce: no hace falta calcularla uno mismo a partir de las dimensiones de `ue_loaded`
`is_theme_style` | string | `fluent` | Estilo visual del componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara u oscura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Color de acento de este componente (`-1` = acento del tema)
`is_tooltip` | string | `""` | Tooltip simple mostrado al pasar el ratón por el componente
`is_super_tooltip_title` | string | `""` | Título del tooltip enriquecido (prevalece sobre `is_tooltip`)
`is_super_tooltip_text` | string | `""` | Texto del tooltip enriquecido (se acepta el marcado enriquecido)
`is_super_tooltip_image` | string | `""` | Imagen del tooltip enriquecido

## Métodos #

Método | Función
--- | ---
`of_reset ( )` | Restablece todas las propiedades a su valor predeterminado y retira la imagen
`of_set_redraw (boolean)` | Agrupa una ráfaga de modificaciones en una sola representación
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta la representación como imagen

## Eventos #

Evento | Se activa cuando
--- | ---
`ue_clicked ( )` | Clic izquierdo en la imagen
`ue_loaded (long al_width, long al_height)` | La imagen está cargada; los parámetros contienen sus dimensiones originales en píxeles
`ue_error (string as_message)` | La imagen no se ha podido cargar (fichero ausente, dirección inaccesible, formato rechazado)
`ue_rclicked ( )` | Clic derecho en la imagen
`ue_double_clicked ( )` | Doble clic en la imagen. Los clics simples que lo preceden también se emiten, en el mismo orden. Cuando `ib_zoomable` está activo, el doble clic también devuelve al encuadre: el evento se emite en ambos casos, y usted decide qué significa
`ue_zoom_changed (double ad_zoom)` | El factor de zoom cambió, tanto con la rueda como con `id_zoom`. `1.0` significa que la imagen entera vuelve a caber
`ue_auto_height (long al_height)` | El componente se detuvo en una nueva altura; el userobject ya está redimensionado cuando se emite. Necesita `ib_auto_height`
`ue_drop_files (string as_files[])` | Archivos soltados desde el Explorador: rutas completas, una entrada por archivo. Necesita `ib_allow_drop`
`ue_drag_enter ( )` | Un arrastre de archivos entra en el componente (`ib_allow_drop`)
`ue_drag_leave ( )` | El arrastre de archivos abandona el componente
`ue_mouse_enter ( )` | El ratón entra — requiere `ib_track_mouse = true`
`ue_mouse_leave ( )` | El ratón sale — requiere `ib_track_mouse = true`
`ue_ready ( )` | El componente ha terminado de cargarse; todo lo enviado antes se ha reproducido
`ue_runtime_missing ( )` | El runtime WebView2 está ausente: el componente permanece vacío
`ue_bg_color (long al_color)` | El componente ha calculado el color de fondo de su tema; el userobject ya lo ha adoptado (`backcolor`)

## Ejemplos #

### Mostrar la foto de una ficha #

    // event ue_row_changed de la datawindow : mostrar la foto del cliente actual
    uo_photo.is_source  = "photos\" + ls_code_client + ".jpg"
    uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL   // rellena el marco, lo que sobresale se recorta
    uo_photo.is_align   = uo_photo.ALIGN_CENTER

    // event ue_error de uo_photo : (string as_message)
    uo_photo.is_source = "img\photo_absente.svg"     // imagen de sustitucion

Tratar `ue_error` es la forma correcta de gestionar una foto que falta: no hace falta comprobar la existencia del fichero antes de asignarlo.

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

    uo_avatar.is_source    = "photos\utilisateur.png"
    uo_avatar.is_tooltip   = "Mi cuenta"

    // event ue_clicked de uo_avatar
    of_ouvrir_mon_compte()

### Contador y escala de grises #

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

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

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

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

### Conocer las dimensiones reales de la imagen #

    uo_apercu.is_source = ls_fichier_choisi

    // event ue_loaded de uo_apercu : (long al_width, long al_height)
    uo_statut.of_item("main").is_text = String(al_width) + " x " + String(al_height) + " px"

    // Una imagen mas pequena que el marco : no ampliarla inutilmente
    if al_width < uo_apercu.width and al_height < uo_apercu.height then
        uo_apercu.is_stretch = uo_apercu.STRETCH_NONE
    end if

### Un banner a todo lo ancho #

    uo_banniere.is_source  = "img\banniere.jpg"
    uo_banniere.is_stretch = uo_banniere.STRETCH_UNIFORMTOFILL   // rellena toda la banda, sin deformar
    uo_banniere.is_valign   = uo_banniere.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).
- Programe `ue_error` en toda imagen cuya fuente dependa de los datos: es su única red de seguridad si falta un fichero.
- 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.

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