/*
 * Copyright (C) 2012 Canonical Ltd.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; version 3.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/*!
    \page resolution-independence.html resolution-independence
    \title Resolution Independence
    \nextpage {Lomiri User Interface Toolkit}

    The objective of resolution independence is to make it easy for graphical
    user interfaces in Lomiri to scale to all the form factors that Lomiri
    targets: phones, tablets, laptops and desktops.
    The approach taken combines simplicity for the designers and developers
    with visual fidelity, quality and usability.


    \section1 Measurement Units

    A new measurement unit is defined called the grid unit, abbreviated \b{\e gu}.
    1 grid unit translates to a given number of pixels depending on the type of
    screen that the user interface is displayed on.
    For example, on a laptop computer 1 grid unit will typically translate to 8 pixels.
    The number of pixels per grid unit is chosen in order to preserve the perceived
    visual size of UI elements and therefore depends on the density of the display
    and the distance the user is to the screen. We also ensure that 1 grid unit is
    always an integer number of pixel.

    Examples:

    \table
    \header
      \li Device
      \li Conversion
    \row
      \li Most laptops
      \li 1 gu = 8 px
    \row
      \li Retina laptops
      \li 1 gu = 16 px
    \row
      \li Phone with 4 inch screen at HD resolution (around 720x1,280 pixels)
      \li 1 gu = 18 px
    \row
      \li Tablet with 10 inch screen at HD resolution (around 720x1,280 pixels)
      \li 1 gu = 10 px
    \endtable

    The grid unit defines a visual rhythm in Lomiri and should be used for all measurements.
    Sizes of elements, spacing, margins, etc. should all use multiples of 1 gu.

    It is available from QML as a method of the global object \b units, instance of \l Units.

    Example Usage:
    \code
    import Lomiri.Components 1.2

    Item {
        width: units.gu(2)
        height: units.gu(5)
    }
    \endcode

    Exceptionally, in order to accommodate for the rare cases where measurements of less
    than 1 gu are needed another unit is available: the density independent pixel,
    abbreviated \b{\e dp}. 1 dp typically translates to 1 pixel on laptops and low
    density mobile phones and tablets.

    Example Usage:
    \code
    import Lomiri.Components 1.2

    Rectangle {
        height: units.dp(1)
    }
    \endcode

    \section1 Bitmaps

    Vector graphics, fonts and programmatically drawn elements will usually scale well
    to the different devices. On the other hand, bitmaps will typically require a bit
    more care.

    The size of a bitmap needs to be adequate to render well on a given
    device. The toolkit allows one to design multiple versions of a bitmap and choose
    the appropriate one dynamically depending on the device the application is
    being run on.
    In order to know for what target device a given version of a bitmap was
    produced, we define a file naming convention based on the number of pixel
    per grid unit of the device.

    Example:

    If the target device the bitmap is produced for has 10 pixels per
    grid unit, then the file name of the bitmap should be suffixed with @10:
    \e my_bitmap.png should be renamed to \e my_bitmap@10.png.


    In order to support the highest possible resolution devices on the market, we
    recommend to always design bitmaps for a device that would have 30 pixels per
    grid unit (@30 suffix). The system will perform a high quality downscaling of
    the bitmap when needed on lower resolution screens.

    Example:

    If the destination size of the bitmap is 10 gu * 10 gu and the developer
    targets a device that has 18 pixels per grid unit (1 gu = 18 px), the bitmap
    should still be created as if 1 gu = 30 px which results in a 300 px * 300 px
    bitmap. When testing on the device the bitmap will be downscaled by a factor
    of 30 / 18 = 1.66667.


    \section1 Fonts

    It is critical for the font sizes to be consistent across Lomiri and to
    have a rhythm defining them.
    Instead of setting the font size in pixels or points, it is imperative to
    define the font size in terms of literals:

    \table
    \row
      \li \b x-large
    \row
      \li \b large
    \row
      \li \b medium
    \row
      \li \b small
    \row
      \li \b x-small
    \endtable

    Example Usage:
    \code
    import Lomiri.Components 1.2

    Label {
        fontSize: "small"
    }
    \endcode

    For reference when designing, these sizes correspond to the following
    pixel measurements:

    \table
    \header
      \li Font Size
      \li Desktop
      \li Smart Phone with 4" HD screen
      \li Tablet with 10" HD screen
    \row
      \li \b{\e x-large}
      \li 34 px
      \li 76 px
      \li 42 px
    \row
      \li \b{\e large}
      \li 20 px
      \li 45 px
      \li 25 px
    \row
      \li \b{\e medium}
      \li 14 px
      \li 31 px
      \li 18 px
    \row
      \li \b{\e small}
      \li 12 px
      \li 27 px
      \li 15 px
    \row
      \li \b{\e x-small}
      \li 10 px
      \li 22 px
      \li 12 px
    \endtable

 */
