# picture — `u_pbt_picture` #

← Riferimento dei componenti · Sommario della guida

> Visualizzazione di immagini: tutti i formati correnti, modalità di ritaglio, allineamento, conversione automatica in scala di grigi e pastiglia contatore.

> ▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Picture: l'anteprima, il codice che lo produce e questa pagina, affiancati.

## In breve #

Userobject | `u_pbt_picture`
Classe degli item | — (componente senza item)
Serve per | Sostituire un `picture` PowerBuilder: formati moderni (SVG, WebP, GIF animato), ritaglio controllato, immagine cliccabile, conversione automatica in scala di grigi
Opzioni opt-in | `ib_track_mouse`

## Avvio rapido #

    // event open della finestra
    uo_image.is_source  = "img\logo.png"
    uo_image.is_stretch = uo_image.STRETCH_UNIFORM   // adatta senza deformare
    uo_image.is_align   = uo_image.ALIGN_CENTER
    uo_image.is_tooltip = "Logo della societa"

## Da dove arriva l'immagine: `is_source` #

`is_source` accetta quattro forme, tutte intercambiabili:

Forma | Esempio | Uso
--- | --- | ---
File locale | `img\logo.png` | png, jpg, bmp, gif, ico, svg, webp
Indirizzo web | `https://…/logo.png` | Immagine caricata da un server (`http` o `https`)
Dati incorporati | `data:image/png;base64,…` | Immagine già in memoria, senza file intermedio
Risorsa di DLL | `img\packimages.dll:SAMPLE` | Immagine impacchettata in una DLL di risorse

Un prefisso `anim:` può essere posto davanti a un GIF per segnalare esplicitamente un'animazione (i GIF si animano comunque).

Quando lo stesso nome esiste sotto più tipi di risorsa in una DLL, precisi il tipo: `img\packimages.dll:PNG/SAMPLE`, `SVG/SAMPLE`, `ICON/APP`, `RCDATA/BLOB`. Vedere Immagini e icone per i prefissi `mono:` e `tint:`, che ricolorano un glifo in base al tema.

## Come viene ritagliata: `is_stretch` #

Costante | Effetto
--- | ---
`STRETCH_UNIFORM` | Predefinito. L'immagine è ridimensionata senza deformazione, interamente visibile; possono comparire dei margini
`STRETCH_UNIFORMTOFILL` | Ridimensionamento senza deformazione, ma la cornice è interamente riempita; le eccedenze vengono ritagliate
`STRETCH_FILL` | L'immagine è stirata per occupare esattamente la cornice — può risultare deformata
`STRETCH_NONE` | Dimensione originale, senza ridimensionamento

`is_align` decide la posizione orizzontale dell'immagine quando è più piccola del controllo: `ALIGN_CENTER` (predefinito), `ALIGN_START`, `ALIGN_END`. L'asse verticale ha la sua proprietà, `is_valign`.

## Costanti #

Costante | Valore | Per
--- | --- | ---
`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` | Collocazione verticale quando l immagine è più piccola del controllo: `VALIGN_TOP`, `VALIGN_CENTER`, `VALIGN_BOTTOM`. I due assi sono indipendenti — `is_align` dà la colonna, questa la riga — ed è ciò che rende raggiungibile un angolo
`ROTATION_NONE` · `ROTATION_90` · `ROTATION_180` · `ROTATION_270` | `0` `90` `180` `270` | `ii_rotation`

`ALIGN_START` e `ALIGN_END` sono logici: seguono il senso di scrittura (Lingua e RTL). I valori fisici `left` e `right` restano accettati come alias.

