1QDialog(3qt) QDialog(3qt)
2
6 QDialog - The base class of dialog windows
7
9 #include <qdialog.h>
10 Inherits QWidget.
12 Inherited by QColorDialog, QErrorMessage, QFileDialog, QFontDialog,
14 QInputDialog, QMessageBox, QMotifDialog, QProgressDialog, QTabDialog,
15 and QWizard.
16 Public Members
18 explicit QDialog ( QWidget * parent = 0, const char * name = 0, bool
19 modal = FALSE, WFlags f = 0 )
20 ~QDialog ()
21 enum DialogCode { Rejected, Accepted }
22 int result () const
23 virtual void show ()
24 void setOrientation ( Orientation orientation )
25 Orientation orientation () const
26 void setExtension ( QWidget * extension )
27 QWidget * extension () const
28 void setSizeGripEnabled ( bool )
29 bool isSizeGripEnabled () const
30 void setModal ( bool modal )
31 bool isModal () const
32 Public Slots
34 int exec ()
35 Properties
37 bool modal - whether show() should pop up the dialog as modal or
38 modeless
39 bool sizeGripEnabled - whether the size grip is enabled
40 Protected Members
42 void setResult ( int i )
43 Protected Slots
45 virtual void done ( int r )
46 virtual void accept ()
47 virtual void reject ()
48 void showExtension ( bool showIt )
49
51 The QDialog class is the base class of dialog windows.
52 A dialog window is a top-level window mostly used for short-term tasks
54 and brief communications with the user. QDialogs may be modal or
55 modeless. QDialogs support extensibility and can provide a return
56 value. They can have default buttons. QDialogs can also have a
57 QSizeGrip in their lower-right corner, using setSizeGripEnabled().
58 Note that QDialog uses the parent widget slightly differently from
60 other classes in Qt. A dialog is always a top-level widget, but if it
61 has a parent, its default location is centered on top of the parent's
62 top-level widget (if it is not top-level itself). It will also share
63 the parent's taskbar entry.
64
66 A modal dialog is a dialog that blocks input to other visible windows
67 in the same application. Users must finish interacting with the dialog
68 and close it before they can access any other window in the
69 application. Dialogs that are used to request a file name from the user
70 or that are used to set application preferences are usually modal.
71 The most common way to display a modal dialog is to call its exec()
73 function. When the user closes the dialog, exec() will provide a useful
74 return value. Typically we connect a default button, e.g. "OK", to the
75 accept() slot and a" Cancel" button to the reject() slot, to get the
76 dialog to close and return the appropriate value. Alternatively you can
77 connect to the done() slot, passing it Accepted or Rejected.
78 An alternative is to call setModal(TRUE), then show(). Unlike exec(),
80 show() returns control to the caller immediately. Calling
81 setModal(TRUE) is especially useful for progress dialogs, where the
82 user must have the ability to interact with the dialog, e.g. to cancel
83 a long running operation. If you use show() and setModal(TRUE) together
84 you must call QApplication::processEvents() periodically during
85 processing to enable the user to interact with the dialog. (See
86 QProgressDialog.)
87
89 A modeless dialog is a dialog that operates independently of other
90 windows in the same application. Find and replace dialogs in word-
91 processors are often modeless to allow the user to interact with both
92 the application's main window and with the dialog.
93 Modeless dialogs are displayed using show(), which returns control to
95 the caller immediately.
96
98 A dialog's default button is the button that's pressed when the user
99 presses Enter (Return). This button is used to signify that the user
100 accepts the dialog's settings and wants to close the dialog. Use
101 QPushButton::setDefault(), QPushButton::isDefault() and
102 QPushButton::autoDefault() to set and control the dialog's default
103 button.
104
106 If the user presses the Esc key in a dialog, QDialog::reject() will be
107 called. This will cause the window to close: the closeEvent cannot be
108 ignored.
109
111 Extensibility is the ability to show the dialog in two ways: a partial
112 dialog that shows the most commonly used options, and a full dialog
113 that shows all the options. Typically an extensible dialog will
114 initially appear as a partial dialog, but with a" More" toggle button.
115 If the user presses the "More" button down, the full dialog will
116 appear. The extension widget will be resized to its sizeHint(). If
117 orientation is Horizontal the extension widget's height() will be
118 expanded to the height() of the dialog. If the orientation is Vertical
119 the extension widget's width() will be expanded to the width() of the
120 dialog. Extensibility is controlled with setExtension(),
121 setOrientation() and showExtension().
122
124 Modal dialogs are often used in situations where a return value is
125 required, e.g. to indicate whether the user pressed "OK" or" Cancel". A
126 dialog can be closed by calling the accept() or the reject() slots, and
127 exec() will return Accepted or Rejected as appropriate. The exec() call
128 returns the result of the dialog. The result is also available from
129 result() if the dialog has not been destroyed. If the WDestructiveClose
130 flag is set, the dialog is deleted after exec() returns.
131
133 A modal dialog.
134 QFileDialog *dlg = new QFileDialog( workingDirectory,
136 QString::null, 0, 0, TRUE );
137 dlg->setCaption( QFileDialog::tr( "Open" ) );
138 dlg->setMode( QFileDialog::ExistingFile );
139 QString result;
140 if ( dlg->exec() == QDialog::Accepted ) {
141 result = dlg->selectedFile();
142 workingDirectory = dlg->url();
143 }
144 delete dlg;
145 return result;
146 A modeless dialog. After the show() call, control returns to the main
148 event loop.
149 int main( int argc, char **argv )
151 {
152 QApplication a( argc, argv );
153 int scale = 10;
155 LifeDialog *life = new LifeDialog( scale );
157 a.setMainWidget( life );
158 life->setCaption("Qt Example - Life");
159 life->show();
160 return a.exec();
162 }
163 See also QTabDialog, QWidget, QProgressDialog, GUI Design Handbook:
165 Dialogs, Standard, Abstract Widget Classes, and Dialog Classes.
166 Member Type Documentation
169 The value returned by a modal dialog.
170 QDialog::Accepted
172 QDialog::Rejected
174
177 modal = FALSE, WFlags f = 0 )
178 Constructs a dialog called name, with parent parent.
179 A dialog is always a top-level widget, but if it has a parent, its
181 default location is centered on top of the parent. It will also share
182 the parent's taskbar entry.
183 The widget flags f are passed on to the QWidget constructor. If, for
185 example, you don't want a What's This button in the titlebar of the
186 dialog, pass WStyle_Customize | WStyle_NormalBorder | WStyle_Title |
187 WStyle_SysMenu in f.
188 Warning: In Qt 3.2, the modal flag is obsolete. There is now a
190 setModal() function that can be used for obtaining a modal behavior
191 when calling show(). This is rarely needed, because modal dialogs are
192 usually invoked using exec(), which ignores the modal flag.
193 See also QWidget::setWFlags() and Qt::WidgetFlags.
195
197 Destroys the QDialog, deleting all its children.
198
200 Hides the modal dialog and sets the result code to Accepted.
201 See also reject() and done().
203 Examples:
205
207 Closes the dialog and sets its result code to r. If this dialog is
208 shown with exec(), done() causes the local event loop to finish, and
209 exec() to return r.
210 As with QWidget::close(), done() deletes the dialog if the
212 WDestructiveClose flag is set. If the dialog is the application's main
213 widget, the application terminates. If the dialog is the last window
214 closed, the QApplication::lastWindowClosed() signal is emitted.
215 See also accept(), reject(), QApplication::mainWidget(), and
217 QApplication::quit().
218
220 Shows the dialog as a modal dialog, blocking until the user closes it.
221 The function returns a DialogCode result.
222 Users cannot interact with any other window in the same application
224 until they close the dialog.
225 See also show() and result().
227 Examples:
229
231 Returns the dialog's extension or 0 if no extension has been defined.
232 See also setExtension().
234
236 Returns TRUE if show() should pop up the dialog as modal or modeless;
237 otherwise returns FALSE. See the "modal" property for details.
238
240 Returns TRUE if the size grip is enabled; otherwise returns FALSE. See
241 the "sizeGripEnabled" property for details.
242
244 Returns the dialog's extension orientation.
245 See also setOrientation().
247
249 Hides the modal dialog and sets the result code to Rejected.
250 See also accept() and done().
252
254 Returns the modal dialog's result code, Accepted or Rejected.
255 Do not call this function if the dialog was constructed with the
257 WDestructiveClose flag.
258
260 Sets the widget, extension, to be the dialog's extension, deleting any
261 previous extension. The dialog takes ownership of the extension. Note
262 that if 0 is passed any existing extension will be deleted.
263 This function must only be called while the dialog is hidden.
265 See also showExtension(), setOrientation(), and extension().
267
269 Sets whether show() should pop up the dialog as modal or modeless to
270 modal. See the "modal" property for details.
271
273 If orientation is Horizontal, the extension will be displayed to the
274 right of the dialog's main area. If orientation is Vertical, the
275 extension will be displayed below the dialog's main area.
276 See also orientation() and setExtension().
278
280 Sets the modal dialog's result code to i.
281
283 Sets whether the size grip is enabled. See the "sizeGripEnabled"
284 property for details.
285
287 Shows the dialog as a modeless dialog. Control returns immediately to
288 the calling code.
289 The dialog will be modal or modeless according to the value of the
291 modal property.
292 See also exec() and modal.
294 Examples:
296 Reimplemented from QWidget.
298
300 If showIt is TRUE, the dialog's extension is shown; otherwise the
301 extension is hidden.
302 This slot is usually connected to the QButton::toggled() signal of a
304 QPushButton.
305 A dialog with a visible extension is not resizeable.
307 See also show(), setExtension(), and setOrientation().
309 Property Documentation
312 This property holds whether show() should pop up the dialog as modal or
313 modeless.
314 By default, this property is false and show() pops up the dialog as
316 modeless.
317 exec() ignores the value of this property and always pops up the dialog
319 as modal.
320 See also show() and exec().
322 Set this property's value with setModal() and get this property's value
324 with isModal().
325
327 This property holds whether the size grip is enabled.
328 A QSizeGrip is placed in the bottom right corner of the dialog when
330 this property is enabled. By default, the size grip is disabled.
331 Set this property's value with setSizeGripEnabled() and get this
333 property's value with isSizeGripEnabled().
334
337 http://doc.trolltech.com/qdialog.html
338 http://www.trolltech.com/faq/tech.html
339
341 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
342 license file included in the distribution for a complete license
343 statement.
344
346 Generated automatically from the source code.
347
349 If you find a bug in Qt, please report it as described in
350 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
351 help you. Thank you.
352 The definitive Qt documentation is provided in HTML format; it is
354 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
355 web browser. This man page is provided as a convenience for those users
356 who prefer man pages, although this format is not officially supported
357 by Trolltech.
358 If you find errors in this manual page, please report them to qt-
360 bugs@trolltech.com. Please include the name of the manual page
361 (qdialog.3qt) and the Qt version (3.3.8).
362Trolltech AS 2 February 2007 QDialog(3qt)