qt-everywhere-src-5.14.1/qtdoc/doc/src/howtos/appicon.qdoc - orbit - Git at Google

 /****************************************************************************
 **
 ** Copyright (C) 2016 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:FDL$
 ** Commercial License Usage
 ** Licensees holding valid commercial Qt licenses may use this file in
 ** accordance with the commercial license agreement provided with the
 ** Software or, alternatively, in accordance with the terms contained in
 ** a written agreement between you and The Qt Company. For licensing terms
 ** and conditions see https://www.qt.io/terms-conditions. For further
 ** information use the contact form at https://www.qt.io/contact-us.
 **
 ** GNU Free Documentation License Usage
 ** Alternatively, this file may be used under the terms of the GNU Free
 ** Documentation License version 1.3 as published by the Free Software
 ** Foundation and appearing in the file included in the packaging of
 ** this file. Please review the following information to ensure
 ** the GNU Free Documentation License version 1.3 requirements
 ** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/

 /*!
     \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 (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
     \menu{File|New}, then select the \menu{File} tab in the dialog
     that appears, and choose \menu{Icon}. (Note that you do not need
     to load your application into Visual C++; here we are only using
     the icon editor.)

     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 myappico.ico.

     Then, assuming you are using qmake to generate your makefiles,
     you only 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.

     If you are 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 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 at \l{http://developer.gnome.org/}.
 */
	/****************************************************************************
	**
	** Copyright (C) 2016 The Qt Company Ltd.
	** Contact: https://www.qt.io/licensing/
	**
	** This file is part of the documentation of the Qt Toolkit.
	**
	** $QT_BEGIN_LICENSE:FDL$
	** Commercial License Usage
	** Licensees holding valid commercial Qt licenses may use this file in
	** accordance with the commercial license agreement provided with the
	** Software or, alternatively, in accordance with the terms contained in
	** a written agreement between you and The Qt Company. For licensing terms
	** and conditions see https://www.qt.io/terms-conditions. For further
	** information use the contact form at https://www.qt.io/contact-us.
	**
	** GNU Free Documentation License Usage
	** Alternatively, this file may be used under the terms of the GNU Free
	** Documentation License version 1.3 as published by the Free Software
	** Foundation and appearing in the file included in the packaging of
	** this file. Please review the following information to ensure
	** the GNU Free Documentation License version 1.3 requirements
	** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
	** $QT_END_LICENSE$
	**
	****************************************************************************/

	/*!
	\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 (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
	\menu{File\|New}, then select the \menu{File} tab in the dialog
	that appears, and choose \menu{Icon}. (Note that you do not need
	to load your application into Visual C++; here we are only using
	the icon editor.)

	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 myappico.ico.

	Then, assuming you are using qmake to generate your makefiles,
	you only 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.

	If you are 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 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 at \l{http://developer.gnome.org/}.
	*/