Doc: Added landing-, examples- and C++ class list-page to qtwidgets

It seems this is the pattern to follow:
landing page:    qtwidgets-index.html
examples page:   qtwidgets-examples.html
class list page: qtwidgets-module.html

Change-Id: I3e5459fe650178e0398cb43181b594c0f12a170e
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

doc/global/qt-module-defaults.qdocconf

@@ -95,3 +95,4 @@ sources.fileextensions  = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc"
 
 versionsym              = QT_VERSION_STR
 
+macro.raisedaster.HTML  = "<sup>*</sup>"

examples/widgets/doc/src/analogclock.qdoc

@@ -28,9 +28,9 @@
 /*!
     \example widgets/analogclock
     \title Analog Clock Example
-
+    \ingroup examples-widgets
-    The Analog Clock example shows how to draw the contents of a custom
+    \brief The Analog Clock example shows how to draw the contents of a
-    widget.
+    custom widget.
 
     \image analogclock-example.png Screenshot of the Analog Clock example
 

src/widgets/doc/snippets/widgets-tutorial/template.cpp

@@ -39,7 +39,7 @@
 ****************************************************************************/
 
 //! [main.cpp body]
-#include <QtGui>
+#include <QtWidgets>
 
 // Include header files for application components.
 // ...

src/widgets/doc/src/qtwidgets-examples.qdoc

@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \page qtwidgets-examples.html
+    \title Qt Widgets Examples
+    \brief Lots of examples of how to use different kinds of widgets.
+    \ingroup all-examples
+
+    \image widget-examples.png
+
+    Qt comes with a large range of standard widgets that users of modern
+    applications have come to expect.
+
+    You can also develop your own custom widgets and controls, and use them
+    alongside standard widgets.
+
+    It is even possible to provide custom styles and themes for widgets that can
+    be used to change the appearance of standard widgets and appropriately
+    written custom widgets.
+
+    \list
+    \li \l{widgets/analogclock}{Analog Clock}\raisedaster
+    \li \l{widgets/calculator}{Calculator}\raisedaster
+    \li \l{widgets/calendarwidget}{Calendar Widget}\raisedaster
+    \li \l{widgets/charactermap}{Character Map}\raisedaster
+    \li \l{widgets/codeeditor}{Code Editor}\raisedaster
+    \li \l{widgets/digitalclock}{Digital Clock}\raisedaster
+    \li \l{widgets/groupbox}{Group Box}\raisedaster
+    \li \l{widgets/icons}{Icons}\raisedaster
+    \li \l{widgets/imageviewer}{Image Viewer}\raisedaster
+    \li \l{widgets/lineedits}{Line Edits}\raisedaster
+    \li \l{widgets/movie}{Movie}
+    \li \l{widgets/scribble}{Scribble}\raisedaster
+    \li \l{widgets/shapedclock}{Shaped Clock}\raisedaster
+    \li \l{widgets/sliders}{Sliders}\raisedaster
+    \li \l{widgets/softkeys}{Soft Keys}
+    \li \l{widgets/spinboxes}{Spin Boxes}\raisedaster
+    \li \l{widgets/styles}{Styles}\raisedaster
+    \li \l{widgets/stylesheet}{Style Sheet}\raisedaster
+    \li \l{widgets/tablet}{Tablet}\raisedaster
+    \li \l{widgets/tetrix}{Tetrix}\raisedaster
+    \li \l{widgets/tooltips}{Tooltips}\raisedaster
+    \li \l{widgets/validators}{Validators}
+    \li \l{widgets/wiggly}{Wiggly}\raisedaster
+    \li \l{widgets/windowflags}{Window Flags}\raisedaster
+    \endlist
+
+    Examples marked with an asterisk (*) are fully documented.
+
+*/

src/widgets/doc/src/qtwidgets-index.qdoc

@@ -31,9 +31,6 @@
 \brief A module which provides a set of C++ technologies for building user
 interfaces
 
-Qt Widgets is a module which provides primary elements for building user
-interfaces in C++.
-
 \section1 Getting Started
 
     To include the definitions of the module's classes, use the
@@ -46,93 +43,133 @@ interfaces in C++.
 
     \snippet code/doc_src_qtwidgets.pro 0
 
-\section1 Widgets
 
-    Widgets are for building C++ user interfaces. They are customizable with
+
-    layouts and stylesheets.
+
+    \section1 Widgets
+
+    Widgets are the primary elements for creating user interfaces in Qt.
+    \l{The Widget Classes}{Widgets} can display data and status information,
+    receive user input, and provide a container for other widgets that
+    should be grouped together. A widget that is not embedded in a
+    parent widget is called a \l{Window and Dialog Widgets} {window}.
+
+    \image parent-child-widgets.png A parent widget containing various child widgets.
+
+    The QWidget class provides the basic capability to render to the
+    screen, and to handle user input events. All UI elements that Qt
+    provides are either subclasses of QWidget, or are used in connection
+    with a QWidget subclass. Creating custom widgets is done by
+    subclassing QWidget or a suitable subclass and reimplementing the
+    virtual event handlers.
 
     \list
-    \li \l{Basic Widgets}
-    \li \l{Advanced Widgets}
-    \li \l{Organizers}
-    \li \l{Widgets Tutorial}
     \li \l{Window and Dialog Widgets}
     \li \l{Application Main Window}
-    \li \l{Standard Dialogs}
     \li \l{Dialog Windows}
     \endlist
 
