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

macOSLinuxWindowsAndroidiOS

(beeware-venv) $ briefcase update --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Impossibile trovare icons/helloworld.icns per l'icona dell'applicazione; utilizzo dell'icona predefinita

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... completata

[helloworld] Applicazione aggiornata.

(beeware-venv) $ briefcase update --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Impossibile trovare icons/helloworld-16.png per l'icona dell'applicazione da 16 px; si utilizza quella predefinita
Impossibile trovare icons/helloworld-32.png per l'icona dell'applicazione da 32px; utilizzo quella predefinita
Impossibile trovare icons/helloworld-64.png per l'icona dell'applicazione da 64px; utilizzo quella predefinita
Impossibile trovare icons/helloworld-128.png per l'icona dell'applicazione da 128px; utilizzo quella predefinita
Impossibile trovare icons/helloworld-256.png per l'icona dell'applicazione da 256px; utilizzo quella predefinita
Impossibile trovare icons/helloworld-512.png per l'icona dell'applicazione da 512px; utilizzo quella predefinita

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... fatto

[helloworld] Applicazione aggiornata.

(beeware-venv) C:\...>briefcase update --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Impossibile trovare icons/helloworld.ico per l'icona dell'applicazione; utilizzo di quella predefinita

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... completata

[helloworld] Applicazione aggiornata.

(beeware-venv) $ briefcase update android --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Impossibile trovare icons/helloworld-round-48.png per l'icona rotonda dell'applicazione da 48 px; utilizzo dell'icona predefinita
Impossibile trovare icons/helloworld-round-72.png per l'icona dell'applicazione rotonda da 72px; utilizzo quella predefinita
Impossibile trovare icons/helloworld-round-96.png per l'icona dell'applicazione rotonda da 96px; utilizzo quella predefinita
Impossibile trovare icons/helloworld-round-144.png per l'icona dell'applicazione rotonda da 144px; utilizzo quella predefinita
Impossibile trovare icons/helloworld-round-192.png per l'icona dell'applicazione rotonda da 192px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-square-48.png per l'icona dell'applicazione quadrata da 48px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-square-72.png per l'icona dell'applicazione quadrata da 72px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-square-96.png per l'icona dell'applicazione quadrata da 96px; si utilizza quella predefinita
Impossibile trovare icons/helloworld-square-144.png per l'icona dell'applicazione quadrata da 144px; si utilizza quella predefinita
Impossibile trovare icons/helloworld-square-192.png per l'icona dell'applicazione quadrata da 192px; si utilizza quella predefinita
Impossibile trovare icons/helloworld-square-320.png per l'icona dell'applicazione quadrata da 320px; si utilizza quella predefinita
Impossibile trovare icons/helloworld-square-480.png per l'icona dell'applicazione quadrata da 480px; si utilizza quella predefinita
Impossibile trovare icons/helloworld-square-640.png per l'icona dell'applicazione quadrata da 640px; si utilizza quella predefinita
Impossibile trovare icons/helloworld-square-960.png per l'icona dell'applicazione quadrata da 960px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-square-1280.png per l'icona dell'applicazione quadrata da 1280px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-adaptive-108.png per l'icona dell'applicazione adattiva da 108px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-adaptive-162.png per l'icona dell'applicazione adattiva da 162px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-adaptive-216.png per l'icona dell'applicazione adattiva da 216px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-adaptive-324.png per l'icona dell'applicazione adattiva da 324px; utilizzo di quella predefinita
Impossibile trovare icons/helloworld-adaptive-432.png per l'icona dell'applicazione adattiva da 432px; utilizzo dell'icona predefinita

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... fatto

[helloworld] Applicazione aggiornata.

