Customizing icons¶
到目前为止,我们的应用程序一直使用默认的 "灰色蜜蜂 "图标。如何更新应用程序,使用我们自己的图标?
添加图标¶
Every platform uses a different format for application icons - and some platforms need multiple icons in different sizes and shapes. To account for this, Briefcase provides a shorthand way to configure an icon once, and then have that definition expand in to all the different icons needed for each individual platform.
Edit your pyproject.toml
, adding a new icon
configuration item in the
[tool.briefcase.app.helloworld]
configuration section, just above the
sources
definition:
icon = "icons/helloworld"
This icon definition doesn't specify any file extension. The value will be used as a prefix; each platform will add additional items to this prefix to build the files needed for each platform. Some platforms require multiple icon files; this prefix will be combined with file size and variant modifiers to generate the list of icon files that are used.
We can now run briefcase update
again - but this time, we pass in the
--update-resources
flag, telling Briefcase that we want to install new
application resources (i.e., the icons):
(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.
This reports the specific icon file (or files) that Briefcase is expecting. However, as we haven't provided the actual icon files, the install fails, and Briefcase falls back to a default value (the same "gray bee" icon).
Let's provide some actual icons. Download this icons.zip bundle
, and unpack it into the root of your project
directory. After unpacking, your project directory should look something like:
beeware-tutorial/
├── beeware-venv/
│ └── ...
└── helloworld/
├── ...
└── pyproject.toml
├── icons/
│ ├── helloworld.icns
│ ├── helloworld.ico
│ ├── helloworld.png
│ ├── helloworld-16.png
│ ├── ...
└── src/
└── ...
There's a lot of icons in this folder, but most of them should look the same: a green snake on a light blue background:
The only exception will be the icons with -adaptive-
in their name; these
will have a transparent background. This represents all the different icon sizes
and shapes you need to support an app on every platform that Briefcase supports.
Now that we have icons, we can update the application again. However,
briefcase update
will only copy the updated resources into the build
directory; we also want to rebuild the app to make sure the new icon is
included, then start the app. We can shortcut this process by passing
--update-resources
to our call to run
- this will update the app, update
the app's resources, and then start the app:
(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...
备注
If you're using a recent version of Android, you may notice that the app icon has been changed to a green snake, but the background of the icon is white, rather than light blue. We'll fix this in the next step.
(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...
When you run the app on iOS or Android, in addition to the icon change, you
should also notice that the splash screen incorporates the new icon. However,
the light blue background of the icon looks a little out of place against the
white background of the splash screen. We can fix this by customizing the
background color of the splash screen. Add the following definition to your
pyproject.toml
, just after the icon
definition:
splash_background_color = "#D3E6F5"
Unfortunately, Briefcase isn't able to apply this change to an already generated
project, as it requires making modifications to one of the files that was
generated during the original call to briefcase create
. To apply this
change, we have to re-create the app by re-running briefcase create
. When we
do this, we'll be prompted to confirm that we want to overwrite the existing
project:
(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
You can then re-build and re-run the app using briefcase run
. You won't
notice any changes to the desktop app; but the Android or iOS apps should now
have a light blue splash screen background.
You'll need to re-create the app like this whenever you make a change to your
pyproject.toml
that doesn't relate to source code or dependencies. Any
change to descriptions, version numbers, colors, or permissions will require a
re-create step. Because of this, while you are developing your project, you
shouldn't make any manual changes to the contents of the build
folder, and
you shouldn't add the build
folder to your version control system. The
build
folder should be considered entirely ephemeral - an output of the
build system that can be recreated as needed to reflect the current
configuration of your project.