Icone e immagini in Wisej.NET

Icone e immagini in Wisej.NET, Modulo 1. Wisej.NET offre diversi modi per mettere un'immagine su un controllo, quindi la prima decisione di questo corso è sempre quale meccanismo possiede l'immagine.

La proprietà Image contiene un System.Drawing.Image che il server tiene in memoria e invia al browser come PNG. ImageSource contiene soltanto una stringa, quindi sul server non viene decodificato nulla. Entrambe riempiono lo stesso slot visivo del controllo, ed è proprio per questo che la scelta deve essere consapevole.

Quella stringa può essere un URL relativo, un URL assoluto, il nome di un'immagine del tema o un percorso resource.wx, ed è il client a risolverla. I controlli che supportano le immagini condividono un unico contratto tramite IImage, quindi un pulsante, un'etichetta e una cella di griglia espongono la stessa famiglia di proprietà immagine.

In IconDesk il pulsante Open riceve un oggetto immagine che il server legge da un file. Il pulsante Save riceve su ImageSource il nome di un'immagine del tema. Print e Delete condividono un'unica ImageList e scelgono la loro grafica per chiave, quindi è la lista a decidere che cosa disegnano quei due pulsanti.

Una ImageList è indirezione più che archiviazione. Una chiave porta un significato che sopravvive al riordino, mentre un indice è solo una posizione e, appena la collezione cambia, punta in silenzio a una grafica diversa. Sostituisci l'immagine salvata sotto una chiave e ogni controllo che usa quella chiave la segue, senza toccare altro codice.

L'etichetta di diagnostica chiede a ogni pulsante, tramite IImage, quale proprietà immagine è davvero valorizzata. Quella domanda intercetta un difetto comune: una stringa sorgente assegnata dopo una chiave immagine si prende lo slot, la chiave resta impostata e il controllo disegna la stringa. Leggere il controllo è meglio che tirare a indovinare.

Eseguendo la pagina, quattro icone arrivano per quattro strade diverse e sembrano tutte ugualmente corrette. Solo il pulsante Open ha fatto decodificare un'immagine al server; le altre tre le ha risolte il browser. L'etichetta nomina il meccanismo dietro ciascuna, così la differenza si vede invece di essere data per scontata.

Sostituire la grafica dietro la chiave delete aggiorna quel pulsante da solo, perché il controllo fa riferimento alla chiave e non all'immagine. Assegnare poi una stringa sorgente allo stesso pulsante cambia ciò che disegna, mentre la chiave resta impostata e ignorata.

Lab uno: costruisci il pannello comandi di IconDesk con tutti e tre i meccanismi, aggiungi l'etichetta di diagnostica che legge ogni pulsante tramite IImage e annota l'effetto reale dello scambio di chiave e della doppia assegnazione.

Modulo 2. La pagina ImageLab di IconDesk mette fianco a fianco un oggetto immagine e una stringa sorgente immagine su controlli PictureBox, così la differenza tra le due pipeline diventa qualcosa che puoi vedere.

Chiedere quali formati supporta Wisej.NET non ha una risposta sola, e trattarla come tale provoca difetti veri. Un logo stirato fuori proporzione, una pagina che si blocca mentre scarica una foto remota e un file di icona che si rifiuta di caricarsi nascono tutti dal ridurre due elenchi di formati a uno solo.

Tieni separati i due elenchi. Bitmap, metafile, icona, JPEG, GIF e PNG passano da System.Drawing e dalla proprietà Image. Il gestore delle risorse e le immagini del tema accettano come stringhe JPEG, PNG, GIF, SVG e bitmap. L'SVG appartiene alla pipeline delle stringhe; non è un formato di System.Drawing.

Sei modalità di dimensionamento descrivono che cosa succede quando l'immagine e il box non vanno d'accordo. Normal taglia, AutoSize ridimensiona il box sull'immagine, CenterImage la centra, StretchImage la distorce, Zoom fa entrare tutta l'immagine e Cover riempie il box ritagliando ciò che avanza.

Quattro controlli condividono un'unica stringa sorgente e differiscono solo per la modalità di dimensionamento, e questo isola la decisione sulla dimensione da quella sul caricamento. Il vecchio file di icona si sposta dalla stringa sorgente alla proprietà Image, perché icona e metafile appartengono alla pipeline di System.Drawing.

LoadAsync recupera la foto del partner senza bloccare la pagina mentre arriva. Una sola icona vettoriale, indirizzata come stringa di risorsa, alimenta quattro dimensioni diverse a partire dallo stesso asset. Un gestore di report stampa poi, per ogni PictureBox, se l'immagine è arrivata da Image o da ImageSource.