(beeware-venv) $ briefcase iOS --update-resources

  [helloworld] Aggiornamento del codice dell'applicazione...
  Installazione di src/helloworld... completata

  [helloworld] Aggiornamento delle risorse dell'applicazione...
  Impossibile trovare icons/helloworld-20.png per l'icona dell'applicazione da 20px; utilizzo quella predefinita
  Impossibile trovare icons/helloworld-29.png per l'icona dell'applicazione da 29px; utilizzo quella predefinita
  Impossibile trovare icons/helloworld-40.png per l'icona dell'applicazione da 40px; utilizzo quella predefinita
  Impossibile trovare icons/helloworld-58.png per l'icona dell'applicazione da 58px; utilizzo di quella predefinita
  Impossibile trovare icons/helloworld-60.png per l'icona dell'applicazione da 60px; utilizzo di quella predefinita
  Impossibile trovare icons/helloworld-76.png per l'icona dell'applicazione da 76px; utilizzo di quella predefinita
  Impossibile trovare icons/helloworld-80.png per l'icona dell'applicazione da 80px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-87.png per l'icona dell'applicazione da 87px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-120.png per l'icona dell'applicazione da 120px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-152.png per l'icona dell'applicazione da 152px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-167.png per l'icona dell'applicazione da 167px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-180.png per l'icona dell'applicazione da 180px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-640.png per l'icona dell'applicazione da 640px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-1024.png per l'icona dell'applicazione da 1024px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-1280.png per l'icona dell'applicazione da 1280px; si utilizza quella predefinita
  Impossibile trovare icons/helloworld-1920.png per l'icona dell'applicazione da 1920px; utilizzo dell'icona predefinita

  [helloworld] Rimozione dei contenuti non necessari dell'app...
  Rimozione dei contenuti non necessari del bundle dell'app... fatto

  [helloworld] Applicazione aggiornata.

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

macOSLinuxWindowsAndroidiOS

(beeware-venv) $ briefcase run --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Installazione di icons/helloworld.icns come icona dell'applicazione... fatto

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... fatto

[helloworld] Applicazione aggiornata.

[helloworld] Firma ad hoc dell'app...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100,0% • 00:01

[helloworld] Creata build/helloworld/macos/app/Hello World.app

[helloworld] Avvio dell'app...

(beeware-venv) $ briefcase run --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Installazione di icons/helloworld-16.png come icona dell'applicazione da 16 px... completata
Installazione di icons/helloworld-32.png come icona dell'applicazione da 32px... fatto
Installazione di icons/helloworld-64.png come icona dell'applicazione da 64px... fatto
Installazione di icons/helloworld-128.png come icona dell'applicazione da 128px... fatto
Installazione di icons/helloworld-256.png come icona dell'applicazione da 256px... fatto
Installazione di icons/helloworld-512.png come icona dell'applicazione da 512px... fatto

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... fatto

[helloworld] Applicazione aggiornata.

[helloworld] Compilazione dell'applicazione...
Compilazione del binario bootstrap...
...

[helloworld] Compilato build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/bin/helloworld

[helloworld] Avvio dell'app...

(beeware-venv) C:\...>briefcase build --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Installazione di icons/helloworld.ico come icona dell'applicazione... fatto

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... fatto

[helloworld] Applicazione aggiornata.

[helloworld] Creazione dell'app...
Rimozione di eventuali firme digitali dall'app stub... fatto
Impostazione dei dettagli dell'app stub... fatto

[helloworld] Creato build\helloworld\windows\app\src\Hello World.exe

[helloworld] Avvio dell'app...

(beeware-venv) $ briefcase build android --update-resources

[helloworld] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Installazione di icons/helloworld-round-48.png come icona dell'applicazione rotonda da 48 px... completata
Installazione di icons/helloworld-round-72.png come icona dell'applicazione rotonda da 72px... fatto
Installazione di icons/helloworld-round-96.png come icona dell'applicazione rotonda da 96px... fatto
Installazione di icons/helloworld-round-144.png come icona dell'applicazione rotonda da 144px... fatto
Installazione di icons/helloworld-round-192.png come icona dell'applicazione rotonda da 192px... fatto
Installazione di icons/helloworld-square-48.png come icona dell'applicazione quadrata da 48px... fatto
Installazione di icons/helloworld-square-72.png come icona dell'applicazione quadrata da 72px... fatto
Installazione di icons/helloworld-square-96.png come icona dell'applicazione quadrata da 96px... fatto
Installazione di icons/helloworld-square-144.png come icona dell'applicazione quadrata da 144px... fatto
Installazione di icons/helloworld-square-192.png come icona dell'applicazione quadrata da 192px... fatto
Installazione di icons/helloworld-square-320.png come icona dell'applicazione quadrata da 320px... fatto
Installazione di icons/helloworld-square-480.png come icona dell'applicazione quadrata da 480px... fatto
Installazione di icons/helloworld-square-640.png come icona dell'applicazione quadrata da 640px... fatto
Installazione di icons/helloworld-square-960.png come icona dell'applicazione quadrata da 960px... fatto
Installazione di icons/helloworld-square-1280.png come icona dell'applicazione quadrata da 1280px... fatto
Installazione di icons/helloworld-adaptive-108.png come icona dell'applicazione adattiva da 108px... fatto
Installazione di icons/helloworld-adaptive-162.png come icona dell'applicazione adattiva da 162px... fatto
Installazione di icons/helloworld-adaptive-216.png come icona dell'applicazione adattiva da 216px... fatto
Installazione di icons/helloworld-adaptive-324.png come icona dell'applicazione adattiva da 324px... fatto
Installazione di icons/helloworld-adaptive-432.png come icona dell'applicazione adattiva da 432px... fatto

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... fatto

