/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt Components project.
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
**     the names of its contributors may be used to endorse or promote
**     products derived from this software without specific prior written
**     permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

    \qmlclass Screen
    \ingroup qt-components
    \since 4.7
    \inherits QtObject
    \brief Screen is a class that gives you physical information about the display of the device and its orientation.

    This class provides access to the screen properties, like the resolution, the orientation
    and the dpi.

    Screen is exposed as a context property called "screen". It is not possible to
    instantiate a Screen object in QML, but the screen must be accessed through
    the context property.
*/

// Enable screen.width and screen.height once dependecies are ok
// /*!
//    \qmlproperty int Screen::width
//
//    Screen width in pixels. This value changes based on orientation, that is in portrait mode
//    width is smaller than height and on the contrary in landscape mode.
//
//    \sa displayWidth
// */
// Also fix displayWidth see also block to point to this

// /*!
//    \qmlproperty int Screen::height
//
//    Screen height in pixels. This value changes based on orientation, that is in portrait mode
//    height is larger than width and on the contrary in landscape mode.
//
//    \sa displayHeight
// */
// Also fix displayHeight see also block to point to this

/*!
    \qmlproperty int Screen::displayWidth

    The native width of the display in pixels, that is the width of the screen when rotation returns zero.

    \sa rotation
*/

/*!
    \qmlproperty int Screen::displayHeight

    The native height of the display in pixels, that is the height of the screen when rotation returns zero.

    \sa rotation
*/

/*!
    \qmlproperty int Screen::rotation
    
    \readonly

    The rotation angle of the (logical content of the) screen, measured counter-clockwise relative
    to the native orientation of the device. If the rotation is zero it means that the screen
    is in the native orientation of the device.

    The value is always non-negative. The actual possible values may depend on hardware. 

    \sa displayWidth, displayHeight
*/

/*!
    \qmlproperty enumeration Screen::currentOrientation
    
    \readonly

    The current orientation of the screen. The possible values are:

    \list
    \o Screen.Portrait - when the width of the screen is less than or equal to the height.
    \o Screen.Landscape - when the width of the screen is greater than the height.
    \o Screen.PortraitInverted - when the width of the screen is less than or equal to the height,
        and the screen is considered to be upside-down.
    \o Screen.LandscapeInverted - when the width of the screen is greater than the height,
        and the screen is considered to be upside-down.
    \endlist

    The actual possible values may depend on hardware. For instance, some devices support
    only one orientation, or some devices do not support inverted orientations.

    Notice that this is a read-only property. For setting the orientation use allowedProperties
    or Page::orientationLock

    \sa allowedOrientations, Page::orientationLock
*/

/*!
    \qmlproperty enumeration Screen::allowedOrientations
    
    \readonly

    The allowed orientations for the screen. The property accepts any combination
    of Screen::Orientations flags. 

    \list
    \o Screen.Default - the default set of allowed orientations, may depend on hardware
    \o Screen.Portrait - portrait mode allowed
    \o Screen.Landscape - landscape mode allowed
    \o Screen.PortraitInverted - inverted portrait mode allowed
    \o Screen.LandscapeInverted - inverted landscape mode allowed
    \o Screen.All - convenience enumeration for allowing all possible orientation modes
    \endlist

    The property is used for locking the screen to a certain orientation, like this:

    \code
    function lockToLandscape() {
        screen.allowedOrientation = Screen.Landscape
    }
    \endcode

    Or it can be used for letting the orientation change freely according to the
    actual physical orientation of the device, like this:

    \code
    function setAutomaticOrientation() {
        screen.allowedOrientation = Screen.All
        // equals to:
        // screen.allowedOrientation = Screen.Portrait | Screen.Landscape |
        //                             Screen.PortraitInverted | Screen.LandscapeInverted
    }
    \endcode

    Notice that typically orientation is controlled by the Page component. This property 
    should be used explicitly only if Page is not used at all, or if Page::orientationLock
    property is set to PageOrientation.Manual.

    \sa currentOrientation, Page::orientationLock
*/

