Move examples to proper location.

Change-Id: Ib808f5d99cb8217f8786411b531fa5bc7fa5250a
Reviewed-by: Martin Smith <martin.smith@digia.com>

9 files changed, 486 insertions, 0 deletions

diff --git a/examples/widgets/doc/dropsite.qdoc b/examples/widgets/doc/dropsite.qdoc
new file mode 100644
index 0000000000..6e4b21a9be
--- /dev/null
+++ b/examples/widgets/doc/dropsite.qdoc
@@ -0,0 +1,249 @@
+/****************************************************************************
+**
+** 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 draganddrop/dropsite
+    \title Drop Site Example
+
+    The example shows how to distinguish the various MIME formats available
+    in a drag and drop operation.
+
+    \image dropsite-example.png Screenshot of the Drop Site example
+
+    The Drop Site example accepts drops from other applications, and displays
+    the MIME formats provided by the drag object.
+
+    There are two classes, \c DropArea and \c DropSiteWindow, and a \c main()
+    function in this example. A \c DropArea object is instantiated in
+    \c DropSiteWindow; a \c DropSiteWindow object is then invoked in the
+    \c main() function.
+
+    \section1 DropArea Class Definition
+
+    The \c DropArea class is a subclass of QLabel with a public slot,
+    \c clear(), and a \c changed() signal.
+
+    \snippet draganddrop/dropsite/droparea.h DropArea header part1
+
+    In addition, \c DropArea also contains a private instance of QLabel and
+    reimplementations of four \l{QWidget} event handlers:
+
+    \list 1
+        \li \l{QWidget::dragEnterEvent()}{dragEnterEvent()}
+        \li \l{QWidget::dragMoveEvent()}{dragMoveEvent()}
+        \li \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()}
+        \li \l{QWidget::dropEvent()}{dropEvent()}
+    \endlist
+
+    These event handlers are further explained in the implementation of the
+    \c DropArea class.
+
+    \snippet draganddrop/dropsite/droparea.h DropArea header part2
+
+    \section1 DropArea Class Implementation
+
+    In the \c DropArea constructor, we set the \l{QWidget::setMinimumSize()}
+    {minimum size} to 200x200 pixels, the \l{QFrame::setFrameStyle()}
+    {frame style} to both QFrame::Sunken and QFrame::StyledPanel, and we align
+    its contents to the center.
+
+    \snippet draganddrop/dropsite/droparea.cpp DropArea constructor
+
+    Also, we enable drop events in \c DropArea by setting the
+    \l{QWidget::acceptDrops()}{acceptDrops} property to \c true. Then,
+    we enable the \l{QWidget::autoFillBackground()}{autoFillBackground}
+    property and invoke the \c clear() function.
+
+    The \l{QWidget::dragEnterEvent()}{dragEnterEvent()} event handler is
+    called when a drag is in progress and the mouse enters the \c DropArea
+    object. For the \c DropSite example, when the mouse enters \c DropArea,
+    we set its text to "<drop content>" and highlight its background.
+
+    \snippet draganddrop/dropsite/droparea.cpp dragEnterEvent() function
+
+    Then, we invoke \l{QDropEvent::acceptProposedAction()}
+    {acceptProposedAction()} on \a event, setting the drop action to the one
+    proposed. Lastly, we emit the \c changed() signal, with the data that was
+    dropped and its MIME type information as a parameter.
+
+    For \l{QWidget::dragMoveEvent()}{dragMoveEvent()}, we just accept the
+    proposed QDragMoveEvent object, \a event, with
+    \l{QDropEvent::acceptProposedAction()}{acceptProposedAction()}.
+
+    \snippet draganddrop/dropsite/droparea.cpp dragMoveEvent() function
+
+    The \c DropArea class's implementation of \l{QWidget::dropEvent()}
+    {dropEvent()} extracts the \a{event}'s mime data and displays it
+    accordingly.
+
+    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part1
+
+    The \c mimeData object can contain one of the following objects: an image,
+    HTML text, plain text, or a list of URLs.
+
+    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part2
+
+    \list
+        \li If \c mimeData contains an image, we display it in \c DropArea with
+           \l{QLabel::setPixmap()}{setPixmap()}.
+        \li If \c mimeData contains HTML, we display it with
+           \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format
+           as Qt::RichText.
+        \li If \c mimeData contains plain text, we display it with
+           \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format
+           as Qt::PlainText. In the event that \c mimeData contains URLs, we
+           iterate through the list of URLs to display them on individual
+           lines.
+        \li If \c mimeData contains other types of objects, we set
+           \c{DropArea}'s text, with \l{QLabel::setText()}{setText()} to
+           "Cannot display data" to inform the user.
+    \endlist
+
+    We then set \c{DropArea}'s \l{QWidget::backgroundRole()}{backgroundRole} to
+    QPalette::Dark and we accept \c{event}'s proposed action.
+
+    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part3
+
+    The \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} event handler is
+    called when a drag is in progress and the mouse leaves the widget.
+
+    \snippet draganddrop/dropsite/droparea.cpp dragLeaveEvent() function
+
+    For \c{DropArea}'s implementation, we clear invoke \c clear() and then
+    accept the proposed event.
+
+    The \c clear() function sets the text in \c DropArea to "<drop content>"
+    and sets the \l{QWidget::backgroundRole()}{backgroundRole} to
+    QPalette::Dark. Lastly, it emits the \c changed() signal.
+
+    \snippet draganddrop/dropsite/droparea.cpp clear() function
+
+    \section1 DropSiteWindow Class Definition
+
+    The \c DropSiteWindow class contains a constructor and a public slot,
+    \c updateFormatsTable().
+
+    \snippet draganddrop/dropsite/dropsitewindow.h DropSiteWindow header
+
+    The class also contains a private instance of \c DropArea, \c dropArea,
+    QLabel, \c abstractLabel, QTableWidget, \c formatsTable, QDialogButtonBox,
+    \c buttonBox, and two QPushButton objects, \c clearButton and
+    \c quitButton.
+
+    \section1 DropSiteWindow Class Implementation
+
+    In the constructor of \c DropSiteWindow, we instantiate \c abstractLabel
+    and set its \l{QLabel::setWordWrap()}{wordWrap} property to \c true. We
+    also call the \l{QLabel::adjustSize()}{adjustSize()} function to adjust
+    \c{abstractLabel}'s size according to its contents.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part1
+
+    Then we instantiate \c dropArea and connect its \c changed() signal to
+    \c{DropSiteWindow}'s \c updateFormatsTable() slot.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part2
+
+    We now set up the QTableWidget object, \c formatsTable. Its
+    horizontal header is set using a QStringList object, \c labels. The number
+    of columms are set to two and the table is not editable. Also, the
+    \c{formatTable}'s horizontal header is formatted to ensure that its second
+    column stretches to occupy additional space available.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part3
+
+    Two QPushButton objects, \c clearButton and \c quitButton, are instantiated
+    and added to \c buttonBox - a QDialogButtonBox object. We use
+    QDialogButtonBox here to ensure that the push buttons are presented in a
+    layout that conforms to the platform's style.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part4
+
+    The \l{QPushButton::clicked()}{clicked()} signals for \c quitButton and
+    \c clearButton are connected to \l{QWidget::close()}{close()} and
+    \c clear(), respectively.
+
+    For the layout, we use a QVBoxLayout, \c mainLayout, to arrange our widgets
+    vertically. We also set the window title to "Drop Site" and the minimum
+    size to 350x500 pixels.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part5
+
+    We move on to the \c updateFormatsTable() function. This function updates
+    the \c formatsTable, displaying the MIME formats of the object dropped onto
+    the \c DropArea object. First, we set \l{QTableWidget}'s
+    \l{QTableWidget::setRowCount()}{rowCount} property to 0. Then, we validate
+    to ensure that the QMimeData object passed in is a valid object.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part1
+
+    Once we are sure that \c mimeData is valid, we iterate through its
+    supported formats using the \l{The foreach Keyword}{foreach keyword}.
+    This keyword has the following format:
+
+    \snippet code/doc_src_examples_dropsite.qdoc 0
+
+    In our example, \c format is the \a variable and the \a container is a
+    QStringList, obtained from \c mimeData->formats().
+
+    \note The \l{QMimeData::formats()}{formats()} function returns a
+    QStringList object, containing all the formats supported by the
+    \c mimeData.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part2
+
+    Within each iteration, we create a QTableWidgetItem, \c formatItem and we
+    set its \l{QTableWidgetItem::setFlags()}{flags} to Qt::ItemIsEnabled, and
+    its \l{QTableWidgetItem::setTextAlignment()}{text alignment} to Qt::AlignTop
+    and Qt::AlignLeft.
+
+    A QString object, \c text, is customized to display data according to the
+    contents of \c format. We invoke {QString}'s \l{QString::simplified()}
+    {simplified()} function on \c text, to obtain a string that has no
+    additional space before, after or in between words.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part3
+
+    If \c format contains a list of URLs, we iterate through them, using spaces
+    to separate them. On the other hand, if \c format contains an image, we
+    display the data by converting the text to hexadecimal.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part4
+
+    Once \c text has been customized to contain the appropriate data, we insert
+    both \c format and \c text into \c formatsTable with
+    \l{QTableWidget::setItem()}{setItem()}. Lastly, we invoke
+    \l{QTableView::resizeColumnToContents()}{resizeColumnToContents()} on
+    \c{formatsTable}'s first column.
+
+    \section1 The main() Function
+
+    Within the \c main() function, we instantiate \c DropSiteWindow and invoke
+    its \l{QWidget::show()}{show()} function.
+
+    \snippet draganddrop/dropsite/main.cpp main() function
+*/
diff --git a/examples/widgets/doc/images/dropsite-example.png b/examples/widgets/doc/images/dropsite-example.png
new file mode 100644
index 0000000000..42b988d733
--- /dev/null
+++ b/examples/widgets/doc/images/dropsite-example.png
diff --git a/examples/widgets/doc/images/mousebutton-buttontester.png b/examples/widgets/doc/images/mousebutton-buttontester.png
new file mode 100644
index 0000000000..82fcb7617f
--- /dev/null
+++ b/examples/widgets/doc/images/mousebutton-buttontester.png
diff --git a/examples/widgets/doc/images/orientation-landscape-ui.png b/examples/widgets/doc/images/orientation-landscape-ui.png
new file mode 100644
index 0000000000..c591ff14d2
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-landscape-ui.png
diff --git a/examples/widgets/doc/images/orientation-landscape.png b/examples/widgets/doc/images/orientation-landscape.png
new file mode 100644
index 0000000000..e606804d21
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-landscape.png
diff --git a/examples/widgets/doc/images/orientation-portrait-ui.png b/examples/widgets/doc/images/orientation-portrait-ui.png
new file mode 100644
index 0000000000..304835b93e
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-portrait-ui.png
diff --git a/examples/widgets/doc/images/orientation-portrait.png b/examples/widgets/doc/images/orientation-portrait.png
new file mode 100644
index 0000000000..3d778e8d90
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-portrait.png
diff --git a/examples/widgets/doc/mousebuttons.qdoc b/examples/widgets/doc/mousebuttons.qdoc
new file mode 100644
index 0000000000..10d1f9a116
--- /dev/null
+++ b/examples/widgets/doc/mousebuttons.qdoc
@@ -0,0 +1,94 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Copyright (C) 2012 Rick Stockton <rickstockton@reno-computerhelp.com>
+** 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/mousebuttons
+    \title Mouse Button Tester
+
+    \brief The 'Mouse Button Tester' example demonstrates how to reimplement
+    mouse events within a custom class. You can also use this program to
+    verify that Qt is actually receiving mouse events from your mouse.
+
+    Many 'gamer' mouse devices are configured with high-numbered "buttons"
+    sending text shortcuts for certain games. With such a mouse, no mouse
+    button events occur: The "mouse" sends keystrokes, and the
+    'Mouse Button Tester' Window will not see the event. Receiving no event,
+    it will not repaint the Window with new text describing a button event.
+
+    And so, in addition to it's use as Qt example code, the program may be
+    useful s a mouse device tester. Note that there is another example
+    mouse buttons example which provides the same function, written in QML.
+
+    This program (the Widget-based example) consists of three classes,
+    in addition to the main() parent program:
+
+    \list
+        \li \c A QPushButton, "Quit".
+        \li \c ButtonTester. This is derived from Qt's TextArea class, for
+            purpose of customizing/re-implementing the mouse and wheel event
+            member functions.
+        \li \c A simple QVBoxLayout layout.
+    \endlist
+
+    First we will review the main program, with it's layout and "Quit"
+    QPushButton. Then we will take a look at the \c ButtonTester class.
+
+    \section1 The Main Program
+
+    Note that the QPushButton, "Quit", is defined directly within the main()
+    program, rather than another class. This is a correct way of defining a
+    "Quit" QPushButton: A "Quit" Button defined inside another
+    class would result in the destructor of that second class being
+    called twice. This "Quit" Button uses the traditional Signal/Slot
+    connection to invoke termination of the QApp, which will properly destroy
+    its child classes before terminating itself.
+
+    The remainder of the main() program is concerned with defining the layout,
+    and applying a minimum size to the customized ButtonTester.
+
+    \section1 ButtonTester Class Definition
+
+    The \c ButtonTester class inherits from QTextEdit, and listens for
+    mouse events on all possible Qt::MouseButton values. It also listens for
+    wheel events from the mouse, and indicates the direction of wheel motion
+    ("up", down", "left", or "right"). It prints short debug messages into
+    the Window, and also on the console QDebug() stream, when mouse button
+    and wheel events occur. Our reimplementation of mousePressEvent(),
+    mouseReleaseEvent(), mouseDoubleClickEvent(), and wheelEvent() "drive"
+    the program; the other functions simply convert the Qt::MouseButton
+    values into text strings.
+
+    You should call the ignore() function on any mouse event (or other event)
+    which your widget-based classes do not use and consume. This function
+    assures that Qt will propagate the event through each parent widget,
+    until it is used or propagated to the Window Manager. (Qt attempts to do
+    this automatically, but it is better programming practice to explicitly
+    invoke the function.)
+
+    \image mousebutton-buttontester.png
+*/
diff --git a/examples/widgets/doc/orientation.qdoc b/examples/widgets/doc/orientation.qdoc
new file mode 100644
index 0000000000..b39bbf981a
--- /dev/null
+++ b/examples/widgets/doc/orientation.qdoc
@@ -0,0 +1,143 @@
+/****************************************************************************
+**
+** 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 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
+*/