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

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.