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