-    Qt's support for widget styles and themes enables your application to fit in
+    \section1 Styles
-    with the native desktop environment. Below, you can find links to the
-    various widget styles that are supplied with Qt Widgets.
-    \list
-    \li \l{Qt Widget Gallery}
-    \li \l{Plastique Style Widget Gallery}
-    \li \l{Cleanlooks Style Widget Gallery}
-    \li \l{Windows XP Style Widget Gallery}
-    \li \l{Windows Vista Style Widget Gallery}
-    \li \l{GTK Style Widget Gallery}
-    \li \l{Macintosh Style Widget Gallery}
-    \endlist
 
-    \section2 Layouts
+    \l{Styles and Style Aware Widgets}{Styles} draw on behalf of
+    widgets and encapsulate the look and feel of a GUI. Qt's built-in
+    widgets use the QStyle class to perform nearly all of their drawing,
+    ensuring that they look exactly like the equivalent native widgets.
 
-    Widgets may use to automatically arrange child widgets within their
+    \table
-    container. Each widget reports its size requirements to the layout and the
+    \row
-    layout distributes the available space accordingly.
+    \li \image windowsxp-tabwidget.png
+    \li \image plastique-tabwidget.png
+    \li \image macintosh-tabwidget.png
+    \endtable
 
-    \list
+    \l{Qt Style Sheets} are a powerful mechanism that allows you to customize the
-    \li \l{Widgets and Layouts}
+    appearance of widgets, in addition to what is already possible by subclassing QStyle.
-    \li \l{Qt Designer Integration}
-    \li \l{Layout Management}
-    \endlist
 
-    \section2 Style Sheets
 
-    \l{Qt Style Sheets} are a powerful mechanism that allows for customization
+    \section1 Layouts
-    of the appearance of widgets. The concepts, terminology, and syntax of Qt
-    Style Sheets are heavily inspired by HTML Cascading Style Sheets (CSS) but
-    adapted to the world of widgets.
 
-    \list
+    \l{Layout Management}{Layouts} are an elegant and flexible way to
-    \li \l{Customizing Qt Widgets Using Style Sheets}
+    automatically arrange child widgets within their container. Each
-    \li \l{Qt Style Sheets}
+    widget reports its size requirements to the layout through the
-    \li \l{The Style Sheet Syntax}
+    \l{QWidget::}{sizeHint} and \l{QWidget::}{sizePolicy} properties,
-    \li \l{Styles and Style Aware Widgets}
+    and the layout distributes the available space accordingly.
-    \li \l{Qt Style Sheets Examples}
-    \endlist
 
-\section1 Graphics View
+    \table
+    \row
+    \li \image qgridlayout-with-5-children.png
+    \li \image qformlayout-with-6-children.png
+    \endtable
 
-    The \l{Graphics View Framework} is for managing and interacting with a large
+    \l {Qt Designer} is a powerful tool for interactively creating and
-    number of custom-made 2D graphical items, and a view widget for visualizing
+    arranging widgets in layouts.
-    the items, with support for zooming and rotation.
 
-\section1 Model/View
+
+
+    \section1 Model/View Classes
 
     The \l{Model/View Programming}{model/view} architecture provides classes
     that manage the way data is presented to the user. Data-driven applications
     which use lists and tables are structured to separate the data and view
     using models, views, and delegates.
 
+    \image windowsxp-treeview.png
+
+    \section1 Graphics View
+
+    The \l{Graphics View Framework} is for managing and interacting with a large
+    number of custom-made 2D graphical items, and a view widget for visualizing
+    the items, with support for zooming and rotation.
+
+    \image graphicsview-items.png
+
+    \section1 Related Information
+
+        \section2 Tutorials
     \list
-    \li \l{Model/View Programming}
+        \li \l{Widgets Tutorial}
-    \li \l{Model/View Tutorial}
+        \li \l{Model/View Tutorial}
     \endlist
 
-\section1 Reference
+    \section2 Examples
-
-\list
-\li \l{Qt Widgets C++ API}
     \list
-    \li \l{Abstract Widget Classes}
+        \li \l{Qt Widgets Examples}
-    \li \l{Graphics View Classes}
-    \li \l{Model/View Classes}
-    \li \l{Main Window and Related Classes}
-    \li \l{Widget Appearance and Style Related Classes}
-    \li \l{Layout Classes}
     \endlist
-\li \l{Qt Style Sheets Reference}
+    \section2 API Reference
-\endlist
+    These are links to the API reference materials.
+
+    \list
+        \li \l{Qt Widgets C++ Classes}
+        \list
+            \li \l{Abstract Widget Classes}
+            \li \l{Graphics View Classes}
+            \li \l{Model/View Classes}
+            \li \l{Main Window and Related Classes}
+            \li \l{Widget Appearance and Style Related Classes}
+            \li \l{Layout Classes}
+        \endlist
+        \li \l{Qt Style Sheets Reference}
+    \endlist
+
 
 */
+
+    /*!
+    \group advanced
+    \title Advanced Widgets
+    */
+
+    /*!
+    \group abstractwidgets
+    \title Abstract Widget Classes
+    */
+
+    /*!
+    \group basicwidgets
+    \title Basic Widgets
+    */
+
+    /*!
+    \group organizers
+    \title Organizers
+    */

src/widgets/doc/src/qtwidgets.qdoc

@@ -27,7 +27,7 @@
 
 /*!
     \module QtWidgets
-    \title Qt Widgets C++ API
+    \title Qt Widgets C++ Classes
     \ingroup modules
 
     \brief The QtWidgets module extends Qt Gui with C++ widget functionality.

src/widgets/doc/src/widgets-and-layouts/gallery.qdoc

@@ -32,7 +32,7 @@
 
   Qt's support for widget styles and themes enables your application to fit in
   with the native desktop environment. Below, you can find links to the various
-  widget styles that are supplied with Qt 4.
+  widget styles that are supplied with Qt.
 
   \table
   \row