[helloworld] Applicazione aggiornata.

[helloworld] Avvio dell'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] Aggiornamento del codice dell'applicazione...
Installazione di src/helloworld... completata

[helloworld] Aggiornamento delle risorse dell'applicazione...
Installazione di icons/helloworld-20.png come icona dell'applicazione da 20px... fatto
Installazione di icons/helloworld-29.png come icona dell'applicazione da 29px... fatto
Installazione di icons/helloworld-40.png come icona dell'applicazione da 40px... fatto
Installazione di icons/helloworld-58.png come icona dell'applicazione da 58px... fatto
Installazione di icons/helloworld-60.png come icona dell'applicazione da 60px... fatto
Installazione di icons/helloworld-76.png come icona dell'applicazione da 76px... fatto
Installazione di icons/helloworld-80.png come icona dell'applicazione da 80px... fatto
Installazione di icons/helloworld-87.png come icona dell'applicazione da 87px... fatto
Installazione di icons/helloworld-120.png come icona dell'applicazione da 120px... fatto
Installazione di icons/helloworld-152.png come icona dell'applicazione da 152px... fatto
Installazione di icons/helloworld-167.png come icona dell'applicazione da 167px... fatto
Installazione di icons/helloworld-180.png come icona dell'applicazione da 180px... fatto
Installazione di icons/helloworld-640.png come icona dell'applicazione da 640px... fatto
Installazione di icons/helloworld-1024.png come icona dell'applicazione da 1024px... fatto
Installazione di icons/helloworld-1280.png come icona dell'applicazione da 1280px... fatto
Installazione di icons/helloworld-1920.png come icona dell'applicazione da 1920px... fatto

[helloworld] Rimozione dei contenuti non necessari dell'app...
Rimozione dei contenuti non necessari del bundle dell'app... fatto

[helloworld] Applicazione aggiornata.

[helloworld] Avvio dell'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:

macOSLinuxWindowsAndroidiOS

(beeware-venv) $ briefcase create

L'applicazione "helloworld" esiste già; sovrascrivere [s/N]? s

[helloworld] Rimozione del vecchio pacchetto dell'applicazione...

[helloworld] Generazione del modello dell'applicazione...
...

[helloworld] Creato build/helloworld/macos/app

(beeware-venv) $ briefcase create

L'applicazione "helloworld" esiste già; sovrascrivere [s/N]? s

[helloworld] Rimozione del vecchio pacchetto dell'applicazione...

[helloworld] Generazione del modello dell'applicazione...
...

[helloworld] Creato build/helloworld/linux/ubuntu/jammy

(beeware-venv) C:\...>briefcase create

L'applicazione "helloworld" esiste già; sovrascrivere [s/N]? s

[helloworld] Rimozione del vecchio pacchetto dell'applicazione...

[helloworld] Generazione del modello dell'applicazione...
...

[helloworld] Creato build\helloworld\windows\app

(beeware-venv) $ briefcase create android

L'applicazione "helloworld" esiste già; sovrascrivere [s/N]? s

[helloworld] Rimozione del vecchio bundle dell'applicazione...

[helloworld] Generazione del modello dell'applicazione...
...
[helloworld] Creato build/helloworld/android/gradle

(beeware-venv) $ briefcase create iOS

L'applicazione "helloworld" esiste già; sovrascrivere [s/N]? s

[helloworld] Rimozione del vecchio pacchetto dell'applicazione...

[helloworld] Generazione del modello dell'applicazione...
...
[helloworld] Creato 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.