doc/src/examples/tabdialog.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example dialogs/tabdialog
  30     \title Tab Dialog Example
  31
  32     \brief The Tab Dialog example shows how to construct a tab dialog using the
  33     QTabWidget class.
  34
  35     Dialogs provide an efficient way for the application to communicate
  36     with the user, but complex dialogs suffer from the problem that they
  37     often take up too much screen area. By using a number of tabs in a
  38     dialog, information can be split into different categories, while
  39     remaining accessible.
  40
  41     \image tabdialog-example.png
  42
  43     The Tab Dialog example consists of a single \c TabDialog class that
  44     provides three tabs, each containing information about a particular
  45     file, and two standard push buttons that are used to accept or reject
  46     the contents of the dialog.
  47
  48     \section1 TabDialog Class Definition
  49
  50     The \c TabDialog class is a subclass of QDialog that displays a
  51     QTabWidget and two standard dialog buttons. The class definition
  52     only contain the class constructor and a private data member for
  53     the QTabWidget:
  54
  55     \snippet examples/dialogs/tabdialog/tabdialog.h 3
  56
  57     In the example, the widget will be used as a top-level window, but
  58     we define the constructor so that it can take a parent widget. This
  59     allows the dialog to be centered on top of an application's main
  60     window.
  61
  62     \section1 TabDialog Class Implementation
  63
  64     The constructor calls the QDialog constructor and creates a QFileInfo
  65     object for the specified filename.
  66
  67     \snippet examples/dialogs/tabdialog/tabdialog.cpp 0
  68
  69     The tab widget is populated with three custom widgets that each
  70     contain information about the file. We construct each of these
  71     without a parent widget because the tab widget will reparent
  72     them as they are added to it.
  73
  74     We create two standard push buttons, and connect each of them to
  75     the appropriate slots in the dialog:
  76
  77     \snippet examples/dialogs/tabdialog/tabdialog.cpp 1
  78     \snippet examples/dialogs/tabdialog/tabdialog.cpp 3
  79
  80     We arrange the tab widget above the buttons in the dialog:
  81
  82     \snippet examples/dialogs/tabdialog/tabdialog.cpp 4
  83
  84     Finally, we set the dialog's title:
  85
  86     \snippet examples/dialogs/tabdialog/tabdialog.cpp 5
  87
  88     Each of the tabs are subclassed from QWidget, and only provide
  89     constructors.
  90
  91     \section1 GeneralTab Class Definition
  92
  93     The GeneralTab widget definition is simple because we are only interested
  94     in displaying the contents of a widget within a tab:
  95
  96     \snippet examples/dialogs/tabdialog/tabdialog.h 0
  97
  98     \section1 GeneralTab Class Implementation
  99
 100     The GeneralTab widget simply displays some information about the file
 101     passed by the TabDialog. Various widgets for this purpose, and these
 102     are arranged within a vertical layout:
 103
 104     \snippet examples/dialogs/tabdialog/tabdialog.cpp 6
 105
 106     \section1 PermissionsTab Class Definition
 107
 108     Like the GeneralTab, the PermissionsTab is just used as a placeholder
 109     widget for its children:
 110
 111     \snippet examples/dialogs/tabdialog/tabdialog.h 1
 112
 113     \section1 PermissionsTab Class Implementation
 114
 115     The PermissionsTab shows information about the file's access information,
 116     displaying details of the file permissions and owner in widgets that are
 117     arranged in nested layouts:
 118
 119     \snippet examples/dialogs/tabdialog/tabdialog.cpp 7
 120
 121     \section1 ApplicationsTab Class Definition
 122
 123     The ApplicationsTab is another placeholder widget that is mostly
 124     cosmetic:
 125
 126     \snippet examples/dialogs/tabdialog/tabdialog.h 2
 127
 128     \section1 ApplicationsTab Class Implementation
 129
 130     The ApplicationsTab does not show any useful information, but could be
 131     used as a template for a more complicated example:
 132
 133     \snippet examples/dialogs/tabdialog/tabdialog.cpp 8
 134 */