summaryrefslogtreecommitdiffstats
path: root/doc/html/appicon.html
blob: 6bd0585cf860e83d0b0372a274be38e7a4a31a21 (plain)
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/appicon.doc:15 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Setting the Application Icon</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>

<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
 <a href="index.html">
<font color="#004faf">Home</font></a>
 | <a href="classes.html">
<font color="#004faf">All&nbsp;Classes</font></a>
 | <a href="mainclasses.html">
<font color="#004faf">Main&nbsp;Classes</font></a>
 | <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
 | <a href="groups.html">
<font color="#004faf">Grouped&nbsp;Classes</font></a>
 | <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Setting the Application Icon</h1>



<p> The application icon, typically displayed in the top-left corner of an
application's top-level windows, is set by calling the
<a href="qwidget.html#setIcon">QWidget::setIcon</a>() method on top-level widgets.
<p> In order to change the icon of the executable application file
itself, as it is presented on the desktop (i.e. prior to application
execution), it is necessary to employ another, platform-dependent
technique.
<p> <!-- toc -->
<ul>
<li><a href="#1"> Setting the Application Icon on Windows
</a>
<li><a href="#2"> Setting the Application Icon on Mac OS X
</a>
<li><a href="#3"> Setting the Application Icon on common Linux desktops
</a>
<ul>
<li><a href="#3-1"> KDE
</a>
<li><a href="#3-2"> GNOME
</a>
</ul>
</ul>
<!-- endtoc -->

<p> <h2> Setting the Application Icon on Windows
</h2>
<a name="1"></a><p> First, create an ICO format bitmap file that contains the icon image. This
can be done with e.g. Microsoft Visual C++: Select "File|New...", then
select the "File" tab in the dialog that appears, and choose "Icon". (Note
that you do not need to load your application into Visual C++; here we are
only using the icon editor).
<p> Store the ICO file in your application's source code directory, for
example, with the name, "myappico.ico". Then, create a text file
called e.g. "myapp.rc" in which you put a single line of text:
<pre>
IDI_ICON1               ICON    DISCARDABLE     "myappico.ico"
</pre>
 
<p> Finally, assuming you are using <a href="qmake-manual.html">qmake</a>
to generate your makefiles, add this line to your "myapp.pro" file:
<p> <pre>
RC_FILE = myapp.rc
</pre>
 
<p> Regenerate your makefile and your application. The .exe file will now be
represented with your icon e.g. in Explorer.
<p> If you do not use <a href="qmake-manual.html">qmake</a>, the necessary
steps are: first, run the "rc" program on the .rc file, then link your
application with the resulting .res file.
<p> <h2> Setting the Application Icon on Mac OS X
</h2>
<a name="2"></a><p> The application icon, typically displayed in the application dock
area, is set by calling <a href="qwidget.html#setIcon">QWidget::setIcon</a>() on a top-level widget. 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. 
<p> 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.
<p> Although many programs can create icon files (<tt>.icns</tt>), the recommended
approach is to use the <em>Icon Composer</em> program supplied by Apple (in the
Developer/Application folder). <em>Icon Composer</em> allows you to import several
different sized icons (for use in different contexts) as well as the masks
that go with them. Save the set of icons to a file in your project
directory.
<p> If you are using <a href="qmake-manual.html">qmake</a> to generate
your make files, you only need to add a single line to your <tt>.pro</tt>
project file. For example, if the name of your icon file is
<tt>myapp.icns</tt>, and your project file is <tt>myapp.pro</tt>, add this line
to <tt>myapp.pro</tt>:
<pre>
RC_FILE = myapp.icns
</pre>
 
This will ensure that <a href="qmake-manual.html">qmake</a> puts your
icons in the proper place and creates an <tt>Info.plist</tt> entry for the
icon.
<p> If you do not use <a href="qmake-manual.html">qmake</a>, you must do
the following manually:
<ol type=1>
<li> Create an Info.plist file for your application (using the
PropertyListEditor, found in Developer/Applications).
<li> Associate your .icns record with the CFBundleIconFile record in the
Info.plist file (again, using the PropertyListEditor).
<li> Copy both the icns and your Info.plist into your application bundle
Resource directory.
</ol>
<p> <h2> Setting the Application Icon on common Linux desktops
</h2>
<a name="3"></a><p> In this section we briefly describe the issues involved in providing
icons for applications for two common Linux desktop environments:
<a href="http://www.kde.org/">KDE</a> and <a href="http://www.gnome.org/">GNOME</a>. 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 <a href="http://www.freedesktop.org/">freedesktop.org</a>. For information
on other Linux desktops please refer to the documentation for the
desktops you are interested in.
<p> 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.
<p> More information about desktop entry files can be found in the
<a href="http://www.freedesktop.org/Standards/desktop-entry-spec">Desktop Entry Specification</a>.
<p> 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
<a href="http://www.freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</a>.
<p> 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 <tt>hicolor/32x32/apps</tt> directory beneath
the icon path.
<p> <h3> KDE
</h3>
<a name="3-1"></a><p> Application icons can be installed for use by all users, or on a per-user basis.
A user currently logged into their KDE desktop can discover these locations
by using <a href="http://developer.kde.org/documentation/other/kde-config.html">kde-config</a>, for example,
by typing the following in a terminal window:
<p> <pre>
kde-config --path icon
</pre>
 
<p> 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
<a href="http://www.freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</a>.
<p> If you are developing exclusively for KDE, you may wish to take
advantage of the <a href="http://developer.kde.org/documentation/other/makefile_am_howto.html">KDE build system</a> to configure your application. This ensures
that your icons are installed in the appropriate locations for KDE.
<p> The KDE developer website is <a href="http://developer.kde.org/">http://developer.kde.org/</a>.
<p> <h3> GNOME
</h3>
<a name="3-2"></a><p> Application icons are stored within a standard system-wide directory containing
architecture-independent files. This location can be determined by
using gnome-config, for example by typing the following in a terminal
window:
<p> <pre>
gnome-config --datadir
</pre>
 
<p> The path printed on stdout refers to a location that should contain a directory
called <tt>pixmaps</tt>; the directory structure within the <tt>pixmaps</tt>
directory is described in the <a href="http://www.freedesktop.org/Standards/icon-theme-spec">Icon Theme
Specification</a>.
<p> If you are developing exclusively for GNOME, you may wish to use
the standard set of <a href="http://developer.gnome.org/tools/build.html">GNU Build Tools</a>,
also described in the relevant section of
the <a href="http://developer.gnome.org/doc/GGAD/ggad.html">GTK+/Gnome
Application Development book</a>. This ensures that your icons are
installed in the appropriate locations for GNOME.
<p> The GNOME developer website is <a href="http://developer.gnome.org/">http://developer.gnome.org/</a>.
<p> 
<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright &copy; 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt 3.3.8</div>
</table></div></address></body>
</html>