Eseguendolo, lo stesso asset viene tagliato da Normal, adattato da Zoom, ritagliato da Cover e appiattito da StretchImage. La foto remota è ancora in viaggio e la pagina resta usabile mentre si scarica, che è tutto il senso di caricarla in modo asincrono.

La riga vettoriale resta nitida a sedici, ventiquattro, trentadue e quarantotto pixel. La piccola bitmap è già sfocata a trentadue, perché il browser sta ingrandendo pixel che non ci sono mai stati. Il report nomina poi la pipeline dietro ogni controllo, così nessuno deve indovinare.

Lab due: costruisci ImageLab con quattro modalità di dimensionamento su un unico asset raster, una foto remota tramite LoadAsync, un'icona vettoriale a quattro dimensioni, il gestore del report e la nota sui formati.

Icone e immagini, Modulo 3. L'immagine su un controllo spesso non è un file che distribuisci accanto alla pagina, ma una stringa sorgente, e la schermata IconGallery riempie cinque slot in cinque modi diversi.

Il Modulo 2 ha lasciato IconDesk con un percorso scritto a mano per ogni aspetto, e va bene finché l'aspetto non deve cambiare. Un tema può fornire l'immagine come URL relativo, come URL assoluto, come dati incorporati oppure come immagine con un nome, e solo l'immagine con un nome aggiunge un livello di indirezione.

Assegnare a ImageSource il nome di un'immagine del tema non apre nessun file e non crea nessun System.Drawing.Image. Il nome è una chiave che il client risolve dal tema che ha già caricato, ed è per questo che un tema diverso può fornire una grafica diversa senza alcuna modifica al tuo codice C#.

L'Image Selector del designer sfoglia le immagini di progetto, le immagini del tema e ogni pacchetto di icone referenziato dal progetto, con un'anteprima di ciascuna. Per le icone monocromatiche mostra in anteprima anche il colore, così una decisione di ricolorazione si prende guardando, invece che ricompilando e ricaricando.

Leggi quello che il picker ha scritto. Designer.cs contiene una stringa sorgente di risorsa che rimanda all'assembly che custodisce la grafica, mai una copia del file. La stessa stringa si può calcolare a runtime, e questo conta quando l'icona dipende dallo stato invece che dal layout.

Aggiungere il suffisso di colore a una stringa sorgente ricolora un'icona vettoriale monocromatica adatta. Un colore letterale funziona, ma un nome di colore del tema è meglio, perché così l'icona segue il tema invece di fissare un valore che un futuro cambio di palette contraddirà in silenzio.

Eseguendo IconGallery, cinque slot vengono riempiti da una chiave del tema, un URL relativo, un URL assoluto, una risorsa di un pacchetto e un'icona vettoriale ricolorata. Sembrano tutti ugualmente a posto, eppure solo l'URL assoluto dipende da un host che non controlli, ed è bene saperlo prima del deployment.

Ora cambia tema. La chiave del tema si risolve in una grafica nuova, e il colore del tema nominato nel suffisso cambia insieme a lei. Le tre sorgenti che nominavano una grafica esatta restano identiche, ed è questa la differenza pratica tra un riferimento semantico e uno letterale.

Lab tre: riempi IconGallery tramite l'Image Selector, ricolora un'icona monocromatica con un nome di colore del tema, leggi le stringhe in Designer.cs e scrivi la nota sul cambio di tema.

Modulo 4. IconDesk ha bisogno di cinque icone oggi e forse di altre quaranta in questo trimestre. Raccoglierle file per file ti lascia spessori di tratto diversi, nessuno stile condiviso e nessuna traccia della provenienza di ogni cosa.

Un pacchetto di icone è un normale assembly .NET la cui grafica è salvata come risorse incorporate. Un solo file nella cartella di output può portare centinaia o migliaia di icone, e ognuna resta indirizzabile singolarmente tramite il gestore delle risorse, quindi niente finisce impacchettato in un blocco unico e inutilizzabile.

I due meccanismi consegnano in modo diverso, e questo decide dove sta ciascuno. Le icone di un pacchetto si tirano: una richiesta al primo uso, poi la cache del browser. Le immagini del tema si spingono, precaricate con il tema, ed è per questo che i cataloghi molto ampi stanno in un pacchetto.

