You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
196 lines
7.9 KiB
196 lines
7.9 KiB
13 years ago
|
/****************************************************************************
|
||
|
|
**
|
||
|
|
** Qt Application Icon Usage Documentation.
|
||
|
|
**
|
||
|
|
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
|
||
|
|
**
|
||
|
|
** This file is part of the Qt GUI Toolkit.
|
||
|
|
** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE
|
||
|
|
**
|
||
|
|
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
|
||
|
|
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||
|
|
**
|
||
|
|
****************************************************************************/
|
||
|
|
|
||
|
|
/*!
|
||
|
|
\page appicon.html
|
||
|
|
|
||
|
|
\title Setting the Application Icon
|
||
|
|
|
||
|
|
The application icon, typically displayed in the top-left corner of an
|
||
|
|
application's top-level windows, is set by calling the
|
||
|
|
QWidget::setIcon() method on top-level widgets.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
\tableofcontents
|
||
|
|
|
||
|
|
\section1 Setting the Application Icon on Windows
|
||
|
|
|
||
|
|
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).
|
||
|
|
|
||
|
|
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:
|
||
|
|
\code
|
||
|
|
IDI_ICON1 ICON DISCARDABLE "myappico.ico"
|
||
|
|
\endcode
|
||
|
|
|
||
|
|
Finally, assuming you are using \link qmake-manual.book qmake\endlink
|
||
|
|
to generate your makefiles, add this line to your "myapp.pro" file:
|
||
|
|
|
||
|
|
\code
|
||
|
|
RC_FILE = myapp.rc
|
||
|
|
\endcode
|
||
|
|
|
||
|
|
Regenerate your makefile and your application. The .exe file will now be
|
||
|
|
represented with your icon e.g. in Explorer.
|
||
|
|
|
||
|
|
If you do not use \link qmake-manual.book qmake\endlink, the necessary
|
||
|
|
steps are: first, run the "rc" program on the .rc file, then link your
|
||
|
|
application with the resulting .res file.
|
||
|
|
|
||
|
|
\section1 Setting the Application Icon on Mac OS X
|
||
|
|
|
||
|
|
The application icon, typically displayed in the application dock
|
||
|
|
area, is set by calling QWidget::setIcon() 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.
|
||
|
|
|
||
|
|
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{Icon Composer} program supplied by Apple (in the
|
||
|
|
Developer/Application folder). \e{Icon Composer} 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.
|
||
|
|
|
||
|
|
If you are using \link qmake-manual.book qmake\endlink to generate
|
||
|
|
your make files, 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}:
|
||
|
|
\code
|
||
|
|
RC_FILE = myapp.icns
|
||
|
|
\endcode
|
||
|
|
This will ensure that \link qmake-manual.book qmake\endlink puts your
|
||
|
|
icons in the proper place and creates an \c{Info.plist} entry for the
|
||
|
|
icon.
|
||
|
|
|
||
|
|
If you do not use \link qmake-manual.book qmake\endlink, you must do
|
||
|
|
the following manually:
|
||
|
|
\list 1
|
||
|
|
\i Create an Info.plist file for your application (using the
|
||
|
|
PropertyListEditor, found in Developer/Applications).
|
||
|
|
\i Associate your .icns record with the CFBundleIconFile record in the
|
||
|
|
Info.plist file (again, using the PropertyListEditor).
|
||
|
|
\i Copy both the icns and your Info.plist into your application bundle
|
||
|
|
Resource 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:
|
||
|
|
\link http://www.kde.org/ KDE\endlink and \link http://www.gnome.org/
|
||
|
|
GNOME\endlink. 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 \link
|
||
|
|
http://www.freedesktop.org/ freedesktop.org\endlink. 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
|
||
|
|
\link http://www.freedesktop.org/Standards/desktop-entry-spec
|
||
|
|
Desktop Entry Specification\endlink.
|
||
|
|
|
||
|
|
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
|
||
|
|
\link http://www.freedesktop.org/Standards/icon-theme-spec
|
||
|
|
Icon Theme Specification\endlink.
|
||
|
|
|
||
|
|
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 KDE
|
||
|
|
|
||
|
|
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 \link http://developer.kde.org/documentation/other/kde-config.html
|
||
|
|
kde-config\endlink, for example,
|
||
|
|
by typing the following in a terminal window:
|
||
|
|
|
||
|
|
\code
|
||
|
|
kde-config --path icon
|
||
|
|
\endcode
|
||
|
|
|
||
|
|
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
|
||
|
|
\link http://www.freedesktop.org/Standards/icon-theme-spec
|
||
|
|
Icon Theme Specification \endlink.
|
||
|
|
|
||
|
|
If you are developing exclusively for KDE, you may wish to take
|
||
|
|
advantage of the \link
|
||
|
|
http://developer.kde.org/documentation/other/makefile_am_howto.html
|
||
|
|
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 \l{http://developer.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 gnome-config, for example by typing the following in a terminal
|
||
|
|
window:
|
||
|
|
|
||
|
|
\code
|
||
|
|
gnome-config --datadir
|
||
|
|
\endcode
|
||
|
|
|
||
|
|
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 wish to use
|
||
|
|
the standard set of \link
|
||
|
|
http://developer.gnome.org/tools/build.html GNU Build Tools\endlink,
|
||
|
|
also described in the relevant section of
|
||
|
|
the \link http://developer.gnome.org/doc/GGAD/ggad.html GTK+/Gnome
|
||
|
|
Application Development book\endlink. This ensures that your icons are
|
||
|
|
installed in the appropriate locations for GNOME.
|
||
|
|
|
||
|
|
The GNOME developer website is \l{http://developer.gnome.org/}.
|
||
|
|
|
||
|
|
*/
|