===============================================================================

This work is provided under the terms of the CREATIVE COMMONS PUBLIC
LICENSE. This work is protected by copyright and/or other applicable
law. Any use of the work other than as authorized under this license
or copyright law is prohibited.

http://creativecommons.org/licenses/by-nc-sa/2.5/

© 2016 OX Software GmbH, Germany, info@open-xchange.com

@author Daniel Rentz <daniel.rentz@open-xchange.com>

===============================================================================

This package contains icon source files used to create the image sets and LESS
code for all icons used in the OX Documents applications.


 
1 Add or Change Icons
=====================

Copy all new or changed source images to the sub directory "images".

* The names of sub directories and the file names must not contain any
    whitespace characters (rename new files if necessary).
* The icons files must be in PNG image format, and must contain the ".png" file
    extension.
* There must exist a 16 pixel version of the icon file (icon height must be 16
    pixels, width is arbitrary), and the file name must end with "_16.png".
* There must exist a 32 pixel version of the icon file (icon height must be 32
    pixels, width must be exactly twice the width of the 16 pixel version), and
    the file name must end with "_32.png".



2 Update Icon Definition File
=============================
 
The file "icons.json" contains the icon definitions, as array of JSON objects.
Each element in the array may contain the following properties:

* "path" (required)
    The base file name of an icon image, including the path inside the "images"
    directory next to this file. The "path" value must not contain whitespace
    (path names and file names), size suffix ("_16", "_32"), nor file extension
    (".png").

* "classes" (required)
    One or more CSS class names for the icon, as string (one class), or array
    of strings (multiple class names for the same source image). The prefix
    "docs-" will be added to all resulting class names during creation of the
    icon sets.

* "locales" (optional)
    One or more ISO language codes, or specific ISO locale codes, as string
    (one language/locale code), or array of strings (multiple language/locale
    codes for the same source image). The language/locale codes will be added
    to the CSS selector of the icon image, and will override the default icon
    defined before, if the GUI locale matches the specified codes.

* "comment" (optional)
    An arbitrary developer comment for the icon file. Will be ignored.


Example 1)

The line

    { "path": "path/icon01", "classes": "my-icon" }

will assign the CSS class "docs-my-icon" to the icon files "path/icon01_16.png"
(16x16 pixels) and "path/icon01_32.png" (32x32 pixels). It can be used by
creating an HTML <i> element with the CSS class "docs-my-icon".


Example 2)

The line

    { "path": "path/icon02", "classes": ["my-icon", "special-icon"] }

will assign the CSS classes "docs-my-icon" and "docs-special-icon" to the same
icon files "path/icon02_**.png".


Example 3)

The lines

    { "path": "path/icon03",   "classes": "my-icon" },
    { "path": "path/icon03_1", "classes": "my-icon", "locales": ["de", "fr"] },
    { "path": "path/icon03_2", "classes": "my-icon", "locales: "de_AT" }

- will assign the CSS class "docs-my-icon" to the icon files
    "path/icon03_**.png",
- will redirect "docs-my-icon" icons for German and French GUI to the icon
    files "path/icon03_1_**.png",
- will redirect "docs-my-icon" icons for Austrian GUI to the icon files
    "path/icon03_2_**.png".