Installa i pacchetti ufficiali Wisej 4 e tieni le loro versioni major allineate a quelle del framework. Poi fai la build del progetto prima di cercarli, perché l'image explorer elenca solo i pacchetti contro cui il progetto è stato davvero compilato.

Scegli un'icona e leggi quello che il designer ha generato: il gestore delle risorse, l'assembly del pacchetto, il file dell'icona e, se serve, il suffisso di colore. Ogni parte di quella stringa è verificata a runtime: un nome di file scritto a memoria non si risolve in niente.

In C# preferisci il catalogo di icone del pacchetto a una stringa scritta a mano: una rinomina diventa un errore del compilatore invece di un controllo vuoto. Il namespace esatto cambia da pacchetto a pacchetto. Una sola proprietà immagine per controllo, e una didascalia accanto a ogni icona che porta significato.

La pagina IconCompare mostra gli stessi cinque concetti disegnati da due famiglie, e rende la differenza di stile evidente come una pagina di catalogo non riesce mai a fare. Due icone monocromatiche accettano il suffisso di colore con un nome di colore del tema; una grafica multicolore lo ignora.

Il pannello di rete fornisce la prova: una richiesta per icona al primo caricamento e hit di cache al ricaricamento. Una raccomandazione sostenuta da questo è difendibile, e mostra anche perché referenziare un pacchetto grande non costa a chi impara un download grande.

Lab quattro: referenzia due pacchetti Wisej 4, costruisci una pagina IconCompare con entrambi, scegli almeno cinque icone nell'image explorer, ricolorane due e indica la famiglia di icone principale del progetto.

Icone e immagini, Modulo 5. Cinque asset di IconDesk smettono di essere file sparsi accanto all'applicazione e iniziano a viaggiare dentro l'assembly, indirizzati da una stringa invece che da un percorso su disco.

Una grafica distribuita accanto all'applicazione è a un passo di copia mancato dall'essere rotta. Il server risponde con un 404, il controllo non disegna niente, e il file è ancora presente sulla macchina dello sviluppatore: ecco perché il problema di solito sopravvive finché non è qualcun altro a eseguire la build.

Per questo non c'è nessuna API. Aggiungi il file al progetto e imposta la sua build action su Embedded Resource, e i byte finiscono nel manifest dell'assembly. Quella singola proprietà è anche ciò che trasforma una normale libreria di classi in un pacchetto di icone, come mostrerà il Modulo 6.

Indirizza la risorsa come stringa. Senza un nome di assembly, Wisej.NET cerca fra gli assembly caricati una risorsa che corrisponda. Nominare l'assembly in modo esplicito, scritto senza l'estensione del file, toglie l'ambiguità quando due assembly potrebbero contenere ciascuno un file con lo stesso nome.

Il gestore serve esattamente nove estensioni: fogli di stile, script, HTML, JPEG in tutte e due le grafie, PNG, GIF, grafica vettoriale e bitmap. Nient'altro viene servito, quindi un file di icona incorporato con grandi speranze resta un 404, e la soluzione è convertirlo, non fare il debug dell'URL.

Un file distribuito con l'applicazione può rispondere allo stesso indirizzo prima della copia incorporata. È davvero utile per il rebrand di un cliente o per una correzione urgente senza ricompilare, e significa anche che la cartella che contiene quegli override è ora qualcosa che devi proteggere.

Nel browser cinque richieste tornano con cinque risposte riuscite, tutte servite dall'assembly dell'applicazione, e il ricaricamento arriva invece dalla cache. La grafica vettoriale resta markup per tutto il percorso; in nessun momento diventa un'immagine System.Drawing.

Mettere un logo sostitutivo accanto all'applicazione distribuita cambia l'immagine senza ricompilare nulla. Poi una lettera raddoppiata in un nome di risorsa produce un 404, e la checklist in sei passi lo trova al passo quattro, che è più veloce che rileggere di nuovo il codice.

Lab cinque: incorpora cinque asset, mostrali tutti su ResourceLab, qualifica una sorgente con il nome dell'assembly, sovrascrivine uno con un file distribuito e racconta la caccia al 404.

Modulo 6. Ormai IconDesk usa icone dappertutto e non ne possiede nessuna. Il rimedio è un pacchetto tutto suo: una libreria di classi, una directory Resources e dodici icone vettoriali marcate come risorse incorporate.

Al momento la stessa icona è scritta in quattro modi leggermente diversi su quattro schermate. Ognuno di quei percorsi è una stringa, quindi tre di loro compilano benissimo e falliscono solo nel browser, e questo sposta l'errore dalla build allo schermo di un cliente.

