Personalização de ícones¶
Até agora, nosso aplicativo tem usado um ícone padrão de "abelha cinza". Como podemos atualizar o aplicativo para usar nosso próprio ícone?
Observação
No BeeWare, o termo ícone pode se referir a duas coisas diferentes:
-
Ícone do aplicativo - A imagem que representa seu aplicativo na área de trabalho, no dock ou na tela inicial.
-
Ícones de tempo de execução - Imagens usadas na interface do seu aplicativo (por exemplo, em botões ou tabelas).
Adição de um ícone¶
Cada plataforma usa um formato diferente para os ícones de aplicativos, e algumas plataformas precisam de vários ícones em diferentes tamanhos e formas. Para levar isso em conta, o Briefcase oferece uma maneira abreviada de configurar um ícone uma vez e, em seguida, expandir essa definição para todos os diferentes ícones necessários para cada plataforma individual.
Edite seu pyproject.toml, adicionando um novo item de configuração icon na
seção de configuração [tool.briefcase.app.helloworld], logo acima da definição
sources:
icon = "icons/helloworld"
Essa definição de ícone não especifica nenhuma extensão de arquivo. O valor será usado como um prefixo; cada plataforma acrescentará itens adicionais a esse prefixo para criar os arquivos necessários para cada plataforma. Algumas plataformas exigem múltiplos arquivos de ícones; esse prefixo será combinado com o tamanho do arquivo e modificadores de variantes para gerar a lista de arquivos de ícones que são usados.
Agora podemos executar o briefcase update novamente, mas, dessa vez, passamos
o sinalizador --update-resources, informando ao Briefcase que queremos
instalar novos recursos do aplicativo (ou seja, os ícones):
(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.
Isso informa o arquivo (ou arquivos) de ícone específico que o Briefcase está esperando. No entanto, como não fornecemos os arquivos de ícone reais, a instalação falha e o Briefcase retorna ao valor padrão (o mesmo ícone de "abelha cinza").
Vamos fornecer alguns ícones reais. Baixe este pacote icons.zip e descompacte-o na raiz do diretório do projeto. Após a descompactação, seu diretório de projeto deverá ter a seguinte aparência
beeware-tutorial/
├── beeware-venv/
│ └── ...
└── helloworld/
├── ...
├── icons/
│ ├── helloworld.icns
│ ├── helloworld.ico
│ ├── helloworld.png
│ ├── helloworld-16.png
│ └──...
├── src/
│ └── ...
└── pyproject.toml
Há muitos ícones nessa pasta, mas a maioria deles deve ter a mesma aparência: uma cobra verde em um fundo azul claro:
A única exceção serão os ícones com -adaptive- em seu nome; eles terão um
fundo transparente. Isso representa todos os diferentes tamanhos e formas de
ícones necessários para suportar um aplicativo em todas as plataformas
suportadas pelo Briefcase.
Agora que temos os ícones, podemos atualizar o aplicativo novamente. No entanto,
o briefcase update copiará apenas os recursos atualizados para o diretório de
compilação; também queremos reconstruir o aplicativo para garantir que o novo
ícone seja incluído e, em seguida, iniciar o aplicativo. Podemos encurtar esse
processo passando --update-resources para a nossa chamada para run - isso
atualizará o aplicativo, atualizará os recursos do aplicativo e, em seguida,
iniciará o aplicativo:
(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...
Observação
Se você estiver usando uma versão recente do Android, poderá notar que o ícone do aplicativo foi alterado para uma cobra verde, mas o fundo do ícone é branco, em vez de azul claro. Vamos corrigir isso na próxima etapa.
(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...
Observação
Se você obtiver um rastreamento de pilha referenciando faker ou httpx ao
executar o aplicativo, é possível que você não tenha executado o aplicativo
durante as etapas 7 ou 8 do tutorial. Execute o aplicativo novamente,
adicionando o argumento -r para atualizar os requisitos do aplicativo.
Ao executar o aplicativo no iOS ou Android, além da alteração do ícone, você
também deve notar que a tela inicial incorpora o novo ícone. No entanto, o fundo
azul claro do ícone parece um pouco deslocado em relação ao fundo branco da tela
inicial. Podemos corrigir isso personalizando a cor de fundo da tela inicial.
Adicione a seguinte definição ao seu pyproject.toml, logo após a definição
icon:
splash_background_color = "#D3E6F5"
Infelizmente, o Briefcase não é capaz de aplicar essa alteração a um projeto já
gerado, pois isso requer modificações em um dos arquivos que foi gerado durante
a chamada original do briefcase create. Para aplicar essa alteração, temos que
recriar o aplicativo executando novamente o briefcase create. Quando fizermos
isso, seremos solicitados a confirmar que queremos substituir o projeto
existente:
(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
Em seguida, você pode recompilar e executar novamente o aplicativo usando o
briefcase run. Você não notará nenhuma alteração no aplicativo para desktop,
mas os aplicativos para Android ou iOS agora devem ter um fundo de tela inicial
azul claro.
Você precisará recriar o aplicativo dessa forma sempre que fizer uma alteração
em seu pyproject.toml que não esteja relacionada ao código-fonte ou às
dependências. Qualquer alteração em descrições, números de versão, cores ou
permissões exigirá uma etapa de recriação. Por esse motivo, enquanto estiver
desenvolvendo o projeto, você não deve fazer nenhuma alteração manual no
conteúdo da pasta build e não deve adicionar a pasta build ao seu sistema de
controle de versão. A pasta build deve ser considerada totalmente efêmera, uma
saída do sistema de compilação que pode ser recriada conforme necessário para
refletir a configuração atual do seu projeto.
Adição de um ícone de tempo de execução¶
Quando se trata de adicionar um ícone à interface do aplicativo, esse tipo de
ícone deve ser armazenado em um diretório separado dos ícones do aplicativo.
Clique com o botão direito do mouse em Tiberius the yak, salve a imagem como um
arquivo .png e nomeie-a helloworld. O arquivo deve ser salvo na pasta
icons/ do pacote de código-fonte do aplicativo.
Seu diretório se parecerá com o seguinte:
beeware-tutorial/
├── beeware-venv/
│ └── ...
└── helloworld/
├── ...
├── icons/
│ ├── helloworld.icns
│ ├── helloworld.ico
│ ├── helloworld.png
│ ├── helloworld-16.png
│ └──...
├── src/
│ ├── helloworld
│ │ └── icons/
│ │ └── helloworld.png
│ └──...
└── pyproject.toml
Agora que o ícone de tempo de execução está no lugar, vamos adicionar um ícone ao nosso botão. O widget do botão Toga só acomoda um ícone ou texto (não ambos), portanto, vamos atualizar o código do botão para incluir o ícone de tempo de execução.
helloworld_icon = toga.Icon("icons/helloworld")
button = toga.Button(
icon=helloworld_icon,
on_press=self.say_hello,
margin=5,
)
Como os ícones de tempo de execução são recursos do aplicativo incluídos no
pacote Python, não é necessário reconstruir ou atualizar o recurso. Nesse ponto,
você pode executar o briefcase dev (ou briefcase run) para ver o ícone
adicionado ao botão.