/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*! \example widgets/orientation
    \group all-examples
    \title Orientation Example

    The example shows a simple way to use different UIs depending on the screen
    orientation of a mobile device.

    \image orientation-landscape.png The UI in landscape mode
    \image orientation-portrait.png The UI in portrait mode

    The screen on many mobile devices can be viewed in both portrait and
    landscape orientation. The orientation can be swiched with the help of a
    hardware or software trigger. Due to the often small physical screen size,
    user interfaces has to be very simple and compact to stay usable, and
    applications usually occupy the whole screen. Designing a user interface
    that works equally well in both landscape and portrait mode is not always
    possible, however, so making a different layout for each case usually pays
    off.

    The example application makes use of two different UI widgets created with
    the Qt Designer, one for portrait and one for landscape orientation. The
    application has a widget that contains an image and the user is able to
    select one of three images for it to show. In addition to the two UIs, the
    application consists of a \c MainWindow class.

    \section1 Landscape UI

    If the screen is in landscape mode, the user probably holds the device with
    both hands and is ready to give full attention to the application. The
    landscape UI looks like this:

    \image orientation-landscape-ui.png The landscape UI

    To the left is a QWidget called \c choiceWidget, which will show the
    current image, and to the right are three QRadioButton instances. The
    active radio button specifies the image to show.

    \section1 Portrait UI

    When the device is in portrait mode, it usually means that the user holds
    it with one hand, and can comfortably use the thumb for small amounts of
    input. The layout is simpler, and is focused on consuming content. The
    portrait UI looks like this:

    \image orientation-portrait-ui.png The portrait UI

    Similarly, it contains a QWidget, also called \c choiceWidget, that will
    show the current image. In contrast to the landscape UI, this one doesn't
    provide any controls to change the image.

    \section1 MainWindow Class Definition

    \c MainWindow inherits from QWidget and acts as the top level widget of the
    application.

    \snippet examples/widgets/orientation/mainwindow.h 0

    The \c resizeEvent() method is re-implemented, and used to check which
    UI to show. The \c onRadioButtonClicked() slot is connected to the
    landscape UI's radio button group and selects the current image.

    \c landscapeWidget and \c portraitWidget will contain the UI layouts. Only
    one of them is visible at a time.

    \section1 MainWindow Class Implementation

    In the constructor, the widgets that will hold the UIs are created and set
    up.

    \snippet examples/widgets/orientation/mainwindow.cpp 0

    Since the exit buttons on the layouts are different from each other, both
    of them have to have their \c clicked() signal connected to the \c close()
    slot of the main widget. The first image is also made current with the call
    to \c onRadioButtonClicked().

    \snippet examples/widgets/orientation/mainwindow.cpp 1

    On the Maemo platform, windows are stuck in landscape mode by default. The
    application has to explicitly say that rotation is supported.

    \snippet examples/widgets/orientation/mainwindow.cpp 2

    The \c resizeEvent() is called when the main window is first created, and
    also whenever the window has been resized. If the window is shown in
    full screen, this is an indication that the orientation of the screen has
    changed.

    The dimensions of \c landscapeWidget is the transpose of the dimensions of
    \c portraitWidget. When the orientation is known, both are set to the
    (possibly transposed) size of the window. Depending on the orientation, one
    widget is made visible and the other invisible.

    \snippet examples/widgets/orientation/mainwindow.cpp 3

    When the user selects one of the radio buttons in the landscape UI, the
    current image is changed. The image is displayed by specifying the
    background style of the choice widget. Since both \c portrait and
    \c landscape have a \c choiceWidget of their own, the change has to be
    reflected in both instances.

    \snippet examples/widgets/orientation/mainwindow.cpp 4

    Synchronizing both UIs like this might become unfeasible when there are
    many things that can change. In that case it is better to make use of the
    \l{Introduction to Model/View Programming}{Model-View-Controller pattern}
    more extensively and share the content between both portrait and landscape
    widgets. Then an interface for displaying and manipulating it can be tailor
    made for both orientations.

    \section1 The \c main() Function

    The main function creates a \c MainWindow instance and shows it full
    screen.
    \snippet examples/widgets/orientation/main.cpp 0
*/