|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \page appicon.html |
|
44 \title Setting the Application Icon |
|
45 |
|
46 \ingroup best-practices |
|
47 |
|
48 The application icon, typically displayed in the top-left corner of an |
|
49 application's top-level windows, is set by calling the |
|
50 QWidget::setWindowIcon() method on top-level widgets. |
|
51 |
|
52 In order to change the icon of the executable application file |
|
53 itself, as it is presented on the desktop (i.e., prior to |
|
54 application execution), it is necessary to employ another, |
|
55 platform-dependent technique. |
|
56 |
|
57 \tableofcontents |
|
58 |
|
59 \section1 Setting the Application Icon on Windows |
|
60 |
|
61 First, create an ICO format bitmap file that contains the icon |
|
62 image. This can be done with e.g. Microsoft Visual C++: Select |
|
63 \menu{File|New}, then select the \menu{File} tab in the dialog |
|
64 that appears, and choose \menu{Icon}. (Note that you do not need |
|
65 to load your application into Visual C++; here we are only using |
|
66 the icon editor.) |
|
67 |
|
68 Store the ICO file in your application's source code directory, |
|
69 for example, with the name \c myappico.ico. Then, create a text |
|
70 file called, say, \c myapp.rc in which you put a single line of |
|
71 text: |
|
72 |
|
73 \snippet doc/src/snippets/code/doc_src_appicon.qdoc 0 |
|
74 |
|
75 Finally, assuming you are using \c qmake to generate your |
|
76 makefiles, add this line to your \c myapp.pro file: |
|
77 |
|
78 \snippet doc/src/snippets/code/doc_src_appicon.qdoc 1 |
|
79 |
|
80 Regenerate your makefile and your application. The \c .exe file |
|
81 will now be represented with your icon in Explorer. |
|
82 |
|
83 If you do not use \c qmake, the necessary steps are: first, run |
|
84 the \c rc program on the \c .rc file, then link your application |
|
85 with the resulting \c .res file. |
|
86 |
|
87 \section1 Setting the Application Icon on Mac OS X |
|
88 |
|
89 The application icon, typically displayed in the application dock |
|
90 area, is set by calling QWidget::setWindowIcon() on a top-level |
|
91 widget. It is possible that the program could appear in the |
|
92 application dock area before the function call, in which case a |
|
93 default icon will appear during the bouncing animation. |
|
94 |
|
95 To ensure that the correct icon appears, both when the application is |
|
96 being launched, and in the Finder, it is necessary to employ a |
|
97 platform-dependent technique. |
|
98 |
|
99 Although many programs can create icon files (\c .icns), the |
|
100 recommended approach is to use the \e{Icon Composer} program |
|
101 supplied by Apple (in the \c Developer/Application folder). |
|
102 \e{Icon Composer} allows you to import several different sized |
|
103 icons (for use in different contexts) as well as the masks that |
|
104 go with them. Save the set of icons to a file in your project |
|
105 directory. |
|
106 |
|
107 If you are using qmake to generate your makefiles, you only need |
|
108 to add a single line to your \c .pro project file. For example, |
|
109 if the name of your icon file is \c{myapp.icns}, and your project |
|
110 file is \c{myapp.pro}, add this line to \c{myapp.pro}: |
|
111 |
|
112 \snippet doc/src/snippets/code/doc_src_appicon.qdoc 2 |
|
113 |
|
114 This will ensure that \c qmake puts your icons in the proper |
|
115 place and creates an \c{Info.plist} entry for the icon. |
|
116 |
|
117 If you do not use \c qmake, you must do the following manually: |
|
118 \list 1 |
|
119 \i Create an \c Info.plist file for your application (using the |
|
120 \c PropertyListEditor, found in \c Developer/Applications). |
|
121 \i Associate your \c .icns record with the \c CFBundleIconFile record in the |
|
122 \c Info.plist file (again, using the \c PropertyListEditor). |
|
123 \i Copy the \c Info.plist file into your application bundle's \c Contents |
|
124 directory. |
|
125 \i Copy the \c .icns file into your application bundle's \c Contents/Resources |
|
126 directory. |
|
127 \endlist |
|
128 |
|
129 \section1 Setting the Application Icon on Common Linux Desktops |
|
130 |
|
131 In this section we briefly describe the issues involved in providing |
|
132 icons for applications for two common Linux desktop environments: |
|
133 \l{http://www.kde.org/}{KDE} and \l{http://www.gnome.org/}{GNOME}. |
|
134 The core technology used to describe application icons |
|
135 is the same for both desktops, and may also apply to others, but there |
|
136 are details which are specific to each. The main source of information |
|
137 on the standards used by these Linux desktops is |
|
138 \l{http://www.freedesktop.org/}{freedesktop.org}. For information |
|
139 on other Linux desktops please refer to the documentation for the |
|
140 desktops you are interested in. |
|
141 |
|
142 Often, users do not use executable files directly, but instead launch |
|
143 applications by clicking icons on the desktop. These icons are |
|
144 representations of "desktop entry files" that contain a description of |
|
145 the application that includes information about its icon. Both desktop |
|
146 environments are able to retrieve the information in these files, and |
|
147 they use it to generate shortcuts to applications on the desktop, in |
|
148 the start menu, and on the panel. |
|
149 |
|
150 More information about desktop entry files can be found in the |
|
151 \l{http://www.freedesktop.org/Standards/desktop-entry-spec}{Desktop Entry |
|
152 Specification}. |
|
153 |
|
154 Although desktop entry files can usefully encapsulate the application's details, |
|
155 we still need to store the icons in the conventional location for each desktop |
|
156 environment. A number of locations for icons are given in the |
|
157 \l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme |
|
158 Specification}. |
|
159 |
|
160 Although the path used to locate icons depends on the desktop in use, |
|
161 and on its configuration, the directory structure beneath each of |
|
162 these should follow the same pattern: subdirectories are arranged by |
|
163 theme, icon size, and application type. Generally, application icons |
|
164 are added to the hicolor theme, so a square application icon 32 pixels |
|
165 in size would be stored in the \c hicolor/32x32/apps directory beneath |
|
166 the icon path. |
|
167 |
|
168 \section2 K Desktop Environment (KDE) |
|
169 |
|
170 Application icons can be installed for use by all users, or on a per-user basis. |
|
171 A user currently logged into their KDE desktop can discover these locations |
|
172 by using \l{http://developer.kde.org/documentation/other/kde-config.html}{kde-config}, |
|
173 for example, by typing the following in a terminal window: |
|
174 |
|
175 \snippet doc/src/snippets/code/doc_src_appicon.qdoc 3 |
|
176 |
|
177 Typically, the list of colon-separated paths printed to stdout includes the |
|
178 user-specific icon path and the system-wide path. Beneath these |
|
179 directories, it should be possible to locate and install icons according |
|
180 to the conventions described in the |
|
181 \l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme Specification}. |
|
182 |
|
183 If you are developing exclusively for KDE, you may wish to take |
|
184 advantage of the \link |
|
185 http://developer.kde.org/documentation/other/makefile_am_howto.html |
|
186 KDE build system\endlink to configure your application. This ensures |
|
187 that your icons are installed in the appropriate locations for KDE. |
|
188 |
|
189 The KDE developer website is at \l{http://developer.kde.org/}. |
|
190 |
|
191 \section2 GNOME |
|
192 |
|
193 Application icons are stored within a standard system-wide |
|
194 directory containing architecture-independent files. This |
|
195 location can be determined by using \c gnome-config, for example |
|
196 by typing the following in a terminal window: |
|
197 |
|
198 \snippet doc/src/snippets/code/doc_src_appicon.qdoc 4 |
|
199 |
|
200 The path printed on stdout refers to a location that should contain a directory |
|
201 called \c{pixmaps}; the directory structure within the \c pixmaps |
|
202 directory is described in the \link |
|
203 http://www.freedesktop.org/Standards/icon-theme-spec Icon Theme |
|
204 Specification \endlink. |
|
205 |
|
206 If you are developing exclusively for GNOME, you may wish to use |
|
207 the standard set of \link |
|
208 http://developer.gnome.org/tools/build.html GNU Build Tools\endlink, |
|
209 also described in the relevant section of |
|
210 the \link http://developer.gnome.org/doc/GGAD/ggad.html GTK+/Gnome |
|
211 Application Development book\endlink. This ensures that your icons are |
|
212 installed in the appropriate locations for GNOME. |
|
213 |
|
214 The GNOME developer website is at \l{http://developer.gnome.org/}. |
|
215 |
|
216 \section1 Setting the Application Icon on the Symbian platform |
|
217 |
|
218 In order to set the application icon for Symbian platform applications, you need |
|
219 an SVG-T icon. For information on how to create SVG-T compliant icons, |
|
220 please refer to |
|
221 \l{http://wiki.forum.nokia.com/index.php/How_to_create_application_icon(SVG)_in_S60_3rd_edition/} |
|
222 |
|
223 Once the icon is available in the correct format and assuming you are |
|
224 using \c qmake to generate your makefiles, you only need to add a single |
|
225 line to your \c .pro project file. For example, if the name of your |
|
226 icon file is \c{myapp.svg}, and your project file is \c{myapp.pro}, |
|
227 add this line to \c{myapp.pro}: |
|
228 |
|
229 \snippet doc/src/snippets/code/doc_src_appicon.qdoc 5 |
|
230 |
|
231 */ |