Add Qt3 development HEAD version

1 files changed, 195 insertions, 0 deletions

diff --git a/doc/appicon.doc b/doc/appicon.doc
new file mode 100644
index 0000000..1145f5b
--- /dev/null
+++ b/doc/appicon.doc
@@ -0,0 +1,195 @@
+/****************************************************************************
+**
+** 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/}.
+
+*/