Add support for creating .ico and .cur files using icotool (icoutils)

ImageMagick has support for these formats but is not suitable because it
does not have the ability to set cursor hotspots.

This patch is preparation towards QBS-73.

[ChangeLog] Introduced the ico module for creating .ico and .cur files

Change-Id: I9a917b3ee5983bc59fba1a5740540299d8d9708f
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/reference/modules/ico-module.qdoc b/doc/reference/modules/ico-module.qdoc
new file mode 100644
index 000000000..f94065f1c
--- /dev/null
+++ b/doc/reference/modules/ico-module.qdoc
@@ -0,0 +1,131 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qbs.
+**
+** $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$
+**
+****************************************************************************/
+
+/*!
+    \contentspage index.html
+    \page ico-module.html
+    \ingroup list-of-modules
+
+    \title Module ico
+    \since 1.11
+    \brief Provides support for building ICO (.ico) and CUR (.cur) files.
+
+    The \c ico module contains properties and rules for building
+    Microsoft Windows Icon (.ico) and Microsoft Windows Cursor (.cur) files.
+
+    \note This module relies on the \c icotool command-line tool from the
+    icotools package, which must be installed separately and found in the
+    \c PATH or an appropriate system binaries directory for your system (e.g.
+    \c /usr/bin or \c /usr/local/bin).
+
+    \section1 General Properties
+
+    \table
+    \header
+        \li Property
+        \li Type
+        \li Since
+        \li Default
+        \li Description
+    \row
+        \li cursorHotspotX
+        \li \c{int}
+        \li 1.11
+        \li \c{undefined}
+        \li Cursor hotspot X coordinate. Only relevant when building .cur files.
+            This must be set individually for each input PNG file.
+            \note icoutils version 0.32 or greater is required to set the
+            hotspot in cursor files with multiple images.
+    \row
+        \li cursorHotspotY
+        \li \c{int}
+        \li 1.11
+        \li \c{undefined}
+        \li Cursor hotspot Y coordinate. Only relevant when building .cur files.
+            This must be set individually for each input PNG file.
+            \note icoutils version 0.32 or greater is required to set the
+            hotspot in cursor files with multiple images.
+    \row
+        \li raw
+        \li \c{bool}
+        \li 1.11
+        \li \c{false}
+        \li Whether to store the input file as a raw PNG,
+            as supported in Windows Vista.
+            Only relevant when building .ico files.
+            This must be set individually for each input PNG file.
+            It is only recommended to set this value for icon sizes
+            larger than or equal to 256x256.
+    \endtable
+
+    \section1 Advanced Properties
+
+    \table
+    \header
+        \li Property
+        \li Type
+        \li Since
+        \li Default
+        \li Description
+    \row
+        \li icotoolFilePath
+        \li \c{string}
+        \li 1.11
+        \li determined automatically
+        \li Full path of the \c icotool binary.
+            This should not normally need to be changed if \QBS was able to
+            automatically detect it.
+    \endtable
+
+    \section1 Relevant File Tags
+
+    \table
+    \header
+        \li Tag
+        \li Auto-tagged File Names
+        \li Since
+        \li Description
+    \row
+        \li \c{"cur"}
+        \li n/a
+        \li 1.11
+        \li The rule that creates cursor (.cur) files
+            attaches this tag to its output artifact.
+    \row
+        \li \c{"ico"}
+        \li n/a
+        \li 1.11
+        \li The rule that creates icon (.ico) files
+            attaches this tag to its output artifact.
+    \row
+        \li \c{"png"}
+        \li \c{"*.png"}
+        \li 1.11
+        \li Source files with this tag indicate PNG files
+            which are used as inputs to create ico or cur files.
+    \endtable
+*/