/*!
    \qmlproperty qreal Screen::dpi
    
    \readonly

    The dots per inch value of the screen. It is assumed that the pixels are square, so in theory
    the value might not be 100% accurate.
*/

/*!
    \qmlproperty enumeration Screen::displayCategory
    
    \readonly

    Screen classification based on the physical size (diagonal) of the screen.

    This property can be used for example for selecting different top level
    layouts for different display categories:

    \code
    Page {
        Loader {
            source: (screen.displayCategory == Screen.Small) ? "SmallView.qml" : "NormalView.qml"
            ...
        }
    }
    \endcode

    \list
    \o Screen.Small - a small screen
    \o Screen.Normal - a normal screen
    \o Screen.Large - a large screen
    \o Screen.ExtraLarge - an extra large screen
    \endlist

    \image screen-display-category.png
    \e Illustration of displayCategory mappings

    \sa density
*/

/*!
    \qmlproperty enumeration Screen::density
    
    \readonly

    Screen classification based on the dpi value of the screen.

    \list
    \o Screen.Low - a low-dpi screen
    \o Screen.Medium - a medium-dpi screen
    \o Screen.High - a high-dpi screen
    \o Screen.ExtraHigh - an extra-high-dpi screen
    \endlist

    \image screen-density.png
    \e Illustration of density mappings

    \sa displayCategory
*/

/*!
    \qmlproperty bool Screen::covered (meego)
    
    \readonly

    MeeGo 1.2 Harmattan-specific property
    
    Returns true if the screen is covered.
*/

/*!
    \qmlproperty string Screen::orientationString (meego)
    
    \readonly

    MeeGo 1.2 Harmattan-specific property
    
    Returns the current orientation as a String ("Portrait", "Landscape", "PortraitInverted" or "LandscapeInverted").
*/

/*!
    \qmlproperty bool Screen::keyboardOpen (meego)
    
    \readonly

    MeeGo 1.2 Harmattan-specific property
    
    Returns true if the virtual keyboard is shown on the screen.
*/

/*!
    \qmlproperty int Screen::rotation (meego)

    MeeGo 1.2 Harmattan-specific property
    
    Returns the current orientation as angle in degrees.
*/

/*!
    \qmlproperty bool Screen::minimized (meego)
    
    \readonly

    MeeGo 1.2 Harmattan-specific property
    
    Returns true if the application is minimized to the switcher.
*/

/*!
    \qmlproperty qvariant Screen::windowState (meego)
    
    \readonly

    MeeGo 1.2 Harmattan-specific property

    An object giving various informations about the state of the windowState.

    \list
        \o windowState.visible: returns true if the window or its thumbnail is shown; otherwise false if the window or its thumbnail has been hidden at least for 1000 ms.
        \o windowState.active: returns true if the window is active (has focus).
        \o windowState.animating: read-write property for the the window orientation animation.
        \o windowState.viewMode: returns the current view mode, WindowState.Fullsize for fullscreen and WindowState.Thumbnail for thumbnail modes. 
        \o windowState.viewModeString: returns the current view mode as a string, "Fullsize" for fullsize and "Thumbnail" for thumbnail modes.

    \endlist

*/

/*!
    \qmlproperty bool Screen::allowSwipe (meego)
    
    \readonly

    MeeGo 1.2 Harmattan-specific property

    Allows to switch off the swipe gesture. As a result the user won’t be able
    to close the application and he won't be able to push it to the background.

    Caution: This feature should not be used unless there are very good reasons:
    The swipe gesture is an essential gesture that the user can rely on.
    Therefore switching it off is usually a bad idea.

    In case of use (e.g. for games) please regard the following guidelines:
    \list
        \o if the application shows a menu it should have the swipe enabled
        \o only if the game is in "active" playing state the swipe gesture can be
           disabled or modified.
        \o furthermore, applications that change the swipe behavior need to have a
           pause button: in pause mode the (swipe) gestures must be enabled.

    \endlist

*/

