← Back to branch summary

~gabriel1984sibiu/minitube/qt5.6

« back to all changes in this revision

Viewing changes to examples/widgets/doc/src/extension.qdoc

  • Committer: Grevutiu Gabriel
  • Date: 2017-06-13 08:43:17 UTC
  • Revision ID: gabriel1984sibiu@gmail.com-20170613084317-ek0zqe0u9g3ocvi8
Original upstream code

Show diffs side-by-side

added added

removed removed

Lines of Context:
examples/widgets/doc/src/extension.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2016 The Qt Company Ltd.
 
4
** Contact: https://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 https://www.qt.io/terms-conditions. For further
 
15
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
/*!
 
29
    \example dialogs/extension
 
30
    \title Extension Example
 
31
    \ingroup examples-dialogs
 
32
 
 
33
    \brief The Extension example shows how to add an extension to a QDialog
 
34
    using the QAbstractButton::toggled() signal and the
 
35
    QWidget::setVisible() slot.
 
36
 
 
37
    \image extension-example.png Screenshot of the Extension example
 
38
 
 
39
    The Extension application is a dialog that allows the user to
 
40
    perform a simple search as well as a more advanced search.
 
41
 
 
42
    The simple search has two options: \uicontrol {Match case} and \uicontrol
 
43
    {Search from start}. The advanced search options include the
 
44
    possibilities to search for \uicontrol {Whole words}, \uicontrol {Search
 
45
    backward} and \uicontrol {Search selection}. Only the simple search is
 
46
    visible when the application starts. The advanced search options
 
47
    are located in the application's extension part, and can be made
 
48
    visible by pressing the \uicontrol More button:
 
49
 
 
50
    \image extension_more.png Screenshot of the Extension example
 
51
 
 
52
    \section1 FindDialog Class Definition
 
53
 
 
54
    The \c FindDialog class inherits QDialog. The QDialog class is the
 
55
    base class of dialog windows. A dialog window is a top-level
 
56
    window mostly used for short-term tasks and brief communications
 
57
    with the user.
 
58
 
 
59
    \snippet dialogs/extension/finddialog.h 0
 
60
 
 
61
    The \c FindDialog widget is the main application widget, and
 
62
    displays the application's search options and controlling
 
63
    buttons.
 
64
 
 
65
    In addition to a constructor, we declare the several child
 
66
    widgets: We need a QLineEdit with an associated QLabel to let the
 
67
    user type a word to search for, we need several  \l
 
68
    {QCheckBox}{QCheckBox}es to facilitate the search options, and we
 
69
    need three \l {QPushButton}{QPushButton}s: the \uicontrol Find button to
 
70
    start a search and the \uicontrol More button to enable an advanced search.
 
71
    Finally, we need a QWidget representing the application's extension
 
72
    part.
 
73
 
 
74
    \section1 FindDialog Class Implementation
 
75
 
 
76
    In the constructor we first create the standard child widgets for
 
77
    the simple search: the QLineEdit with the associated QLabel, two
 
78
    of the \l {QCheckBox}{QCheckBox}es and all the \l
 
79
    {QPushButton}{QPushButton}s.
 
80
 
 
81
    \snippet dialogs/extension/finddialog.cpp 0
 
82
 
 
83
    We give the options and buttons a shortcut key using the &
 
84
    character. In the \uicontrol {Find what} option's case, we also need to
 
85
    use the QLabel::setBuddy() function to make the shortcut key work
 
86
    as expected; then, when the user presses the shortcut key
 
87
    indicated by the label, the keyboard focus is transferred to the
 
88
    label's buddy widget, the QLineEdit.
 
89
 
 
90
    We set the \uicontrol Find button's default property to true, using the
 
91
    QPushButton::setDefault() function. Then the push button will be
 
92
    pressed if the user presses the Enter (or Return) key. Note that a
 
93
    QDialog can only have one default button.
 
94
 
 
95
    \snippet dialogs/extension/finddialog.cpp 2
 
96
 
 
97
    Then we create the extension widget, and the \l
 
98
    {QCheckBox}{QCheckBox}es associated with the advanced search
 
99
    options.
 
100
 
 
101
    \snippet dialogs/extension/finddialog.cpp 3
 
102
 
 
103
    Now that the extension widget is created, we can connect the \uicontrol
 
104
    More button's \l{QAbstractButton::toggled()}{toggled()} signal to
 
105
    the extension widget's \l{QWidget::setVisible()}{setVisible()} slot.
 
106
 
 
107
    The QAbstractButton::toggled() signal is emitted whenever a
 
108
    checkable button changes its state. The signal's argument is true
 
109
    if the button is checked, or false if the button is unchecked. The
 
110
    QWidget::setVisible() slot sets the widget's visible status. If
 
111
    the status is true the widget is shown, otherwise the widget is
 
112
    hidden.
 
113
 
 
114
    Since we made the \uicontrol More button checkable when we created it,
 
115
    the connection makes sure that the extension widget is shown
 
116
    depending on the state of \uicontrol More button.
 
117
 
 
118
    We also put the check boxes associated with the advanced
 
119
    search options into a layout we install on the extension widget.
 
120
 
 
121
    \snippet dialogs/extension/finddialog.cpp 4
 
122
 
 
123
    Before we create the main layout, we create several child layouts
 
124
    for the widgets: First we align the QLabel and its buddy, the
 
125
    QLineEdit, using a QHBoxLayout. Then we vertically align the
 
126
    QLabel and QLineEdit with the check boxes associated with the
 
127
    simple search, using a QVBoxLayout. We also create a QVBoxLayout
 
128
    for the buttons. In the end we lay out the two latter layouts and
 
129
    the extension widget using a QGridLayout.
 
130
 
 
131
    \snippet dialogs/extension/finddialog.cpp 5
 
132
 
 
133
    Finally, we hide the extension widget using the QWidget::hide()
 
134
    function, making the application only show the simple search
 
135
    options when it starts. When the user wants to access the advanced
 
136
    search options, the dialog only needs to change the visibility of
 
137
    the extension widget. Qt's layout management takes care of the
 
138
    dialog's appearance.
 
139
*/