La ricetta documentata ha quattro passi: crea una libreria di classi, crea una directory Resources, mettici dentro le icone e imposta la loro build action su Embedded Resource. Quello che ne esce è un unico indirizzo fatto dal gestore, dal nome dell'assembly e dal percorso della risorsa. Verificalo una volta contro l'applicazione in esecuzione.

Il catalogo trasforma quell'indirizzo in IntelliSense. Una costante privata contiene la parte condivisa del percorso, e una costante pubblica per icona nomina il concetto invece del file, così chi chiama scrive un nome di prodotto come Save o Warning invece di ripetere un percorso.

Due strade finiscono sulla stessa stringa. L'Image Selector la scrive in Designer.cs quando è una decisione di layout a scegliere l'icona, e il codice a runtime la legge dal catalogo quando decide lo stato dell'applicazione. E la grafica vettoriale resta markup che il client risolve, mai un'immagine System.Drawing.

Funziona. Dodici icone arrivano da un solo assembly referenziato, una richiesta alla volta man mano che ciascuna viene usata la prima volta, e servite dalla cache del browser al caricamento successivo. Niente nell'applicazione aveva bisogno di sapere dove vive la grafica su disco.

Il suffisso di colore ricolora due icone e viene ignorato dalla terza, perché quel file ha un colore fissato nel codice della grafica. Togli il valore fissato dal markup, poi ricontrolla il risultato in un tema scuro invece di dare per scontato che la correzione valga anche lì.

Tre abitudini tengono il pacchetto manutenibile: un concetto per icona, il catalogo trattato come API pubblica del pacchetto, così che rinominare resti un problema del compilatore, e una strada di override documentata per un'applicazione che ha bisogno di una grafica diversa sotto lo stesso nome familiare.

Lab sei: costruisci la libreria IconDesk.Icons con dodici icone incorporate e il catalogo, assegnane alcune nel designer e alcune da codice, verifica tre ricolorazioni e scrivi le regole di versionamento.

Icone e immagini in Wisej.NET, Modulo 7, il capstone. IconDesk sa già disegnare un'icona in cinque modi diversi. Ora ne guadagna un sesto e, cosa più importante, la regola scritta che decide fra loro.

Un oggetto immagine, una stringa sorgente, un'immagine del tema, una risorsa incorporata e ora un font di icone. Sei meccanismi senza una prima scelta scritta: ecco come lo stesso comando Delete finisce per avere un aspetto diverso su tre schermate della stessa applicazione.

Un font di icone salta del tutto la pipeline delle immagini. Un solo link al foglio di stile nel Default.html fa scaricare al browser il CSS e i file del font, e una classe CSS dentro il testo di un controllo che consente l'HTML disegna il glifo come testo.

Nessuno dei due approcci vince del tutto. Le risorse Wisej portano ricolorazione, Image Selector e vere proprietà immagine. I font portano un design system CSS già esistente e mettono il glifo in linea con il testo. E l'origine di quel foglio di stile, rete pubblica o tuo server, è una decisione vera.

Nel codice le due decisioni stanno a livelli diversi. Il link al foglio di stile vale per tutta la pagina; consentire l'HTML è una scelta consapevole per singolo controllo. Due glifi con ruoli diversi condividono così una cella di griglia, e il clic riporta quale elemento è stato colpito.

Ecco la policy. Immagini del tema per la grafica semantica che segue il tema. Un pacchetto principale per i comandi. Il pacchetto personalizzato per la grafica di prodotto che possiedi. Raster per le fotografie. Font di icone solo dove l'integrazione HTML ripaga la dipendenza in più.

La pagina di riepilogo esegue tutti e cinque i meccanismi insieme. Cambia tema e lo seguono solo l'immagine del tema e l'icona vettoriale ricolorata. L'icona del pacchetto, quella del pacchetto personalizzato e l'asset incorporato restano esattamente come sono stati disegnati, ed è questo il comportamento attorno a cui è scritta la policy.

La colonna azioni risponde a due clic diversi da un'unica cella leggendo il ruolo dell'elemento colpito. Il controllo di qualità si ripete poi in un tema scuro, verificando che ogni glifo sia ancora leggibile e che ogni azione porti ancora un nome che uno screen reader possa annunciare.

Il capstone: il foglio di stile e una toolbar che consente l'HTML, la colonna azioni con i ruoli, la pagina riepilogo dei cinque meccanismi, la policy delle icone scritta e una nota di qualità su chiaro e scuro.