// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page qtwidgets-index.html
\title Qt Widgets
\brief A module which provides a set of C++ technologies for building user
interfaces

    The \l {Qt Widgets C++ Classes}{Qt Widgets Module} provides a set of UI
    elements to create classic desktop-style user interfaces. See the
    \l {User Interfaces} overview for more information on using widgets.

    \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. To create custom widgets, subclass QWidget or a
    suitable subclass and reimplement the virtual event handlers.

    \list
    \li \l{Window and Dialog Widgets}
    \li \l{Application Main Window}
    \li \l{Dialog Windows}
    \li \l{Keyboard Focus in Widgets}
    \endlist

    \section1 Styles

    \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.

    \table
    \row
    \li \image windowsvista-tabwidget.png
    \li \image fusion-tabwidget.png
    \li \image macos-tabwidget.png
    \endtable

    \l{Qt Style Sheets} are a powerful mechanism that lets you customize
    the appearance of widgets, in addition to what is already possible by
    subclassing QStyle.


    \section1 Layouts

    \l{Layout Management}{Layouts} are an elegant and flexible way to
    automatically arrange child widgets within their container. Each
    widget reports its size requirements to the layout through the
    \l{QWidget::}{sizeHint} and \l{QWidget::}{sizePolicy} properties,
    and the layout distributes the available space accordingly.

    \table
    \row
    \li \image qgridlayout-with-5-children.png
    \li \image qformlayout-with-6-children.png
    \endtable

    \l {Qt Widgets Designer} is a powerful tool for interactively creating and
    arranging widgets in layouts.



    \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 windows-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 Using the Module

    \include {module-use.qdocinc} {using the c++ api}

    \section2 Building with CMake

    \include {module-use.qdocinc} {building with cmake} {Widgets}

    \section2 Building with qmake

    \include {module-use.qdocinc} {building_with_qmake} {widgets}

    \section1 Articles and Guides

    \list
        \li \l{Widgets Tutorial}
        \li \l{Getting Started Programming with Qt Widgets}
        \li \l{Creating a Qt Widget Based Application}
        \li \l{Model/View Tutorial}
    \endlist

    \section1 Examples

    \list
        \li \l{Qt Widgets Examples}
        \li \l{Layout Examples}
        \li \l{Tools Examples}
    \endlist

    \section1 API Reference

    \list
        \li \l{Qt Widgets C++ Classes}
        \list
            \li \l{Basic Widget Classes}
            \li \l{Advanced Widget Classes}
            \li \l{Abstract Widget Classes}
            \li \l{Organizer 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

    \section1 Module Evolution

    \l{Changes to Qt Widgets} lists important changes in the module API
    and functionality that were done for the Qt 6 series of Qt.

    \section1 Licenses

    The Qt Widgets module is available under commercial licenses from \l{The Qt Company}.
    In addition, it is available under free software licenses:
    The \l{GNU Lesser General Public License, version 3}, or
    the \l{GNU General Public License, version 2}.
    See \l{Qt Licensing} for further details.
*/