| /**************************************************************************** |
| ** |
| ** 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 (that is, prior to |
| application launch), 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 using Microsoft Visual Studio: Select |
| \uicontrol{File >> New}, and choose the \uicontrol{Icon File}. |
| |
| \note You need not load the application into the Visual Studio IDE as you |
| are using the icon editor only. |
| |
| 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 appico.ico. |
| |
| \section2 Using CMake |
| |
| To configure your application's icon, a resource file containing |
| information about the icon is required. A resource file is a text |
| file that contains information about the application |
| resources, such as icons, cursors, fonts, and so on. For |
| more information about resource files and what it can contain, see |
| \l{https://docs.microsoft.com/en-us/windows/win32/menurc/about-resource-files}{About Resource Files}. |
| |
| Once you have the \c .rc file, add information about the ICO file to it and |
| use it to configure your application icon. |
| |
| The following snippet example demonstrates how to set up application |
| icon using CMake: |
| |
| \snippet snippets/code/CMakeLists.txt appicon_windows |
| |
| Notice that the \c set command, defines the \c APP_ICON_RESOURCE_WINDOWS |
| variable, which contains the path of the RC file. This variable is used |
| with the \c add_executable command to set the application's icon. |
| |
| \section2 Using qmake |
| |
| If you are still using qmake to generate your makefiles, |
| you 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. |
| |
| \section2 Using CMake |
| |
| To configure the application's icon, the \c Info.plist file generated |
| by CMake must contain the icon information. This can be achieved by |
| setting the \c .icns file name to the \c MACOSX_BUNDLE_ICON_FILE variable. |
| |
| The following snippet demonstrates how to set up the application icon using |
| CMake: |
| |
| \snippet snippets/code/CMakeLists.txt appicon_macOS |
| |
| Notice that the first \c set command defines the \c MACOSX_BUNDLE_ICON_FILE |
| variable, which is required to add the icon file to the \c Info.plist file. |
| The second \c set command defines the \c APP_ICON_MACOSX variable with the |
| absolute path to the icon file. This variable is then used to configure |
| MACOSX_PACKAGE_LOCATION, which defines the icon file's install location. |
| Finally, the \c add_executable uses the \c APP_ICON_MACOSX variable to set |
| the application's icon. |
| |
| \section2 Using qmake |
| |
| If you are still 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 want to use |
| the standard set of GNU Build Tools. For more information, see |
| the |
| \l{https://developer.gnome.org/platform-overview/unstable/dev-launching.html.en}{Application launching} |
| section. This ensures that your icons are installed in the |
| appropriate locations for GNOME. |
| |
| The GNOME developer website, \l{http://developer.gnome.org/}, provides |
| more insight into developing applications. |
| */ |