qt5base-lts/examples/widgets/doc/orientation.qdoc
Eike Ziller 4727bb5991 Add \brief to the examples.
That is used by qdoc to generate brief descriptions for the example
manifests.

Change-Id: I142a6d3259f90d0c9990033b3c36e139062ac343
Reviewed-by: Eike Ziller <eike.ziller@digia.com>
Reviewed-by: hjk <qthjk@ovi.com>
2012-11-29 13:51:54 +01:00

144 lines
6.2 KiB
Plaintext

/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*! \example widgets/orientation
\group all-examples
\title Orientation Example
\brief 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 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 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 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 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 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 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 widgets/orientation/main.cpp 0
*/