## Proprietà #

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_source` | string | `""` | L'immagine da visualizzare (vedere le quattro forme qui sopra)
`is_stretch` | string | `"uniform"` | Modalità di ritaglio: `STRETCH_NONE`, `STRETCH_FILL`, `STRETCH_UNIFORM`, `STRETCH_UNIFORMTOFILL`
`is_align` | string | `"center"` | Posizionamento orizzontale quando l'immagine è più piccola del controllo: `ALIGN_CENTER`, `ALIGN_START`, `ALIGN_END`. L'asse verticale è `is_valign`
`ib_enabled` | boolean | `true` | A `false`, l'immagine è visualizzata in scala di grigi
`ii_badge` | integer | `0` | Pastiglia contatore nell'angolo superiore destro (`0` = nessuna)
`il_badge_color` | long | `0` | Sfondo della pastiglia, in RGB PowerBuilder (`0` = il colore che proviene dal tema). Il colore del testo viene scelto automaticamente affinché il contatore resti leggibile
`ii_badge_size` | integer | `0` | Altezza del badge in pixel (`0` = la dimensione che proviene dal tema). La dimensione del carattere segue da sola: il contatore resta centrato qualunque sia la dimensione
`ib_track_mouse` | boolean | `false` | Opt-in: attiva `ue_mouse_enter` / `ue_mouse_leave`
`is_placeholder` | string | `""` | Immagine segnaposto, mostrata finché `is_source` è vuota (una cornice « aggiungi una foto », una sagoma). Presentata attenuata: un segnaposto non è il contenuto e non viene mai annunciato come immagine caricata. Accetta il prefisso `mono:`, che ricolora un glifo monocromatico con il tema
`is_error_source` | string | `""` | Immagine di ripiego quando la sorgente fallisce il caricamento. La lasci vuota e il componente mostra il proprio glifo di errore — mai un riquadro vuoto, che non dice nulla all utente mentre `ue_error` va solo al Suo codice. Accetta il prefisso `mono:`
`ii_rotation` | integer | `0` | Quarti di giro, per le scansioni e le foto che arrivano coricate: `ROTATION_NONE`, `ROTATION_90`, `ROTATION_180`, `ROTATION_270` (qualunque altro valore vale 0). Un quarto di giro scambia anche gli assi di adattamento, così l'immagine conserva le proporzioni invece di essere schiacciata
`ib_mirror` | boolean | `false` | Specchiatura orizzontale, applicata sopra la rotazione
`ib_zoomable` | boolean | `false` | Opt-in: l'utente può avvicinarsi (rotellina), spostarsi (trascinamento) e tornare all'inquadratura (doppio clic). Per una pianta, una scansione, una foto — dove quattro modi di adattamento fissi non bastano
`id_zoom` | double | `1.0` | Fattore di zoom: `1.0` = l'immagine intera entra, fino a `8.0`. Rileggendolo si ottiene il fattore corrente, rotellina compresa (`ue_zoom_changed` avvisa a ogni scatto). Richiede `ib_zoomable`
`ib_allow_drop` | boolean | `false` | Opt-in: accetta i file rilasciati da Esplora risorse. La cornice mostra di essere armata, e i percorsi completi arrivano con `ue_drop_files` — caricarli in `is_source` spetta alla sua applicazione
`ib_auto_height` | boolean | `false` | Opt-in: l'userobject prende l'altezza che rispetta le proporzioni dell'immagine alla larghezza corrente. Per un'immagine quell'altezza si deduce: non serve calcolarla da sé a partire dalle dimensioni di `ue_loaded`
`is_theme_style` | string | `fluent` | Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Colore d'accento di questo componente (`-1` = accento del tema)
`is_tooltip` | string | `""` | Tooltip semplice mostrato al passaggio del mouse sul componente
`is_super_tooltip_title` | string | `""` | Titolo del tooltip avanzato (prevale su `is_tooltip`)
`is_super_tooltip_text` | string | `""` | Testo del tooltip avanzato (markup avanzato accettato)
`is_super_tooltip_image` | string | `""` | Immagine del tooltip avanzato

## Metodi #

Metodo | Ruolo
--- | ---
`of_reset ( )` | Riporta tutte le proprietà al valore predefinito e rimuove l'immagine
`of_set_redraw (boolean)` | Raggruppa una raffica di modifiche in un unico rendering
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Esporta il rendering come immagine

## Event #

Event | Attivato quando
--- | ---
`ue_clicked ( )` | Clic sinistro sull'immagine
`ue_loaded (long al_width, long al_height)` | L'immagine è caricata; i parametri portano le sue dimensioni originali in pixel
`ue_error (string as_message)` | L'immagine non ha potuto essere caricata (file assente, indirizzo irraggiungibile, formato rifiutato)
`ue_rclicked ( )` | Clic destro sull'immagine
`ue_double_clicked ( )` | Doppio clic sull'immagine. Anche i clic singoli che lo precedono vengono emessi, nello stesso ordine. Quando `ib_zoomable` è attivo, il doppio clic riporta anche all'inquadratura: l'evento parte in entrambi i casi, sta a lei decidere cosa significa
`ue_zoom_changed (double ad_zoom)` | Il fattore di zoom è cambiato, con la rotellina come con `id_zoom`. `1.0` significa che l'immagine intera entra di nuovo
`ue_auto_height (long al_height)` | Il componente si è fermato su una nuova altezza; l'userobject è già ridimensionato quando l'evento parte. Richiede `ib_auto_height`
`ue_drop_files (string as_files[])` | File rilasciati da Esplora risorse: percorsi completi, una voce per file. Richiede `ib_allow_drop`
`ue_drag_enter ( )` | Un trascinamento di file entra nel componente (`ib_allow_drop`)
`ue_drag_leave ( )` | Il trascinamento di file lascia il componente
`ue_mouse_enter ( )` | Il mouse entra — richiede `ib_track_mouse = true`
`ue_mouse_leave ( )` | Il mouse esce — richiede `ib_track_mouse = true`
`ue_ready ( )` | Il componente ha terminato il caricamento; tutto ciò che è stato inviato prima è stato riprodotto
`ue_runtime_missing ( )` | Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)` | Il componente ha calcolato il colore di sfondo del proprio tema; l'userobject lo ha già adottato (`backcolor`)

