1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page appicon.html
\title Setting the Application Icon
\brief How to set your application's icon.
\ingroup best-practices
The application icon, typically displayed in the top-left corner of an
application's top-level windows, is set by calling the
QWindow::setIcon() method.
In order to change the icon of the executable application file
itself, as it is presented on the desktop (that is, prior to
application launch), it is necessary to employ another,
platform-dependent technique.
\tableofcontents
\section1 Setting the Application Icon on Windows
First, create an ICO format bitmap file that contains the icon
image. This can be done using Microsoft Visual Studio: Select
\uicontrol{File >> New}, and choose the \uicontrol{Icon File}.
\note You need not load the application into the Visual Studio IDE as you
are using the icon editor only.
Alternatively, an \c .ico file can be created from a set of images using
ImageMagick's \l {https://imagemagick.org/script/convert.php}{convert}
tool:
\badcode
magick.exe convert icon-16.png icon-32.png icon-256.png icon.ico
\endcode
Store the ICO file in your application's source code directory,
for example, with the name \c appico.ico.
\section2 Using CMake on Windows
To configure your application's icon, a resource file containing
information about the icon is required. A resource file is a text
file that contains information about the application
resources, such as icons, cursors, fonts, and so on. For
more information about resource files and what it can contain, see
\l{https://docs.microsoft.com/en-us/windows/win32/menurc/about-resource-files}{About Resource Files}.
Once you have the \c .rc file, add information about the ICO file to it and
use it to configure your application icon.
The following snippet demonstrates how the \l{Photo Surface}
example application uses CMake to set up an application icon:
\snippet demos/photosurface/CMakeLists.txt appicon_windows
Notice that the \c set command, defines the \c app_icon_windows
variable, which contains the path of the RC file. This variable is used
with the \c add_executable command to set the application's icon.
\section2 Using qmake on Windows
If you are still using qmake to generate your makefiles,
you need to add a single line to your \c .pro project file:
\snippet snippets/code/doc_src_appicon.pro 0
Finally, regenerate your makefile and your application. The \c .exe file
will now be represented by your icon in Explorer.
However, if you already have an \c .rc file, for example, with the name
\c myapp.rc, which you want to reuse, the following two steps will be
required. First, put a single line of text to the \c myapp.rc file:
\snippet snippets/code/doc_src_appicon.qdoc 0
Then, add this line to your \c myapp.pro file:
\snippet snippets/code/doc_src_appicon.pro 1
If you do not use \c qmake, the necessary steps are: first, create an
\c .rc file and run the \c rc or \c windres program on the \c .rc file,
then link your application with the resulting \c .res file.
\section1 Setting the Application Icon on \macos
The application icon, typically displayed in the application dock
area, is set by calling QWindow::setWindowIcon() on a window. It is
possible that the program could appear in the application dock area
before the function call, in which case a default icon will appear
during the bouncing animation.
To ensure that the correct icon appears, both when the application is
being launched, and in the Finder, it is necessary to employ a
platform-dependent technique.
Although many programs can create icon files (\c .icns), the
recommended approach is to use the \e{iconutil} program
supplied by Apple. \e{iconutil} is a command-line tool that
converts iconset folders to deployment-ready, high-resolution
icns files. Using this tool also compresses the resulting icns file,
so there is no need for you to perform additional compression.
\section2 Using CMake on \macos
To configure the application's icon, the \c Info.plist file generated
by CMake must contain the icon information. This can be achieved by
setting the \c .icns file name to the \c MACOSX_BUNDLE_ICON_FILE variable.
The following snippet demonstrates how the \l{Photo Surface}
example application uses CMake to set up an application icon:
\snippet demos/photosurface/CMakeLists.txt appicon_macOS
Notice that the first \c set command defines the \c MACOSX_BUNDLE_ICON_FILE
variable, which is required to add the icon file to the \c Info.plist file.
The second \c set command defines the \c app_icon_macos variable with the
absolute path to the icon file. This variable is then used to configure
MACOSX_PACKAGE_LOCATION, which defines the icon file's install location.
Finally, the \c add_executable uses the \c app_icon_macOS variable to set
the application's icon.
\section2 Using qmake on \macos
If you are still using qmake to generate your makefiles, you only need
to add a single line to your \c .pro project file. For example,
if the name of your icon file is \c{myapp.icns}, and your project
file is \c{myapp.pro}, add this line to \c{myapp.pro}:
\snippet snippets/code/doc_src_appicon.pro 2
This will ensure that \c qmake puts your icons in the proper
place and creates an \c{Info.plist} entry for the icon.
If you do not use \c qmake, you must do the following manually:
\list 1
\li Create an \c Info.plist file for your application (using the
\c PropertyListEditor, found in \c Developer/Applications).
\li Associate your \c .icns record with the \c CFBundleIconFile record in the
\c Info.plist file (again, using the \c PropertyListEditor).
\li Copy the \c Info.plist file into your application bundle's \c Contents
directory.
\li Copy the \c .icns file into your application bundle's \c Contents/Resources
directory.
\endlist
\section1 Setting the Application Icon on Common Linux Desktops
In this section we briefly describe the issues involved in providing
icons for applications for two common Linux desktop environments:
\l{http://www.kde.org/}{KDE} and \l{http://www.gnome.org/}{GNOME}.
The core technology used to describe application icons
is the same for both desktops, and may also apply to others, but there
are details which are specific to each. The main source of information
on the standards used by these Linux desktops is
\l{http://www.freedesktop.org/}{freedesktop.org}. For information
on other Linux desktops please refer to the documentation for the
desktops you are interested in.
Often, users do not use executable files directly, but instead launch
applications by clicking icons on the desktop. These icons are
representations of "desktop entry files" that contain a description of
the application that includes information about its icon. Both desktop
environments are able to retrieve the information in these files, and
they use it to generate shortcuts to applications on the desktop, in
the start menu, and on the panel.
More information about desktop entry files can be found in the
\l{http://www.freedesktop.org/Standards/desktop-entry-spec}{Desktop Entry
Specification}.
Although desktop entry files can usefully encapsulate the application's details,
we still need to store the icons in the conventional location for each desktop
environment. A number of locations for icons are given in the
\l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme
Specification}.
Although the path used to locate icons depends on the desktop in use,
and on its configuration, the directory structure beneath each of
these should follow the same pattern: subdirectories are arranged by
theme, icon size, and application type. Generally, application icons
are added to the hicolor theme, so a square application icon 32 pixels
in size would be stored in the \c hicolor/32x32/apps directory beneath
the icon path.
\section2 K Desktop Environment (KDE)
Application icons can be installed for use by all users, or on a per-user basis.
A user currently logged into their KDE 4 desktop can discover these locations
by using kde4-config, for example, by typing the following in a terminal window:
\snippet snippets/code/doc_src_appicon.qdoc 3
Applications using Qt 5 and KDE Frameworks 5 will find their icons in the list
returned by this command:
\snippet snippets/code/doc_src_appicon.qdoc 5
Typically, the list of colon-separated paths printed to stdout includes the
user-specific icon path and the system-wide path. Beneath these
directories, it should be possible to locate and install icons according
to the conventions described in the
\l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme Specification}.
If you are developing exclusively for KDE, you may wish to take
advantage of the \link
http://techbase.kde.org/Development/CMake/Addons_for_KDE
KDE build system\endlink to configure your application. This ensures
that your icons are installed in the appropriate locations for KDE.
The KDE developer website is at \l{http://techbase.kde.org/}.
\section2 GNOME
Application icons are stored within a standard system-wide
directory containing architecture-independent files. This
location can be determined by using \c gnome-config, for example
by typing the following in a terminal window:
\snippet snippets/code/doc_src_appicon.qdoc 4
The path printed on stdout refers to a location that should contain a directory
called \c{pixmaps}; the directory structure within the \c pixmaps
directory is described in the \link
http://www.freedesktop.org/Standards/icon-theme-spec Icon Theme
Specification \endlink.
If you are developing exclusively for GNOME, you may want to use the
standard set of GNU Build Tools. For more information, see the
\l{https://developer.gnome.org/documentation/guidelines/maintainer/integrating.html?highlight=application%20icons#icons}{Integration
Guidelines} section. This ensures that your icons are installed in the
appropriate locations for GNOME.
The GNOME developer website, \l{http://developer.gnome.org/}, provides
more insight into developing applications.
*/
|
