Personalizzazione delle icone¶
Finora la nostra applicazione ha utilizzato l'icona predefinita "ape grigia". Come possiamo aggiornare l'app per utilizzare la nostra icona?
Nota
In BeeWare, il termine icona può riferirsi a due cose diverse:
-
Icona dell'applicazione - L'immagine che rappresenta l'applicazione sul desktop, sul dock o sulla schermata iniziale.
-
Icone runtime - Immagini utilizzate all'interno dell'interfaccia dell'applicazione (ad esempio, nei pulsanti o nelle tabelle).
Aggiunta di un'icona¶
Ogni piattaforma utilizza un formato diverso per le icone delle applicazioni e alcune piattaforme hanno bisogno di molte icone di dimensioni e forme diverse. Per tenere conto di questo, Briefcase offre un modo breve per configurare un'icona una volta sola, e poi far sì che la definizione si espanda a tutte le diverse icone necessarie per ogni singola piattaforma.
Modificare il file pyproject.toml, aggiungendo una nuova voce di
configurazione icon nella sezione di configurazione
[tool.briefcase.app.helloworld], appena sopra la definizione sources:
icon = "icons/helloworld"
Questa definizione di icona non specifica alcuna estensione di file. Il valore sarà usato come prefisso; ogni piattaforma aggiungerà ulteriori elementi a questo prefisso per creare i file necessari per ogni piattaforma. Alcune piattaforme richiedono multipli file di icone; questo prefisso sarà combinato con i modificatori di dimensione e variante del file per generare l'elenco dei file di icone utilizzati.
Ora possiamo eseguire nuovamente briefcase update, ma questa volta passiamo il
flag --update-resources, indicando a Briefcase che vogliamo installare le
nuove risorse dell'applicazione (cioè le icone):
(beeware-venv) $ briefcase update --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Unable to find icons/helloworld.icns for application icon; using default
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
(beeware-venv) $ briefcase update --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Unable to find icons/helloworld-16.png for 16px application icon; using default
Unable to find icons/helloworld-32.png for 32px application icon; using default
Unable to find icons/helloworld-64.png for 64px application icon; using default
Unable to find icons/helloworld-128.png for 128px application icon; using default
Unable to find icons/helloworld-256.png for 256px application icon; using default
Unable to find icons/helloworld-512.png for 512px application icon; using default
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
(beeware-venv) C:\...>briefcase update --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Unable to find icons/helloworld.ico for application icon; using default
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
(beeware-venv) $ briefcase update android --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Unable to find icons/helloworld-round-48.png for 48px round application icon; using default
Unable to find icons/helloworld-round-72.png for 72px round application icon; using default
Unable to find icons/helloworld-round-96.png for 96px round application icon; using default
Unable to find icons/helloworld-round-144.png for 144px round application icon; using default
Unable to find icons/helloworld-round-192.png for 192px round application icon; using default
Unable to find icons/helloworld-square-48.png for 48px square application icon; using default
Unable to find icons/helloworld-square-72.png for 72px square application icon; using default
Unable to find icons/helloworld-square-96.png for 96px square application icon; using default
Unable to find icons/helloworld-square-144.png for 144px square application icon; using default
Unable to find icons/helloworld-square-192.png for 192px square application icon; using default
Unable to find icons/helloworld-square-320.png for 320px square application icon; using default
Unable to find icons/helloworld-square-480.png for 480px square application icon; using default
Unable to find icons/helloworld-square-640.png for 640px square application icon; using default
Unable to find icons/helloworld-square-960.png for 960px square application icon; using default
Unable to find icons/helloworld-square-1280.png for 1280px square application icon; using default
Unable to find icons/helloworld-adaptive-108.png for 108px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-162.png for 162px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-216.png for 216px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-324.png for 324px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-432.png for 432px adaptive application icon; using default
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
(beeware-venv) $ briefcase iOS --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Unable to find icons/helloworld-20.png for 20px application icon; using default
Unable to find icons/helloworld-29.png for 29px application icon; using default
Unable to find icons/helloworld-40.png for 40px application icon; using default
Unable to find icons/helloworld-58.png for 58px application icon; using default
Unable to find icons/helloworld-60.png for 60px application icon; using default
Unable to find icons/helloworld-76.png for 76px application icon; using default
Unable to find icons/helloworld-80.png for 80px application icon; using default
Unable to find icons/helloworld-87.png for 87px application icon; using default
Unable to find icons/helloworld-120.png for 120px application icon; using default
Unable to find icons/helloworld-152.png for 152px application icon; using default
Unable to find icons/helloworld-167.png for 167px application icon; using default
Unable to find icons/helloworld-180.png for 180px application icon; using default
Unable to find icons/helloworld-640.png for 640px application icon; using default
Unable to find icons/helloworld-1024.png for 1024px application icon; using default
Unable to find icons/helloworld-1280.png for 1280px application icon; using default
Unable to find icons/helloworld-1920.png for 1920px application icon; using default
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
Questo riporta il file (o i file) dell'icona specifica che Briefcase si aspetta. Tuttavia, poiché non abbiamo fornito i file delle icone, l'installazione fallisce e Briefcase torna al valore predefinito (la stessa icona "ape grigia").
Forniamo alcune icone reali. Scaricare questo bundle icons.zip e decomprimerlo nella cartella principale del progetto. Dopo la decompressione, la cartella del progetto dovrebbe avere un aspetto simile a:
beeware-tutorial/
├── beeware-venv/
│ └── ...
└── helloworld/
├── ...
├── icons/
│ ├── helloworld.icns
│ ├── helloworld.ico
│ ├── helloworld.png
│ ├── helloworld-16.png
│ └──...
├── src/
│ └── ...
└── pyproject.toml
Ci sono molte icone in questa cartella, ma la maggior parte di esse dovrebbe avere lo stesso aspetto: un serpente verde su uno sfondo azzurro:
![Icona di un serpente verde con sfondo azzurro] (../../images/icon.png)
L'unica eccezione è rappresentata dalle icone con il nome adaptive-, che
avranno uno sfondo trasparente. Questo rappresenta tutte le diverse dimensioni e
forme di icone necessarie per supportare un'applicazione su tutte le piattaforme
supportate da Briefcase.
Ora che abbiamo le icone, possiamo aggiornare di nuovo l'applicazione. Tuttavia,
briefcase update copierà solo le risorse aggiornate nella cartella di build;
vogliamo anche ricostruire l'applicazione per assicurarci che la nuova icona sia
inclusa, quindi avviare l'applicazione. Possiamo abbreviare questo processo
passando --update-resources alla nostra chiamata a run: questo aggiornerà
l'applicazione, aggiornerà le risorse dell'applicazione e poi la avvierà:
(beeware-venv) $ briefcase run --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Installing icons/helloworld.icns as application icon... done
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
[helloworld] Ad-hoc signing app...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 00:01
[helloworld] Built build/helloworld/macos/app/Hello World.app
[helloworld] Starting app...
(beeware-venv) $ briefcase run --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Installing icons/helloworld-16.png as 16px application icon... done
Installing icons/helloworld-32.png as 32px application icon... done
Installing icons/helloworld-64.png as 64px application icon... done
Installing icons/helloworld-128.png as 128px application icon... done
Installing icons/helloworld-256.png as 256px application icon... done
Installing icons/helloworld-512.png as 512px application icon... done
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
[helloworld] Building application...
Build bootstrap binary...
...
[helloworld] Built build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/bin/helloworld
[helloworld] Starting app...
(beeware-venv) C:\...>briefcase build --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Installing icons/helloworld.ico as application icon... done
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
[helloworld] Building App...
Removing any digital signatures from stub app... done
Setting stub app details... done
[helloworld] Built build\helloworld\windows\app\src\Hello World.exe
[helloworld] Starting app...
(beeware-venv) $ briefcase build android --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Installing icons/helloworld-round-48.png as 48px round application icon... done
Installing icons/helloworld-round-72.png as 72px round application icon... done
Installing icons/helloworld-round-96.png as 96px round application icon... done
Installing icons/helloworld-round-144.png as 144px round application icon... done
Installing icons/helloworld-round-192.png as 192px round application icon... done
Installing icons/helloworld-square-48.png as 48px square application icon... done
Installing icons/helloworld-square-72.png as 72px square application icon... done
Installing icons/helloworld-square-96.png as 96px square application icon... done
Installing icons/helloworld-square-144.png as 144px square application icon... done
Installing icons/helloworld-square-192.png as 192px square application icon... done
Installing icons/helloworld-square-320.png as 320px square application icon... done
Installing icons/helloworld-square-480.png as 480px square application icon... done
Installing icons/helloworld-square-640.png as 640px square application icon... done
Installing icons/helloworld-square-960.png as 960px square application icon... done
Installing icons/helloworld-square-1280.png as 1280px square application icon... done
Installing icons/helloworld-adaptive-108.png as 108px adaptive application icon... done
Installing icons/helloworld-adaptive-162.png as 162px adaptive application icon... done
Installing icons/helloworld-adaptive-216.png as 216px adaptive application icon... done
Installing icons/helloworld-adaptive-324.png as 324px adaptive application icon... done
Installing icons/helloworld-adaptive-432.png as 432px adaptive application icon... done
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
[helloworld] Starting app...
Nota
Se utilizzate una versione recente di Android, potreste notare che l'icona dell'app è stata cambiata in un serpente verde, ma lo sfondo dell'icona è bianco, anziché azzurro. Risolveremo questo problema nella fase successiva.
(beeware-venv) $ briefcase build iOS --update-resources
[helloworld] Updating application code...
Installing src/helloworld... done
[helloworld] Updating application resources...
Installing icons/helloworld-20.png as 20px application icon... done
Installing icons/helloworld-29.png as 29px application icon... done
Installing icons/helloworld-40.png as 40px application icon... done
Installing icons/helloworld-58.png as 58px application icon... done
Installing icons/helloworld-60.png as 60px application icon... done
Installing icons/helloworld-76.png as 76px application icon... done
Installing icons/helloworld-80.png as 80px application icon... done
Installing icons/helloworld-87.png as 87px application icon... done
Installing icons/helloworld-120.png as 120px application icon... done
Installing icons/helloworld-152.png as 152px application icon... done
Installing icons/helloworld-167.png as 167px application icon... done
Installing icons/helloworld-180.png as 180px application icon... done
Installing icons/helloworld-640.png as 640px application icon... done
Installing icons/helloworld-1024.png as 1024px application icon... done
Installing icons/helloworld-1280.png as 1280px application icon... done
Installing icons/helloworld-1920.png as 1920px application icon... done
[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done
[helloworld] Application updated.
[helloworld] Starting app...
Nota
Se si ottiene una traccia di stack che fa riferimento a faker o httpx quando
si esegue l'applicazione, è possibile che non si sia eseguita l'applicazione
durante i passi 7 o 8 del tutorial. Eseguire nuovamente l'applicazione,
aggiungendo l'argomento -r per aggiornare i requisiti dell'applicazione.
Quando si esegue l'app su iOS o Android, oltre al cambiamento dell'icona, si
dovrebbe notare che lo splash screen incorpora la nuova icona. Tuttavia, lo
sfondo azzurro dell'icona sembra un po' fuori luogo rispetto allo sfondo bianco
della schermata iniziale. È possibile risolvere il problema personalizzando il
colore di sfondo della schermata iniziale. Aggiungere la seguente definizione al
file pyproject.toml, subito dopo la definizione icon:
splash_background_color = "#D3E6F5"
Sfortunatamente, Briefcase non è in grado di applicare questa modifica a un
progetto già generato, perché richiede la modifica di uno dei file generati
durante la chiamata originale a briefcase create. Per applicare questa
modifica, dobbiamo ricreare l'applicazione eseguendo nuovamente briefcase
create. Quando lo facciamo, ci verrà chiesto di confermare che vogliamo
sovrascrivere il progetto esistente:
(beeware-venv) $ briefcase create
Application 'helloworld' already exists; overwrite [y/N]? y
[helloworld] Removing old application bundle...
[helloworld] Generating application template...
...
[helloworld] Created build/helloworld/macos/app
(beeware-venv) $ briefcase create
Application 'helloworld' already exists; overwrite [y/N]? y
[helloworld] Removing old application bundle...
[helloworld] Generating application template...
...
[helloworld] Created build/helloworld/linux/ubuntu/jammy
(beeware-venv) C:\...>briefcase create
Application 'helloworld' already exists; overwrite [y/N]? y
[helloworld] Removing old application bundle...
[helloworld] Generating application template...
...
[helloworld] Created build\helloworld\windows\app
(beeware-venv) $ briefcase create android
Application 'helloworld' already exists; overwrite [y/N]? y
[helloworld] Removing old application bundle...
[helloworld] Generating application template...
...
[helloworld] Created build/helloworld/android/gradle
(beeware-venv) $ briefcase create iOS
Application 'helloworld' already exists; overwrite [y/N]? y
[helloworld] Removing old application bundle...
[helloworld] Generating application template...
...
[helloworld] Created build/helloworld/ios/xcode
È quindi possibile ricostruire ed eseguire nuovamente l'applicazione utilizzando
briefcase run. Non si noterà alcun cambiamento nell'applicazione desktop, ma
le applicazioni per Android o iOS dovrebbero ora avere uno sfondo azzurro.
Sarà necessario ricreare l'applicazione in questo modo ogni volta che si apporta
una modifica a pyproject.toml che non riguarda il codice sorgente o le
dipendenze. Qualsiasi modifica alle descrizioni, ai numeri di versione, ai
colori o ai permessi richiederà una nuova creazione. Per questo motivo, durante
lo sviluppo del progetto, non si dovrebbero apportare modifiche manuali al
contenuto della cartella build e non si dovrebbe aggiungere la cartella
build al sistema di controllo di versione. La cartella build deve essere
considerata del tutto effimera, un output del sistema di compilazione che può
essere ricreato secondo le necessità per riflettere la configurazione corrente
del progetto.
Aggiunta di un'icona di runtime¶
Quando si tratta di aggiungere un'icona all'interfaccia dell'applicazione,
questo tipo di icona deve essere memorizzata in una directory separata dalle
icone dell'applicazione. Cliccate con il tasto destro del mouse su Tiberius lo
yak, salvate l'immagine come file .png e chiamatela helloworld. Il file deve
essere salvato nella cartella icons/ del pacchetto sorgente dell'applicazione.
La directory avrà l'aspetto seguente:
beeware-tutorial/
├── beeware-venv/
│ └── ...
└── helloworld/
├── ...
├── icons/
│ ├── helloworld.icns
│ ├── helloworld.ico
│ ├── helloworld.png
│ ├── helloworld-16.png
│ └──...
├── src/
│ ├── helloworld
│ │ └── icons/
│ │ └── helloworld.png
│ └──...
└── pyproject.toml
Ora che l'icona di runtime è pronta, aggiungiamo un'icona al nostro pulsante. Il widget del pulsante di Toga può contenere solo un'icona o del testo (non entrambi), quindi aggiorniamo il codice del pulsante per includere l'icona di runtime.
helloworld_icon = toga.Icon("icons/helloworld")
button = toga.Button(
icon=helloworld_icon,
on_press=self.say_hello,
margin=5,
)
Poiché le icone di runtime sono risorse dell'applicazione incluse nel pacchetto
Python, non è necessario ricostruire o aggiornare le risorse. A questo punto si
può eseguire briefcase dev (o briefcase run) per vedere l'icona aggiunta al
pulsante.