## Esempi #

### Visualizzare la foto di una scheda #

    // event ue_row_changed della datawindow : visualizzare la foto del cliente corrente
    uo_photo.is_source  = "photos\" + ls_code_client + ".jpg"
    uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL   // riempie la cornice, l'eccedenza viene ritagliata
    uo_photo.is_align   = uo_photo.ALIGN_CENTER

    // event ue_error di uo_photo : (string as_message)
    uo_photo.is_source = "img\photo_absente.svg"     // immagine sostitutiva

Gestire `ue_error` è il modo corretto di trattare una foto mancante: è inutile verificare l'esistenza del file prima di assegnarlo.

### Un'immagine cliccabile, in stile pulsante #

    uo_avatar.is_source    = "photos\utilisateur.png"
    uo_avatar.is_tooltip   = "Il mio account"

    // event ue_clicked di uo_avatar
    of_ouvrir_mon_compte()

### Contatore e scala di grigi #

    // Una pastiglia di notifiche su un'icona di posta
    uo_messagerie.is_source = "img\packimages.dll:SVG/MAIL"
    uo_messagerie.ii_badge  = ll_non_lus       // 0 fa sparire la pastiglia

    // Pastiglia rossa oltre una soglia, colore del tema altrimenti (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

    // Funzione non disponibile : l'immagine passa in scala di grigi, senza fornire una seconda immagine
    uo_messagerie.ib_enabled = ib_droit_messagerie

La scala di grigi è calcolata automaticamente: non deve fornire una seconda immagine « disattivata ».

### Conoscere le dimensioni reali dell'immagine #

    uo_apercu.is_source = ls_fichier_choisi

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

    // Un'immagine piu piccola della cornice : non ingrandirla 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 tutta larghezza #

    uo_banniere.is_source  = "img\banniere.jpg"
    uo_banniere.is_stretch = uo_banniere.STRETCH_UNIFORMTOFILL   // riempie tutta la fascia, senza deformare
    uo_banniere.is_valign   = uo_banniere.VALIGN_TOP               // mantiene visibile la parte alta dell'immagine

## Buone pratiche #

- `STRETCH_UNIFORM` è la modalità sicura: non deforma mai. Riservi `STRETCH_FILL` agli sfondi decorativi, dove la deformazione è senza conseguenze.
- Per una foto in una cornice fissa (organigramma fotografico, miniatura), `STRETCH_UNIFORMTOFILL` dà un risultato regolare, senza margini antiestetici.
- Raggruppi le Sue icone in una DLL di risorse anziché consegnare centinaia di file; la forma `pack.dll:TIPO/NOME` elimina ogni ambiguità.
- Per un glifo monocromatico che deve seguire il tema chiaro e scuro, usi il prefisso `mono:` (Immagini e icone).
- Scriva uno script per `ue_error` su ogni immagine la cui sorgente dipende dai dati: è la Sua unica rete di sicurezza in caso di file mancante.
- Chiami `of_reset()` prima di riutilizzare il componente per un'immagine di natura diversa: senza questo, la modalità di ritaglio, la pastiglia o lo stato in scala di grigi precedenti restano attivi.

← Riferimento dei componenti · Sommario della guida