qt5base-lts/examples/widgets/doc/tabdialog.qdoc

/****************************************************************************
**
** 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 dialogs/tabdialog
    \title Tab Dialog Example

    The Tab Dialog example shows how to construct a tab dialog using the
    QTabWidget class.

    Dialogs provide an efficient way for the application to communicate
    with the user, but complex dialogs suffer from the problem that they
    often take up too much screen area. By using a number of tabs in a
    dialog, information can be split into different categories, while
    remaining accessible.

    \image tabdialog-example.png

    The Tab Dialog example consists of a single \c TabDialog class that
    provides three tabs, each containing information about a particular
    file, and two standard push buttons that are used to accept or reject
    the contents of the dialog.

    \section1 TabDialog Class Definition

    The \c TabDialog class is a subclass of QDialog that displays a
    QTabWidget and two standard dialog buttons. The class definition
    only contain the class constructor and a private data member for
    the QTabWidget:

    \snippet dialogs/tabdialog/tabdialog.h 3

    In the example, the widget will be used as a top-level window, but
    we define the constructor so that it can take a parent widget. This
    allows the dialog to be centered on top of an application's main
    window.

    \section1 TabDialog Class Implementation

    The constructor calls the QDialog constructor and creates a QFileInfo
    object for the specified filename.

    \snippet dialogs/tabdialog/tabdialog.cpp 0

    The tab widget is populated with three custom widgets that each
    contain information about the file. We construct each of these
    without a parent widget because the tab widget will reparent
    them as they are added to it.

    We create two standard push buttons, and connect each of them to
    the appropriate slots in the dialog:

    \snippet dialogs/tabdialog/tabdialog.cpp 1
    \snippet dialogs/tabdialog/tabdialog.cpp 3

    We arrange the tab widget above the buttons in the dialog:

    \snippet dialogs/tabdialog/tabdialog.cpp 4

    Finally, we set the dialog's title:

    \snippet dialogs/tabdialog/tabdialog.cpp 5

    Each of the tabs are subclassed from QWidget, and only provide
    constructors.

    \section1 GeneralTab Class Definition

    The GeneralTab widget definition is simple because we are only interested
    in displaying the contents of a widget within a tab:

    \snippet dialogs/tabdialog/tabdialog.h 0

    \section1 GeneralTab Class Implementation

    The GeneralTab widget simply displays some information about the file
    passed by the TabDialog. Various widgets for this purpose, and these
    are arranged within a vertical layout:

    \snippet dialogs/tabdialog/tabdialog.cpp 6

    \section1 PermissionsTab Class Definition

    Like the GeneralTab, the PermissionsTab is just used as a placeholder
    widget for its children:

    \snippet dialogs/tabdialog/tabdialog.h 1

    \section1 PermissionsTab Class Implementation

    The PermissionsTab shows information about the file's access information,
    displaying details of the file permissions and owner in widgets that are
    arranged in nested layouts:

    \snippet dialogs/tabdialog/tabdialog.cpp 7

    \section1 ApplicationsTab Class Definition

    The ApplicationsTab is another placeholder widget that is mostly
    cosmetic:

    \snippet dialogs/tabdialog/tabdialog.h 2

    \section1 ApplicationsTab Class Implementation

    The ApplicationsTab does not show any useful information, but could be
    used as a template for a more complicated example:

    \snippet dialogs/tabdialog/tabdialog.cpp 8
*/