← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/howtos/appicon.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/howtos/appicon.qdoc
 
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
*/